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 AddCommandOptions(cmd *mybase.Command)
- func DockerImageForFlavor(flavor tengo.Flavor, arch string) (string, error)
- func RegisterShutdownFunc(f ShutdownFunc)
- func Shutdown(args ...interface{})
- type CleanupAction
- type LocalDocker
- type Options
- type Schema
- type ShutdownFunc
- type StatementError
- type TempSchema
- type Type
- type Workspace
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddCommandOptions ¶
AddCommandOptions adds workspace-related option definitions to the supplied mybase.Command.
func DockerImageForFlavor ¶ added in v1.11.2
DockerImageForFlavor attempts to return the name of a Docker image for the supplied flavor and arch. The arch should be supplied in the same format as returned by tengo.DockerEngineArchitecture(), i.e. "amd64" or "arm64". In most cases this function returns "Docker official" Dockerhub images (top- level repos without an account name), but in some cases we must use a different source, or return an error.
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) (_ *LocalDocker, retErr 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(schema *tengo.Schema) 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
NameCaseMode tengo.NameCaseMode
LockTimeout time.Duration // max wait for workspace user-level locking, via GET_LOCK()
Concurrency int
SkipBinlog bool
}
Options represent different parameters controlling the workspace that is used. Some options are specific to a Type.
func OptionsForDir ¶
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 AddCommandOptions(), as well as the "flavor" option from util.AddGlobalOptions().
type Schema ¶
type Schema struct {
*tengo.Schema
LogicalSchema *fs.LogicalSchema
Failures []*StatementError
}
Schema captures the result of executing the SQL from an fs.LogicalSchema in a workspace, and then introspecting the resulting schema. It wraps the introspected tengo.Schema alongside the original fs.LogicalSchema and any SQL errors that occurred.
func ExecLogicalSchema ¶
func ExecLogicalSchema(logicalSchema *fs.LogicalSchema, opts Options) (_ *Schema, retErr error)
ExecLogicalSchema converts a LogicalSchema into a workspace.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 a value containing the introspected schema and any SQL errors (e.g. tables that could not be created). Such individual statement errors are not fatal and are not included in the error return value. The error return value only represents fatal errors that prevented the entire process. Note that if opts.NameCaseMode > tengo.NameCaseAsIs, logicalSchema may be modified in-place to force some identifiers to lowercase.
func (*Schema) FailedKeys ¶
FailedKeys returns a slice of tengo.ObjectKey values corresponding to statements that had SQL errors when executed.
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 ¶
StatementError represents a problem that occurred when executing a specific tengo.Statement in a Workspace.
func (*StatementError) Error ¶
func (se *StatementError) Error() string
Error satisfies the builtin error interface.
func (*StatementError) ErrorNumber ¶ added in v1.10.0
func (se *StatementError) ErrorNumber() uint16
ErrorNumber returns the server error code corresponding to Err if it is a driver-provided error. Otherwise, it returns 0.
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) (_ *TempSchema, retErr error)
NewTempSchema creates a temporary schema on the supplied instance and returns it.
func (*TempSchema) Cleanup ¶
func (ts *TempSchema) Cleanup(schema *tengo.Schema) 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.
// The arg may be nil, and/or the implementation may ignore the arg; it is
// supplied to optionally improve performance where relevant.
Cleanup(schema *tengo.Schema) error
}
Workspace represents a "scratch space" for DDL operations and schema introspection.
Source Files