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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RegisterShutdownFunc ¶ added in v1.1.0
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 ¶ added in v1.1.0
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 ¶ added in v1.1.0
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 ¶ added in v1.1.0
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 ¶ added in v1.1.0
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 ¶ added in v1.1.0
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 ¶ added in v1.1.0
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 ¶ added in v1.1.0
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 ¶ added in v1.1.0
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 ¶ added in v1.1.3
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 ¶ added in v1.1.0
StatementError represents a problem that occurred when executing a specific fs.Statement in a Workspace.
func ExecLogicalSchema ¶ added in v1.1.0
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 ¶ added in v1.1.0
func (se *StatementError) Error() string
Error satisfies the builtin error interface.
func (*StatementError) String ¶ added in v1.1.0
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 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.
Source Files