workspace

Documentation

Overview

Package workspace provides functions for interacting with a temporary MySQL schema. It manages creating a schema on a desired location (either an existing MySQL instance, or a dynamically-controlled Docker instance), running SQL DDL or DML, introspecting the resulting schema, and cleaning up the schema when it is no longer needed.

Index

• func RegisterShutdownFunc(f ShutdownFunc)
• func Shutdown(args ...interface{})
• type CleanupAction
• type LocalDocker
  • func NewLocalDocker(opts Options) (ld *LocalDocker, err error)
  • func (ld *LocalDocker) Cleanup() error
  • func (ld *LocalDocker) ConnectionPool(params string) (*sqlx.DB, error)
  • func (ld *LocalDocker) IntrospectSchema() (*tengo.Schema, error)
• type Options
  • func OptionsForDir(dir *fs.Dir, instance *tengo.Instance) (Options, error)
• type ShutdownFunc
• type StatementError
  • func ExecLogicalSchema(logicalSchema *fs.LogicalSchema, opts Options) (schema *tengo.Schema, statementErrors []*StatementError, fatalErr error)
  • func (se *StatementError) Error() string
  • func (se *StatementError) String() string
• type TempSchema
  • func NewTempSchema(opts Options) (ts *TempSchema, err error)
  • func (ts *TempSchema) Cleanup() error
  • func (ts *TempSchema) ConnectionPool(params string) (*sqlx.DB, error)
  • func (ts *TempSchema) IntrospectSchema() (*tengo.Schema, error)
• type Type
• type Workspace
  • func New(opts Options) (Workspace, error)

Functions

func RegisterShutdownFunc

func RegisterShutdownFunc(f ShutdownFunc)

RegisterShutdownFunc registers a function to be executed by Shutdown. Structs satisfying the Workspace interface may optionally use this function to track actions to perform at shutdown time, such as stopping or destroying containers.

func Shutdown

func Shutdown(args ...interface{})

Shutdown performs any necessary cleanup operations prior to the program exiting. For example, if containers need to be stopped or destroyed, it is most efficient to do so at program exit, rather than needlessly doing so for each workspace invocation. It is recommended that programs importing this package call Shutdown as a deferred function in main().

Types

type CleanupAction

type CleanupAction int

CleanupAction represents how to clean up a workspace.

const (
	// CleanupActionNone means to perform no special cleanup
	CleanupActionNone CleanupAction = iota

	// CleanupActionDrop means to drop the schema in Workspace.Cleanup(). Only
	// used with TypeTempSchema.
	CleanupActionDrop

	// CleanupActionStop means to stop the MySQL instance container in Shutdown().
	// Only used with TypeLocalDocker.
	CleanupActionStop

	// CleanupActionDestroy means to destroy the MySQL instance container in
	// Shutdown(). Only used with TypeLocalDocker.
	CleanupActionDestroy
)

Constants enumerating different cleanup actions. These may affect the behavior of Workspace.Cleanup() and/or Shutdown().

type LocalDocker

type LocalDocker struct {
	// contains filtered or unexported fields
}

LocalDocker is a Workspace created inside of a Docker container on localhost. The schema is dropped when done interacting with the workspace in Cleanup(), but the container remains running. The container may optionally be stopped or destroyed via Shutdown().

func NewLocalDocker

func NewLocalDocker(opts Options) (ld *LocalDocker, err error)

NewLocalDocker finds or creates a containerized MySQL instance, creates a temporary schema on it, and returns it.

func (*LocalDocker) Cleanup

func (ld *LocalDocker) Cleanup() error

Cleanup drops the temporary schema from the Dockerized instance. If any tables have any rows in the temp schema, the cleanup aborts and an error is returned. Cleanup does not handle stopping or destroying the container. If requested, that is handled by Shutdown() instead, so that containers aren't needlessly created and stopped/destroyed multiple times during a program's execution.

func (*LocalDocker) ConnectionPool

func (ld *LocalDocker) ConnectionPool(params string) (*sqlx.DB, error)

ConnectionPool returns a connection pool (*sqlx.DB) to the temporary workspace schema, using the supplied connection params (which may be blank).

func (*LocalDocker) IntrospectSchema

func (ld *LocalDocker) IntrospectSchema() (*tengo.Schema, error)

IntrospectSchema introspects and returns the temporary workspace schema.

type Options

type Options struct {
	Type                Type
	CleanupAction       CleanupAction
	Instance            *tengo.Instance // only TypeTempSchema
	Flavor              tengo.Flavor    // only TypeLocalDocker
	ContainerName       string          // only TypeLocalDocker
	SchemaName          string
	DefaultCharacterSet string
	DefaultCollation    string
	DefaultConnParams   string    // only TypeLocalDocker
	RootPassword        string    // only TypeLocalDocker
	PrefabWorkspace     Workspace // only TypePrefab
	LockWaitTimeout     time.Duration
}

Options represent different parameters controlling the workspace that is used. Some options are specific to a Type.

func OptionsForDir

func OptionsForDir(dir *fs.Dir, instance *tengo.Instance) (Options, error)

OptionsForDir returns Options based on the configuration in an fs.Dir. A non-nil instance should be supplied, unless the caller already knows the workspace won't be temp-schema based. This method relies on option definitions from util.AddGlobalOptions(), including "workspace", "temp-schema", "flavor", "docker-cleanup", and "reuse-temp-schema".

type ShutdownFunc

type ShutdownFunc func(...interface{}) bool

ShutdownFunc is a function that manages final cleanup of a Workspace upon completion of a request or process. It may optionally use args, passed through by Shutdown(), to determine whether or not a Workspace needs to be cleaned up. It should return true if cleanup occurred (meaning that the ShutdownFunc should be de-registered from future calls to Shutdown()), or false otherwise.

type StatementError

type StatementError struct {
	*fs.Statement
	Err error
}

StatementError represents a problem that occurred when executing a specific fs.Statement in a Workspace.

func ExecLogicalSchema

func ExecLogicalSchema(logicalSchema *fs.LogicalSchema, opts Options) (schema *tengo.Schema, statementErrors []*StatementError, fatalErr error)

ExecLogicalSchema converts a LogicalSchema to a tengo.Schema. It obtains a Workspace, executes the creation DDL contained in a LogicalSchema there, introspects it into a *tengo.Schema, cleans up the Workspace, and then returns the introspected schema. SQL errors (e.g. tables that could not be created) are non-fatal, and are returned in the second return value. The third return value represents fatal errors only.

func (*StatementError) Error

func (se *StatementError) Error() string

Error satisfies the builtin error interface.

func (*StatementError) String

func (se *StatementError) String() string

type TempSchema

type TempSchema struct {
	// contains filtered or unexported fields
}

TempSchema is a Workspace that exists as a schema that is created on another database instance. The schema is cleaned up when done interacting with the workspace.

func NewTempSchema

func NewTempSchema(opts Options) (ts *TempSchema, err error)

NewTempSchema creates a temporary schema on the supplied instance and returns it.

func (*TempSchema) Cleanup

func (ts *TempSchema) Cleanup() error

Cleanup either drops the temporary schema (if not using reuse-temp-schema) or just drops all tables in the schema (if using reuse-temp-schema). If any tables have any rows in the temp schema, the cleanup aborts and an error is returned.

func (*TempSchema) ConnectionPool

func (ts *TempSchema) ConnectionPool(params string) (*sqlx.DB, error)

ConnectionPool returns a connection pool (*sqlx.DB) to the temporary workspace schema, using the supplied connection params (which may be blank).

func (*TempSchema) IntrospectSchema

func (ts *TempSchema) IntrospectSchema() (*tengo.Schema, error)

IntrospectSchema introspects and returns the temporary workspace schema.

type Type

type Type int

Type represents a kind of workspace to use.

const (
	TypeTempSchema  Type = iota // A temporary schema on a real pre-supplied Instance
	TypeLocalDocker             // A schema on an ephemeral Docker container on localhost
	TypePrefab                  // A pre-supplied Workspace, possibly from another package
)

Constants enumerating different types of workspaces

type Workspace

type Workspace interface {
	// ConnectionPool returns a *sqlx.DB representing a connection pool for
	// interacting with the workspace. The pool should already be using the
	// correct default database for interacting with the workspace schema.
	ConnectionPool(params string) (*sqlx.DB, error)

	// IntrospectSchema returns a *tengo.Schema representing the current state
	// of the workspace schema.
	IntrospectSchema() (*tengo.Schema, error)

	// Cleanup cleans up the workspace, leaving it in a state where it could be
	// re-used/re-initialized as needed. Repeated calls to Cleanup() may error.
	Cleanup() error
}

Workspace represents a "scratch space" for DDL operations and schema introspection.

func New

func New(opts Options) (Workspace, error)

New returns a pointer to a ready-to-use Workspace, using the configuration specified in opts.