tengo

package module
v0.10.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 21, 2022 License: Apache-2.0 Imports: 24 Imported by: 0

README

Go La Tengo

Golang library for MySQL and MariaDB database automation

Repo now archived

Skeema is a bootstrapped (self-funded) product, primarily built by an independent developer. The continued viability of Skeema's open source development is dependent on consulting services and commercial products; without these revenue sources, ongoing development is not possible.

Go La Tengo was designed as a reusable package in a separate repo, with the hope of building development momentum for use-cases outside of schema management. However, maintaining it as a separate repo is time-consuming: the codebase must be separately maintained, tested, versioned, and released; and then vendored inside of the Skeema CLI's repo.

Recently, one of the external users of the Tengo package -- a startup that has raised over $55 million USD -- has been building commercial schema management functionality that directly competes with Skeema as a whole. That company is now also building functionality that is specifically only offered in Skeema's commercial edition. This company's behavior willfully and directly endangers the continued existence of Skeema, and as a result of this, it is simply no longer viable to offer Go La Tengo as an independent repository. All functionality here has now been merged directly into the Skeema CLI's primary repo as an internal sub-package. As of 4 November 2021, this separate Tengo repo is now archived, and may be deleted entirely in the coming months.

The open source Community edition of the Skeema CLI remains available and maintained at this time, but in light of such blatant bad actors in the open source space, it is entirely possible its license may change to either BSL or AGPL in the future. In any case, most new feature development is focused on the closed-source commercially-licensed Premium edition at this time.

External Dependencies

Credits

Created and maintained by @evanelias.

Additional contributions by:

Support for stored procedures and functions generously sponsored by Psyonix.

Support for partitioned tables generously sponsored by Etsy.

License

Copyright 2021 Skeema LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Documentation

Overview

Package tengo (Go La Tengo) is a database automation library. In its current form, its functionality is focused on MySQL schema introspection and diff'ing. Future releases will add more general-purpose automation features.

Index

Constants

This section is empty.

Variables

View Source 
var FlavorMariaDB101 = Flavor{VendorMariaDB, 10, 1, 0}

FlavorMariaDB101 represents MariaDB 10.1.x. This constant omits a patch number; avoid direct equality comparisons and ideally only use this in tests.

View Source 
var FlavorMariaDB102 = Flavor{VendorMariaDB, 10, 2, 0}

FlavorMariaDB102 represents MariaDB 10.2.x. This constant omits a patch number; avoid direct equality comparisons and ideally only use this in tests.

View Source 
var FlavorMariaDB103 = Flavor{VendorMariaDB, 10, 3, 0}

FlavorMariaDB103 represents MariaDB 10.3.x. This constant omits a patch number; avoid direct equality comparisons and ideally only use this in tests.

View Source 
var FlavorMariaDB104 = Flavor{VendorMariaDB, 10, 4, 0}

FlavorMariaDB104 represents MariaDB 10.4.x. This constant omits a patch number; avoid direct equality comparisons and ideally only use this in tests.

View Source 
var FlavorMariaDB105 = Flavor{VendorMariaDB, 10, 5, 0}

FlavorMariaDB105 represents MariaDB 10.5.x. This constant omits a patch number; avoid direct equality comparisons and ideally only use this in tests.

View Source 
var FlavorMariaDB106 = Flavor{VendorMariaDB, 10, 6, 0}

FlavorMariaDB106 represents MariaDB 10.6.x. This constant omits a patch number; avoid direct equality comparisons and ideally only use this in tests.

View Source 
var FlavorMySQL55 = Flavor{VendorMySQL, 5, 5, 0}

FlavorMySQL55 represents MySQL 5.5.x. This constant omits a patch number; avoid direct equality comparisons and ideally only use this in tests.

View Source 
var FlavorMySQL56 = Flavor{VendorMySQL, 5, 6, 0}

FlavorMySQL56 represents MySQL 5.6.x. This constant omits a patch number; avoid direct equality comparisons and ideally only use this in tests.

View Source 
var FlavorMySQL57 = Flavor{VendorMySQL, 5, 7, 0}

FlavorMySQL57 represents MySQL 5.7.x. This constant omits a patch number; avoid direct equality comparisons and ideally only use this in tests.

View Source 
var FlavorMySQL80 = Flavor{VendorMySQL, 8, 0, 0}

FlavorMySQL80 represents MySQL 8.0.x. This constant omits a patch number; avoid direct equality comparisons and ideally only use this in tests. Patch number is especially relevant in MySQL 8.0.x as functionality now changes in patch releases.

View Source 
var FlavorPercona55 = Flavor{VendorPercona, 5, 5, 0}

FlavorPercona55 represents Percona Server 5.5.x. This constant omits a patch number; avoid direct equality comparisons and ideally only use this in tests.

View Source 
var FlavorPercona56 = Flavor{VendorPercona, 5, 6, 0}

FlavorPercona56 represents Percona Server 5.6.x. This constant omits a patch number; avoid direct equality comparisons and ideally only use this in tests.

View Source 
var FlavorPercona57 = Flavor{VendorPercona, 5, 7, 0}

FlavorPercona57 represents Percona Server 5.7.x. This constant omits a patch number; avoid direct equality comparisons and ideally only use this in tests.

View Source 
var FlavorPercona80 = Flavor{VendorPercona, 8, 0, 0}

FlavorPercona80 represents Percona Server 8.0.x. This constant omits a patch number; avoid direct equality comparisons and ideally only use this in tests. Patch number is especially relevant in Percona Server 8.0.x as functionality now changes in patch releases.

View Source 
var FlavorUnknown = Flavor{VendorUnknown, 0, 0, 0}

FlavorUnknown represents a flavor that cannot be parsed. This is the zero value for Flavor.

Functions

func EscapeIdentifier 

func EscapeIdentifier(input string) string

EscapeIdentifier is for use in safely escaping MySQL identifiers (table names, column names, etc). It doubles any backticks already present in the input string, and then returns the string wrapped in outer backticks.

func EscapeValueForCreateTable 

func EscapeValueForCreateTable(input string) string

EscapeValueForCreateTable returns the supplied value (typically obtained from querying an information_schema table) escaped in the same manner as SHOW CREATE TABLE would display it. Examples include default values, table comments, column comments, index comments.

func IsAccessError 

func IsAccessError(err error) bool

IsAccessError returns true if err indicates an authentication or authorization problem, at connection time or query time. Can be a problem with credentials, client host, no access to requested default database, missing privilege, etc. There is no sense in immediately retrying the connection or query when encountering this type of error.

func IsDatabaseError 

func IsDatabaseError(err error, specificErrors ...uint16) bool

IsDatabaseError returns true if err came from a database server, typically as a response to a query or connection attempt. If one or more specificErrors are supplied, IsDatabaseError only returns true if the database error code matched one of those numbers.

func IsForbiddenDiff 

func IsForbiddenDiff(err error) bool

IsForbiddenDiff returns true if err represents an "unsafe" alteration that has not explicitly been permitted by the supplied StatementModifiers.

func IsSyntaxError 

func IsSyntaxError(err error) bool

IsSyntaxError returns true if err is a SQL syntax error, or false otherwise.

func IsUnsupportedDiff 

func IsUnsupportedDiff(err error) bool

IsUnsupportedDiff returns true if err represents an object that cannot be diff'ed due to use of features not supported by this package.

func NormalizeCreateOptions 

func NormalizeCreateOptions(createStmt string) string

NormalizeCreateOptions adjusts the supplied CREATE TABLE statement to remove any no-op table options that are persisted in SHOW CREATE TABLE, but not reflected in information_schema and serve no purpose for InnoDB tables. This function is not guaranteed to be safe for non-InnoDB tables.

func ParseCreateAutoInc 

func ParseCreateAutoInc(createStmt string) (string, uint64)

ParseCreateAutoInc parses a CREATE TABLE statement, formatted in the same manner as SHOW CREATE TABLE, and removes the table-level next-auto-increment clause if present. The modified CREATE TABLE will be returned, along with the next auto-increment value if one was found.

func ParseCreatePartitioning added in v0.10.4 

func ParseCreatePartitioning(createStmt string) (base, partitionClause string)

ParseCreatePartitioning parses a CREATE TABLE statement, formatted in the same manner as SHOW CREATE TABLE, and splits out the base CREATE clauses from the partioning clause.

func ParseVersion 

func ParseVersion(version string) (result [3]int)

ParseVersion takes a version string (e.g. @@version variable from MySQL) and returns a 3-element array of major, minor, and patch numbers. If parsing failed, the returned value will be {0, 0, 0}.

func RunSuite 

func RunSuite(suite IntegrationTestSuite, t *testing.T, backends []string)

RunSuite runs all test methods in the supplied suite once per backend. It calls suite.Setup(backend) once per backend, then iterates through all Test methods in suite. For each test method, suite.BeforeTest will be run, followed by the test itself. Finally, suite.Teardown(backend) will be run. Backends are just strings, and may contain docker image names or any other string representation that the test suite understands.

func SplitEnv 

func SplitEnv(key string) []string

SplitEnv examines the specified environment variable and splits its value on commas to return a list of strings. Note that if the env variable is blank or unset, an empty slice will be returned; this behavior differs from that of strings.Split.

func SplitHostOptionalPort 

func SplitHostOptionalPort(hostaddr string) (string, int, error)

SplitHostOptionalPort takes an address string containing a hostname, ipv4 addr, or ipv6 addr; *optionally* followed by a colon and port number. It splits the hostname portion from the port portion and returns them separately. If no port was present, 0 will be returned for that portion. If hostaddr contains an ipv6 address, the IP address portion must be wrapped in brackets on input, and the brackets will still be present on output.

func StripDisplayWidth added in v0.10.4 

func StripDisplayWidth(colType string) string

StripDisplayWidth removes integer display width from the supplied column type string, in a way that matches MySQL 8.0.19+'s behavior. The input should only be either an integer type or year(4) type; this function does NOT confirm this. No change is made to tinyint(1) types, nor types with a zerofill modifier, as per handling in MySQL 8.0.19.

func UseFilteredDriverLogger 

func UseFilteredDriverLogger()

UseFilteredDriverLogger overrides the mysql driver's logger to avoid excessive messages. This suppresses the driver's "unexpected EOF" output, which occurs when an initial connection is refused or a connection drops early. This excessive logging can occur whenever DockerClient.CreateInstance() or DockerClient.GetInstance() is waiting for the instance to finish starting.

Types

type AddCheck added in v0.10.4 

type AddCheck struct {
	Check *Check
	// contains filtered or unexported fields
}

AddCheck represents a new check constraint that is present on the right-side ("to") schema version of the table, but not the left-side ("from") version. It satisfies the TableAlterClause interface.

func (AddCheck) Clause added in v0.10.4 

func (acc AddCheck) Clause(mods StatementModifiers) string

Clause returns an ADD CONSTRAINT ... CHECK clause of an ALTER TABLE statement.

type AddColumn 

type AddColumn struct {
	Table         *Table
	Column        *Column
	PositionFirst bool
	PositionAfter *Column
}

AddColumn represents a new column that is present on the right-side ("to") schema version of the table, but not the left-side ("from") version. It satisfies the TableAlterClause interface.

func (AddColumn) Clause 

func (ac AddColumn) Clause(mods StatementModifiers) string

Clause returns an ADD COLUMN clause of an ALTER TABLE statement.

type AddForeignKey 

type AddForeignKey struct {
	ForeignKey *ForeignKey
	// contains filtered or unexported fields
}

AddForeignKey represents a new foreign key that is present on the right-side ("to") schema version of the table, but not the left-side ("from") version. It satisfies the TableAlterClause interface.

func (AddForeignKey) Clause 

func (afk AddForeignKey) Clause(mods StatementModifiers) string

Clause returns an ADD CONSTRAINT ... FOREIGN KEY clause of an ALTER TABLE statement.

type AddIndex 

type AddIndex struct {
	Index *Index
	// contains filtered or unexported fields
}

AddIndex represents an index that is present on the right-side ("to") schema version of the table, but was not identically present on the left- side ("from") version. It satisfies the TableAlterClause interface.

func (AddIndex) Clause 

func (ai AddIndex) Clause(mods StatementModifiers) string

Clause returns an ADD KEY clause of an ALTER TABLE statement.

type AlterCheck added in v0.10.4 

type AlterCheck struct {
	Check          *Check
	NewEnforcement bool
}

AlterCheck represents a change in a check's enforcement status in MySQL 8+. It satisfies the TableAlterClause interface.

func (AlterCheck) Clause added in v0.10.4 

func (alcc AlterCheck) Clause(mods StatementModifiers) string

Clause returns an ALTER CHECK clause of an ALTER TABLE statement.

type AlterIndex added in v0.10.4 

type AlterIndex struct {
	Index        *Index
	NewInvisible bool // true if index is being changed from visible to invisible
	// contains filtered or unexported fields
}

AlterIndex represents a change in an index's visibility in MySQL 8+ or MariaDB 10.6+.

func (AlterIndex) Clause added in v0.10.4 

func (ai AlterIndex) Clause(mods StatementModifiers) string

Clause returns an ALTER INDEX clause of an ALTER TABLE statement. It will be suppressed if the flavor does not support invisible/ignored indexes, and/or if the statement modifiers are respecting exact index order (in which case this ALTER TABLE will also have DROP and re-ADD clauses for this index, which prevents use of an ALTER INDEX clause.)

type BulkDropOptions added in v0.10.4 

type BulkDropOptions struct {
	OnlyIfEmpty     bool    // If true, when dropping tables, error if any have rows
	MaxConcurrency  int     // Max objects to drop at once
	SkipBinlog      bool    // If true, use session sql_log_bin=0 (requires superuser)
	PartitionsFirst bool    // If true, drop RANGE/LIST partitioned tables one partition at a time
	Schema          *Schema // If non-nil, obtain object lists from Schema instead of running I_S queries
}

BulkDropOptions controls how objects are dropped in bulk.

func (BulkDropOptions) Concurrency added in v0.10.4 

func (opts BulkDropOptions) Concurrency() int

Concurrency returns the concurrency, with a minimum value of 1.

type ChangeAutoIncrement 

type ChangeAutoIncrement struct {
	OldNextAutoIncrement uint64
	NewNextAutoIncrement uint64
}

ChangeAutoIncrement represents a difference in next-auto-increment value between two versions of a table. It satisfies the TableAlterClause interface.

func (ChangeAutoIncrement) Clause 

func (cai ChangeAutoIncrement) Clause(mods StatementModifiers) string

Clause returns an AUTO_INCREMENT clause of an ALTER TABLE statement.

type ChangeCharSet 

type ChangeCharSet struct {
	CharSet   string
	Collation string // blank string means "default collation for CharSet"
}

ChangeCharSet represents a difference in default character set and/or collation between two versions of a table. It satisfies the TableAlterClause interface.

func (ChangeCharSet) Clause 

func (ccs ChangeCharSet) Clause(_ StatementModifiers) string

Clause returns a DEFAULT CHARACTER SET clause of an ALTER TABLE statement.

type ChangeComment 

type ChangeComment struct {
	NewComment string
}

ChangeComment represents a difference in the table-level comment between two versions of a table. It satisfies the TableAlterClause interface.

func (ChangeComment) Clause 

func (cc ChangeComment) Clause(_ StatementModifiers) string

Clause returns a clause of an ALTER TABLE statement that changes a table's comment.

type ChangeCreateOptions 

type ChangeCreateOptions struct {
	OldCreateOptions string
	NewCreateOptions string
}

ChangeCreateOptions represents a difference in the create options (row_format, stats_persistent, stats_auto_recalc, etc) between two versions of a table. It satisfies the TableAlterClause interface.

func (ChangeCreateOptions) Clause 

func (cco ChangeCreateOptions) Clause(_ StatementModifiers) string

Clause returns a clause of an ALTER TABLE statement that sets one or more create options.

type ChangeStorageEngine 

type ChangeStorageEngine struct {
	NewStorageEngine string
}

ChangeStorageEngine represents a difference in the table's storage engine. It satisfies the TableAlterClause interface. Please note that Go La Tengo's support for non-InnoDB storage engines is currently very limited, however it still provides the ability to generate ALTERs that change engine.

func (ChangeStorageEngine) Clause 

func (cse ChangeStorageEngine) Clause(_ StatementModifiers) string

Clause returns a clause of an ALTER TABLE statement that changes a table's storage engine.

func (ChangeStorageEngine) Unsafe 

func (cse ChangeStorageEngine) Unsafe() bool

Unsafe returns true if this clause is potentially destructive of data. ChangeStorageEngine is always considered unsafe, due to the potential complexity in converting a table's data to the new storage engine.

type Check added in v0.10.4 

type Check struct {
	Name     string `json:"name"`
	Clause   string `json:"clause"`
	Enforced bool   `json:"enforced"` // Always true in MariaDB
}

Check represents a single check constraint in a table.

func (*Check) Definition added in v0.10.4 

func (cc *Check) Definition(flavor Flavor) string

Definition returns this Check's definition clause, for use as part of a DDL statement.

type Column 

type Column struct {
	Name               string `json:"name"`
	TypeInDB           string `json:"type"`
	Nullable           bool   `json:"nullable,omitempty"`
	AutoIncrement      bool   `json:"autoIncrement,omitempty"`
	Default            string `json:"default,omitempty"` // Stored as an expression, i.e. quote-wrapped if string
	OnUpdate           string `json:"onUpdate,omitempty"`
	GenerationExpr     string `json:"generationExpression,omitempty"` // Only populated if generated column
	Virtual            bool   `json:"virtual,omitempty"`
	CharSet            string `json:"charSet,omitempty"`            // Only populated if textual type
	Collation          string `json:"collation,omitempty"`          // Only populated if textual type
	CollationIsDefault bool   `json:"collationIsDefault,omitempty"` // Only populated if textual type; indicates default for CharSet
	Compression        string `json:"compression,omitempty"`        // Only non-empty if using column compression in Percona Server or MariaDB
	Comment            string `json:"comment,omitempty"`
	Invisible          bool   `json:"invisible,omitempty"` // True if an invisible column (MariaDB 10.3+, MySQL 8.0.23+)
	CheckClause        string `json:"check,omitempty"`     // Only non-empty for MariaDB inline check constraint clause
}

Column represents a single column of a table.

func (*Column) Definition 

func (c *Column) Definition(flavor Flavor, table *Table) string

Definition returns this column's definition clause, for use as part of a DDL statement. A table may optionally be supplied, which simply causes CHARACTER SET clause to be omitted if the table and column have the same *collation* (mirroring the specific display logic used by SHOW CREATE TABLE)

func (*Column) Equals 

func (c *Column) Equals(other *Column) bool

Equals returns true if two columns are identical, false otherwise.

type DatabaseDiff added in v0.8.13 

type DatabaseDiff struct {
	From *Schema
	To   *Schema
}

DatabaseDiff represents differences of schema characteristics (default character set or default collation), or a difference in the existence of the the schema.

func (*DatabaseDiff) DiffType added in v0.8.13 

func (dd *DatabaseDiff) DiffType() DiffType

DiffType returns the type of diff operation.

func (*DatabaseDiff) ObjectKey added in v0.8.14 

func (dd *DatabaseDiff) ObjectKey() ObjectKey

ObjectKey returns a value representing the type and name of the schema being diff'ed. The type is always ObjectTypeDatabase. The name will be the From side schema, unless it is nil (CREATE DATABASE), in which case the To side schema name is returned.

func (*DatabaseDiff) Statement added in v0.8.13 

func (dd *DatabaseDiff) Statement(_ StatementModifiers) (string, error)

Statement returns a DDL statement corresponding to the DatabaseDiff. A blank string may be returned if there is no statement to execute.

type DiffType added in v0.8.13 

type DiffType int

DiffType enumerates possible ways that two objects differ 

const (
	DiffTypeNone DiffType = iota
	DiffTypeCreate
	DiffTypeDrop
	DiffTypeAlter
	DiffTypeRename
)

Constants representing the types of diff operations.

func (DiffType) String added in v0.8.13 

func (dt DiffType) String() string

type DockerClient added in v0.8.8 

type DockerClient struct {
	Options DockerClientOptions
	// contains filtered or unexported fields
}

DockerClient manages lifecycle of local Docker containers for sandbox database instances. It wraps and hides the implementation of a specific Docker client implementation. (This package currently uses github.com/fsouza/go-dockerclient, but may later switch to the official Docker Golang client.)

func NewDockerClient added in v0.8.8 

func NewDockerClient(opts DockerClientOptions) (*DockerClient, error)

NewDockerClient is a constructor for DockerClient

func (*DockerClient) CreateInstance added in v0.8.8 

func (dc *DockerClient) CreateInstance(opts DockerizedInstanceOptions) (*DockerizedInstance, error)

CreateInstance attempts to create a Docker container with the supplied name (any arbitrary name, or blank to assign random) and image (such as "mysql:5.6", or just "mysql" to indicate latest). A connection pool will be established for the instance.

func (*DockerClient) GetInstance added in v0.8.8 

func (dc *DockerClient) GetInstance(opts DockerizedInstanceOptions) (*DockerizedInstance, error)

GetInstance attempts to find an existing container with name equal to opts.Name. If the container is found, it will be started if not already running, and a connection pool will be established. If the container does not exist or cannot be started or connected to, a nil *DockerizedInstance and a non-nil error will be returned. If a non-blank opts.Image is supplied, and the existing container has a a different image, the instance's flavor will be examined as a fallback. If it also does not match the requested image, an error will be returned.

func (*DockerClient) GetOrCreateInstance added in v0.8.8 

func (dc *DockerClient) GetOrCreateInstance(opts DockerizedInstanceOptions) (*DockerizedInstance, error)

GetOrCreateInstance attempts to fetch an existing Docker container with name equal to opts.Name. If it exists and its image (or flavor) matches opts.Image, and there are no errors starting or connecting to the instance, it will be returned. If it exists but its image/flavor don't match, or it cannot be started or connected to, an error will be returned. If no container exists with this name, a new one will attempt to be created.

type DockerClientOptions added in v0.8.8 

type DockerClientOptions struct{}

DockerClientOptions specifies options when instantiating a Docker client. No options are currently supported, but this may change in the future.

type DockerizedInstance 

type DockerizedInstance struct {
	*Instance
	DockerizedInstanceOptions
	Manager *DockerClient
	// contains filtered or unexported fields
}

DockerizedInstance is a database instance running in a local Docker container.

func (*DockerizedInstance) DSN 

func (di *DockerizedInstance) DSN() string

DSN returns a github.com/go-sql-driver/mysql formatted DSN corresponding to its containerized mysql-server instance.

func (*DockerizedInstance) Destroy 

func (di *DockerizedInstance) Destroy() error

Destroy stops and deletes the corresponding containerized mysql-server.

func (*DockerizedInstance) NukeData 

func (di *DockerizedInstance) NukeData() error

NukeData drops all non-system schemas and tables in the containerized mysql-server, making it useful as a per-test cleanup method in implementations of IntegrationTestSuite.BeforeTest.

func (*DockerizedInstance) Port 

func (di *DockerizedInstance) Port() int

Port returns the actual port number on localhost that maps to the container's internal port 3306.

func (*DockerizedInstance) Source added in v0.10.4 

func (di *DockerizedInstance) Source(reader io.Reader) (string, error)

Source reads from the io.Reader and executes it against the containerized mysql-server. The io.Reader should contain one or more valid SQL instructions, typically a mix of DML and/or DDL statements. It is useful as a per-test setup method in implementations of IntegrationTestSuite.BeforeTest.

func (*DockerizedInstance) SourceSQL 

func (di *DockerizedInstance) SourceSQL(filePath string) (string, error)

SourceSQL reads the specified file and executes it against the containerized mysql-server. The file should contain one or more valid SQL instructions, typically a mix of DML and/or DDL statements. It is useful as a per-test setup method in implementations of IntegrationTestSuite.BeforeTest.

func (*DockerizedInstance) SourceString added in v0.10.4 

func (di *DockerizedInstance) SourceString(str string) (string, error)

SourceString reads the specified string and executes it against the containerized mysql-server. The string should contain one or more valid SQL instructions, typically a mix of DML and/or DDL statements. It is useful as a per-test setup method in implementations of IntegrationTestSuite.BeforeTest.

func (*DockerizedInstance) Start added in v0.8.2 

func (di *DockerizedInstance) Start() error

Start starts the corresponding containerized mysql-server. If it is not already running, an error will be returned if it cannot be started. If it is already running, nil will be returned.

func (*DockerizedInstance) Stop added in v0.8.2 

func (di *DockerizedInstance) Stop() error

Stop halts the corresponding containerized mysql-server, but does not destroy the container. The connection pool will be removed. If the container was not already running, nil will be returned.

func (*DockerizedInstance) String 

func (di *DockerizedInstance) String() string

func (*DockerizedInstance) TryConnect added in v0.8.3 

func (di *DockerizedInstance) TryConnect() (err error)

TryConnect sets up a connection pool to the containerized mysql-server, and tests connectivity. It returns an error if a connection cannot be established within 30 seconds.

type DockerizedInstanceOptions added in v0.8.8 

type DockerizedInstanceOptions struct {
	Name              string
	Image             string
	RootPassword      string
	DefaultConnParams string
}

DockerizedInstanceOptions specifies options for creating or finding a sandboxed database instance inside a Docker container.

type DropCheck added in v0.10.4 

type DropCheck struct {
	Check *Check
	// contains filtered or unexported fields
}

DropCheck represents a check constraint that was present on the left-side ("from") schema version of the table, but not the right-side ("to") version. It satisfies the TableAlterClause interface.

func (DropCheck) Clause added in v0.10.4 

func (dcc DropCheck) Clause(mods StatementModifiers) string

Clause returns a DROP CHECK or DROP CONSTRAINT clause of an ALTER TABLE statement, depending on the flavor.

type DropColumn 

type DropColumn struct {
	Column *Column
}

DropColumn represents a column that was present on the left-side ("from") schema version of the table, but not the right-side ("to") version. It satisfies the TableAlterClause interface.

func (DropColumn) Clause 

func (dc DropColumn) Clause(_ StatementModifiers) string

Clause returns a DROP COLUMN clause of an ALTER TABLE statement.

func (DropColumn) Unsafe 

func (dc DropColumn) Unsafe() bool

Unsafe returns true if this clause is potentially destructive of data. DropColumn is always unsafe, unless it's a virtual column (which is easy to roll back; there's no inherent data loss from dropping a virtual column).

type DropForeignKey 

type DropForeignKey struct {
	ForeignKey *ForeignKey
	// contains filtered or unexported fields
}

DropForeignKey represents a foreign key that was present on the left-side ("from") schema version of the table, but not the right-side ("to") version. It satisfies the TableAlterClause interface.

func (DropForeignKey) Clause 

func (dfk DropForeignKey) Clause(mods StatementModifiers) string

Clause returns a DROP FOREIGN KEY clause of an ALTER TABLE statement.

type DropIndex 

type DropIndex struct {
	Index *Index
	// contains filtered or unexported fields
}

DropIndex represents an index that was present on the left-side ("from") schema version of the table, but not identically present the right-side ("to") version. It satisfies the TableAlterClause interface.

func (DropIndex) Clause 

func (di DropIndex) Clause(mods StatementModifiers) string

Clause returns a DROP KEY clause of an ALTER TABLE statement.

type Flavor 

type Flavor struct {
	Vendor Vendor
	Major  int
	Minor  int
	Patch  int
}

Flavor represents a database server release, including vendor along with major and minor version number, and optionally the patch number (or 0 if unknown or irrelevant).

func NewFlavor added in v0.8.2 

func NewFlavor(base string, versionParts ...int) Flavor

NewFlavor returns a Flavor value based on its inputs, which should be supplied in one of these forms: NewFlavor("vendor", major, minor) NewFlavor("vendor", major, minor, patch) NewFlavor("vendor:major.minor") NewFlavor("vendor:major.minor.patch")

func ParseFlavor 

func ParseFlavor(versionString, versionComment string) Flavor

ParseFlavor returns a Flavor value based on inputs obtained from server vars @@global.version and @@global.version_comment. It accounts for how some distributions and/or cloud platforms manipulate those values.

func (Flavor) AllowBlobDefaults added in v0.8.2 

func (fl Flavor) AllowBlobDefaults() bool

AllowBlobDefaults returns true if the flavor permits blob and text types to have literal default values. (Note that MySQL may permit these types to have default *expressions* anyway.)

func (Flavor) AlwaysShowTableCollation added in v0.8.4 

func (fl Flavor) AlwaysShowTableCollation(charSet string) bool

AlwaysShowTableCollation returns true if this flavor always emits a collation clause for the supplied character set, even if the collation is the default for the character set

func (Flavor) DefaultUtf8mb4Collation added in v0.8.4 

func (fl Flavor) DefaultUtf8mb4Collation() string

DefaultUtf8mb4Collation returns the name of the default collation of the utf8mb4 character set in this flavor.

func (Flavor) Family added in v0.10.4 

func (fl Flavor) Family() Flavor

Family returns a copy of the receiver with a zeroed-out patch version.

func (Flavor) FractionalTimestamps added in v0.8.2 

func (fl Flavor) FractionalTimestamps() bool

FractionalTimestamps returns true if the flavor supports fractional seconds in timestamp and datetime values. Note that this returns true for FlavorUnknown as a special-case, since all recent flavors do support this.

func (Flavor) GeneratedColumns added in v0.10.4 

func (fl Flavor) GeneratedColumns() bool

GeneratedColumns returns true if the flavor supports generated columns using MySQL's native syntax. (Although MariaDB 10.1 has support for generated columns, its syntax is borrowed from other DBMS, so false is returned.)

func (Flavor) HasCheckConstraints added in v0.10.4 

func (fl Flavor) HasCheckConstraints() bool

HasCheckConstraints returns true if the flavor supports check constraints and exposes them in information_schema.

func (Flavor) HasDataDictionary added in v0.8.4 

func (fl Flavor) HasDataDictionary() bool

HasDataDictionary returns true if the flavor has a global transactional data dictionary instead of using traditional frm files.

func (Flavor) Known added in v0.8.15 

func (fl Flavor) Known() bool

Known returns true if both the vendor and major version of this flavor were parsed properly

func (Flavor) MySQLishMinVersion added in v0.8.15 

func (fl Flavor) MySQLishMinVersion(versionParts ...int) bool

MySQLishMinVersion returns true if the vendor isn't VendorMariaDB, and this flavor has a version equal to or newer than the specified version. Note that this intentionally DOES consider VendorUnknown to be MySQLish.

func (Flavor) OmitIntDisplayWidth added in v0.10.4 

func (fl Flavor) OmitIntDisplayWidth() bool

OmitIntDisplayWidth returns true if the flavor omits inclusion of display widths from column types in the int family, aside from special cases like tinyint(1).

func (Flavor) SortedForeignKeys added in v0.8.17 

func (fl Flavor) SortedForeignKeys() bool

SortedForeignKeys returns true if the flavor sorts foreign keys lexicographically in SHOW CREATE TABLE.

func (Flavor) String 

func (fl Flavor) String() string

func (Flavor) Supported added in v0.8.2 

func (fl Flavor) Supported() bool

Supported returns true if package tengo officially supports this flavor

func (Flavor) VendorMinVersion added in v0.8.2 

func (fl Flavor) VendorMinVersion(vendor Vendor, versionParts ...int) bool

VendorMinVersion returns true if this flavor matches the supplied vendor, and has a version equal to or newer than the specified version.

type ForbiddenDiffError 

type ForbiddenDiffError struct {
	Reason    string
	Statement string
}

ForbiddenDiffError can be returned by ObjectDiff.Statement when the supplied statement modifiers do not permit the generated ObjectDiff to be used in this situation.

func (*ForbiddenDiffError) Error 

func (e *ForbiddenDiffError) Error() string

Error satisfies the builtin error interface.

type ForeignKey 

type ForeignKey struct {
	Name                  string   `json:"name"`
	ColumnNames           []string `json:"columnNames"`
	ReferencedSchemaName  string   `json:"referencedSchemaName,omitempty"` // will be empty string if same schema
	ReferencedTableName   string   `json:"referencedTableName"`
	ReferencedColumnNames []string `json:"referencedColumnNames"` // slice length always identical to len(ColumnNames)
	UpdateRule            string   `json:"updateRule"`
	DeleteRule            string   `json:"deleteRule"`
}

ForeignKey represents a single foreign key constraint in a table. Note that the "referenced" side of the FK is tracked as strings, rather than *Schema, *Table, *[]Column to avoid potentially having to introspect multiple schemas in a particular order. Also, the referenced side is not gauranteed to exist, especially if foreign_key_checks=0 has been used at any point in the past.

func (*ForeignKey) Definition 

func (fk *ForeignKey) Definition(flavor Flavor) string

Definition returns this ForeignKey's definition clause, for use as part of a DDL statement.

func (*ForeignKey) Equals 

func (fk *ForeignKey) Equals(other *ForeignKey) bool

Equals returns true if two ForeignKeys are completely identical (even in terms of cosmetic differences), false otherwise.

func (*ForeignKey) Equivalent 

func (fk *ForeignKey) Equivalent(other *ForeignKey) bool

Equivalent returns true if two ForeignKeys are functionally equivalent, regardless of whether or not they have the same names.

type Index 

type Index struct {
	Name           string      `json:"name"`
	Parts          []IndexPart `json:"parts"`
	PrimaryKey     bool        `json:"primaryKey,omitempty"`
	Unique         bool        `json:"unique,omitempty"`
	Invisible      bool        `json:"invisible,omitempty"` // MySQL 8+, also used for MariaDB 10.6's IGNORED indexes
	Comment        string      `json:"comment,omitempty"`
	Type           string      `json:"type"`
	FullTextParser string      `json:"parser,omitempty"`
}

Index represents a single index (primary key, unique secondary index, or non- unique secondard index) in a table.

func (*Index) Definition 

func (idx *Index) Definition(flavor Flavor) string

Definition returns this index's definition clause, for use as part of a DDL statement.

func (*Index) Equals 

func (idx *Index) Equals(other *Index) bool

Equals returns true if two indexes are completely identical, false otherwise.

func (*Index) EqualsIgnoringVisibility added in v0.10.4 

func (idx *Index) EqualsIgnoringVisibility(other *Index) bool

EqualsIgnoringVisibility returns true if two indexes are identical, or only differ in visibility.

func (*Index) Equivalent added in v0.8.16 

func (idx *Index) Equivalent(other *Index) bool

Equivalent returns true if two Indexes are functionally equivalent, regardless of whether or not they have the same names, comments, or visibility.

func (*Index) RedundantTo added in v0.8.16 

func (idx *Index) RedundantTo(other *Index) bool

RedundantTo returns true if idx is equivalent to, or a strict subset of, other. Both idx and other should be indexes of the same table. A non-unique index is considered redundant to any other index having the same (or more) columns in the same order, unless its parts have a greater column prefix length. A unique index can only be redundant to the primary key or an exactly equivalent unique index; another unique index with more cols may coexist due to the desired constraint semantics. A primary key is never redundant to another index.

type IndexPart added in v0.10.4 

type IndexPart struct {
	ColumnName   string `json:"columnName,omitempty"`   // name of column, or empty if expression
	Expression   string `json:"expression,omitempty"`   // expression value (MySQL 8+), or empty if column
	PrefixLength uint16 `json:"prefixLength,omitempty"` // nonzero if only a prefix of column is indexed
	Descending   bool   `json:"descending,omitempty"`   // if true, collation is descending (MySQL 8+)
}

IndexPart represents an individual indexed column or expression. Each index has one or more IndexPart values.

func (*IndexPart) Definition added in v0.10.4 

func (part *IndexPart) Definition(_ Flavor) string

Definition returns this index part's definition clause.

type Instance 

type Instance struct {
	BaseDSN    string // DSN ending in trailing slash; i.e. no schema name or params
	Driver     string
	User       string
	Password   string
	Host       string
	Port       int
	SocketPath string
	// contains filtered or unexported fields
}

Instance represents a single database server running on a specific host or address.

func NewInstance 

func NewInstance(driver, dsn string) (*Instance, error)

NewInstance returns a pointer to a new Instance corresponding to the supplied driver and dsn. Currently only "mysql" driver is supported. dsn should be formatted according to driver specifications. If it contains a schema name, it will be ignored. If it contains any params, they will be applied as default params to all connections (in addition to whatever is supplied in Connect).

func (*Instance) AlterSchema 

func (instance *Instance) AlterSchema(schema string, opts SchemaCreationOptions) error

AlterSchema changes the character set and/or collation of the supplied schema on instance. Supply an empty string for opts.DefaultCharSet to only change the collation, or supply an empty string for opts.DefaultCollation to use the default collation of opts.DefaultCharSet. (Supplying an empty string for both is also allowed, but is a no-op.)

func (*Instance) CachedConnectionPool added in v0.10.4 

func (instance *Instance) CachedConnectionPool(defaultSchema, params string) (*sqlx.DB, error)

CachedConnectionPool operates like ConnectionPool, except it caches connection pools for reuse. When multiple requests are made for the same combination of defaultSchema and params, a pre-existing connection pool will be returned. See ConnectionPool for usage of the args for this method.

func (*Instance) CanConnect 

func (instance *Instance) CanConnect() (bool, error)

CanConnect returns true if the Instance can currently be connected to, using its configured User and Password. If a new connection cannot be made, the return value will be false, along with an error expressing the reason.

func (*Instance) CanSkipBinlog added in v0.10.4 

func (instance *Instance) CanSkipBinlog() bool

CanSkipBinlog returns true if instance.User has privileges necessary to set sql_log_bin=0. If an error occurs in checking grants, this method returns false as a safe fallback.

func (*Instance) CloseAll added in v0.8.7 

func (instance *Instance) CloseAll()

CloseAll closes all of instance's cached connection pools. This can be useful for graceful shutdown, to avoid aborted-connection counters/logging in some versions of MySQL.

func (*Instance) Connect 

func (instance *Instance) Connect(defaultSchema string, params string) (*sqlx.DB, error)

Connect is an alias for CachedConnectionPool.

func (*Instance) ConnectionPool added in v0.10.4 

func (instance *Instance) ConnectionPool(defaultSchema, params string) (*sqlx.DB, error)

ConnectionPool returns a new sqlx.DB for this instance's host/port/user/pass with the supplied default schema and params string. A connection attempt is made, and an error will be returned if connection fails. defaultSchema may be "" if it is not relevant. params should be supplied in format "foo=bar&fizz=buzz" with URL escaping already applied. Do not include a prefix of "?". params will be merged with instance.defaultParams, with params supplied here taking precedence. The connection pool's max size, max conn lifetime, and max idle time are all tuned automatically to intelligent defaults based on auto-discovered limits.

func (*Instance) CreateSchema 

func (instance *Instance) CreateSchema(name string, opts SchemaCreationOptions) (*Schema, error)

CreateSchema creates a new database schema with the supplied name, and optionally the supplied default CharSet and Collation. (Leave these fields blank to use server defaults.)

func (*Instance) DefaultCharSetAndCollation 

func (instance *Instance) DefaultCharSetAndCollation() (serverCharSet, serverCollation string, err error)

DefaultCharSetAndCollation returns the instance's default character set and collation

func (*Instance) DropRoutinesInSchema added in v0.10.4 

func (instance *Instance) DropRoutinesInSchema(schema string, opts BulkDropOptions) error

DropRoutinesInSchema drops all stored procedures and functions in a schema.

func (*Instance) DropSchema 

func (instance *Instance) DropSchema(schema string, opts BulkDropOptions) error

DropSchema first drops all tables in the schema, and then drops the database schema itself. If opts.OnlyIfEmpty==true, returns an error if any of the tables have any rows.

func (*Instance) DropTablesInSchema 

func (instance *Instance) DropTablesInSchema(schema string, opts BulkDropOptions) error

DropTablesInSchema drops all tables in a schema. If opts.OnlyIfEmpty==true, returns an error if any of the tables have any rows.

func (*Instance) Flavor 

func (instance *Instance) Flavor() Flavor

Flavor returns this instance's flavor value, representing the database distribution/fork/vendor as well as major and minor version. If this is unable to be determined or an error occurs, FlavorUnknown will be returned.

func (*Instance) ForceFlavor added in v0.8.15 

func (instance *Instance) ForceFlavor(flavor Flavor)

ForceFlavor overrides this instance's flavor value. Only tests should call this method directly; all other callers should use SetFlavor instead and check the error return value.

func (*Instance) HasSchema 

func (instance *Instance) HasSchema(name string) (bool, error)

HasSchema returns true if this instance has a schema with the supplied name visible to the user, or false otherwise. An error result will only be returned if a connection or query failed entirely and we weren't able to determine whether the schema exists.

func (*Instance) HostAndOptionalPort 

func (instance *Instance) HostAndOptionalPort() string

HostAndOptionalPort is like String(), but omits the port if default

func (*Instance) Schema 

func (instance *Instance) Schema(name string) (*Schema, error)

Schema returns a single schema by name. If the schema does not exist, nil will be returned along with a sql.ErrNoRows error.

func (*Instance) SchemaNames 

func (instance *Instance) SchemaNames() ([]string, error)

SchemaNames returns a slice of all schema name strings on the instance visible to the user. System schemas are excluded.

func (*Instance) Schemas 

func (instance *Instance) Schemas(onlyNames ...string) ([]*Schema, error)

Schemas returns a slice of schemas on the instance visible to the user. If called with no args, all non-system schemas will be returned. Or pass one or more schema names as args to filter the result to just those schemas. Note that the ordering of the resulting slice is not guaranteed.

func (*Instance) SchemasByName 

func (instance *Instance) SchemasByName(onlyNames ...string) (map[string]*Schema, error)

SchemasByName returns a map of schema name string to *Schema. If called with no args, all non-system schemas will be returned. Or pass one or more schema names as args to filter the result to just those schemas.

func (*Instance) SetFlavor added in v0.8.15 

func (instance *Instance) SetFlavor(flavor Flavor) error

SetFlavor attempts to set this instance's flavor value. If the instance's flavor has already been hydrated successfully, the value is not changed and an error is returned.

func (*Instance) ShowCreateTable 

func (instance *Instance) ShowCreateTable(schema, table string) (string, error)

ShowCreateTable returns a string with a CREATE TABLE statement, representing how the instance views the specified table as having been created.

func (*Instance) String 

func (instance *Instance) String() string

String for an instance returns a "host:port" string (or "localhost:/path/to/socket" if using UNIX domain socket)

func (*Instance) TableHasRows 

func (instance *Instance) TableHasRows(schema, table string) (bool, error)

TableHasRows returns true if the table has at least one row. If an error occurs in querying, also returns true (along with the error) since a false positive is generally less dangerous in this case than a false negative.

func (*Instance) TableSize 

func (instance *Instance) TableSize(schema, table string) (int64, error)

TableSize returns an estimate of the table's size on-disk, based on data in information_schema. If the table or schema does not exist on this instance, the error will be sql.ErrNoRows. Please note that use of innodb_stats_persistent may negatively impact the accuracy. For example, see https://bugs.mysql.com/bug.php?id=75428.

func (*Instance) Valid added in v0.10.4 

func (instance *Instance) Valid() (bool, error)

Valid returns true if a successful connection can be made to the Instance, or if a successful connection has already been made previously. This method only returns false if no previous successful connection was ever made, and a new attempt to establish one fails.

func (*Instance) Version 

func (instance *Instance) Version() (int, int, int)

Version returns three ints representing the database's major, minor, and patch version, respectively. If this is unable to be determined, all 0's will be returned.

type IntegrationTestSuite 

type IntegrationTestSuite interface {
	Setup(backend string) error
	Teardown(backend string) error
	BeforeTest(backend string) error
}

IntegrationTestSuite is the interface for a suite of test methods. In addition to implementing the 3 methods of the interface, an integration test suite struct should have any number of test methods of form TestFoo(t *testing.T), which will be executed automatically by RunSuite.

type ModifyColumn 

type ModifyColumn struct {
	Table         *Table
	OldColumn     *Column
	NewColumn     *Column
	PositionFirst bool
	PositionAfter *Column
}

ModifyColumn represents a column that exists in both versions of the table, but with a different definition. It satisfies the TableAlterClause interface.

func (ModifyColumn) Clause 

func (mc ModifyColumn) Clause(mods StatementModifiers) string

Clause returns a MODIFY COLUMN clause of an ALTER TABLE statement.

func (ModifyColumn) Unsafe 

func (mc ModifyColumn) Unsafe() bool

Unsafe returns true if this clause is potentially destructive of data. ModifyColumn's safety depends on the nature of the column change; for example, increasing the size of a varchar is safe, but changing decreasing the size or changing the column type entirely is considered unsafe.

type ModifyPartitions added in v0.10.4 

type ModifyPartitions struct {
	Add          []*Partition
	Drop         []*Partition
	ForDropTable bool
}

ModifyPartitions represents a change to the partition list for a table using RANGE, RANGE COLUMNS, LIST, or LIST COLUMNS partitioning. Generation of this clause is only partially supported at this time.

func (ModifyPartitions) Clause added in v0.10.4 

func (mp ModifyPartitions) Clause(mods StatementModifiers) string

Clause currently returns an empty string when a partition list difference is present in a table that exists in both "from" and "to" sides of the diff; in that situation, ModifyPartitions is just used as a placeholder to indicate that a difference was detected. ModifyPartitions currently returns a non-empty clause string only for the use-case of dropping individual partitions before dropping a table entirely, which reduces the amount of time the dict_sys mutex is held when dropping the table.

func (ModifyPartitions) Unsafe added in v0.10.4 

func (mp ModifyPartitions) Unsafe() bool

Unsafe returns true if this clause is potentially destructive of data.

type NextAutoIncMode 

type NextAutoIncMode int

NextAutoIncMode enumerates various ways of handling AUTO_INCREMENT discrepancies between two tables. 

const (
	NextAutoIncIgnore      NextAutoIncMode = iota // omit auto-inc value changes in diff
	NextAutoIncIfIncreased                        // only include auto-inc value if the "from" side is less than the "to" side
	NextAutoIncIfAlready                          // only include auto-inc value if the "from" side is already greater than 1
	NextAutoIncAlways                             // always include auto-inc value in diff
)

Constants for how to handle next-auto-inc values in table diffs. Usually these are ignored in diffs entirely, but in some cases they are included.

type ObjectDiff added in v0.8.13 

type ObjectDiff interface {
	DiffType() DiffType
	ObjectKey() ObjectKey
	Statement(StatementModifiers) (string, error)
}

ObjectDiff is an interface allowing generic handling of differences between two objects.

type ObjectKey added in v0.8.14 

type ObjectKey struct {
	Type ObjectType
	Name string
}

ObjectKey is useful as a map key for indexing database objects within a single schema.

func (ObjectKey) String added in v0.8.14 

func (key ObjectKey) String() string

type ObjectType added in v0.8.14 

type ObjectType string

ObjectType defines a class of object in a relational database system. 

const (
	ObjectTypeDatabase ObjectType = "database"
	ObjectTypeTable    ObjectType = "table"
	ObjectTypeProc     ObjectType = "procedure"
	ObjectTypeFunc     ObjectType = "function"
)

Constants enumerating valid object types. Currently we do not define separate types for sub-types such as columns, indexes, foreign keys, etc as these are handled within the table logic.

func (ObjectType) Caps added in v0.8.14 

func (ot ObjectType) Caps() string

Caps returns the object type as an uppercase string.

type Partition added in v0.10.4 

type Partition struct {
	Name    string `json:"name"`
	SubName string `json:"subName,omitempty"` // empty string if no sub-partitioning; not fully supported yet
	Values  string `json:"values,omitempty"`  // only populated for RANGE or LIST
	Comment string `json:"comment,omitempty"`
	Engine  string `json:"engine"`
	DataDir string `json:"dataDir,omitempty"`
}

Partition stores information on a single partition.

func (*Partition) Definition added in v0.10.4 

func (p *Partition) Definition(flavor Flavor, method string) string

Definition returns this partition's definition clause, for use as part of a DDL statement.

type PartitionBy added in v0.10.4 

type PartitionBy struct {
	Partitioning *TablePartitioning
	RePartition  bool // true if changing partitioning on already-partitioned table
}

PartitionBy represents initially partitioning a previously-unpartitioned table, or changing the partitioning method and/or expression on an already- partitioned table. It satisfies the TableAlterClause interface.

func (PartitionBy) Clause added in v0.10.4 

func (pb PartitionBy) Clause(mods StatementModifiers) string

Clause returns a clause of an ALTER TABLE statement that partitions a previously-unpartitioned table.

type PartitionListMode added in v0.10.4 

type PartitionListMode string

PartitionListMode values control edge-cases for how the list of partitions is represented in SHOW CREATE TABLE. 

const (
	PartitionListDefault  PartitionListMode = ""          // Default behavior based on partitioning method
	PartitionListExplicit PartitionListMode = "full"      // List each partition individually
	PartitionListCount    PartitionListMode = "countOnly" // Just use a count of partitions
	PartitionListNone     PartitionListMode = "omit"      // Omit partition list and count, implying just 1 partition
)

Constants enumerating valid PartitionListMode values.

type PartitioningMode added in v0.10.4 

type PartitioningMode int

PartitioningMode enumerates ways of handling partitioning status -- that is, presence or lack of a PARTITION BY clause. 

const (
	PartitioningPermissive PartitioningMode = iota // don't negate any partitioning-related clauses
	PartitioningRemove                             // negate PARTITION BY clauses from DDL
	PartitioningKeep                               // negate REMOVE PARTITIONING clauses from ALTERs
)

Constants for how to handle partitioning status differences.

type RemovePartitioning added in v0.10.4 

type RemovePartitioning struct{}

RemovePartitioning represents de-partitioning a previously-partitioned table. It satisfies the TableAlterClause interface.

func (RemovePartitioning) Clause added in v0.10.4 

func (rp RemovePartitioning) Clause(mods StatementModifiers) string

Clause returns a clause of an ALTER TABLE statement that partitions a previously-unpartitioned table.

type RenameColumn 

type RenameColumn struct {
	OldColumn *Column
	NewName   string
}

RenameColumn represents a column that exists in both versions of the table, but with a different name. It satisfies the TableAlterClause interface.

func (RenameColumn) Clause 

func (rc RenameColumn) Clause(_ StatementModifiers) string

Clause returns a CHANGE COLUMN clause of an ALTER TABLE statement.

func (RenameColumn) Unsafe 

func (rc RenameColumn) Unsafe() bool

Unsafe returns true if this clause is potentially destructive of data. RenameColumn is always considered unsafe, despite it not directly destroying data, because it is high-risk for interfering with application logic that may be continuing to use the old column name.

type Routine added in v0.8.14 

type Routine struct {
	Name              string     `json:"name"`
	Type              ObjectType `json:"type"`                     // Will be ObjectTypeProcedure or ObjectTypeFunction
	Body              string     `json:"body"`                     // Has correct escaping despite I_S mutilating it
	ParamString       string     `json:"paramString"`              // Formatted as per original CREATE
	ReturnDataType    string     `json:"returnDataType,omitempty"` // Includes charset/collation when relevant
	Definer           string     `json:"definer"`
	DatabaseCollation string     `json:"dbCollation"` // from creation time
	Comment           string     `json:"comment,omitempty"`
	Deterministic     bool       `json:"deterministic,omitempty"`
	SQLDataAccess     string     `json:"sqlDataAccess,omitempty"`
	SecurityType      string     `json:"securityType"`
	SQLMode           string     `json:"sqlMode"`    // sql_mode in effect at creation time
	CreateStatement   string     `json:"showCreate"` // complete SHOW CREATE obtained from an instance
}

Routine represents a stored procedure or function.

func (*Routine) Definition added in v0.8.14 

func (r *Routine) Definition(flavor Flavor) string

Definition generates and returns a canonical CREATE PROCEDURE or CREATE FUNCTION statement based on the Routine's Go field values.

func (*Routine) DropStatement added in v0.8.14 

func (r *Routine) DropStatement() string

DropStatement returns a SQL statement that, if run, would drop this routine.

func (*Routine) Equals added in v0.8.14 

func (r *Routine) Equals(other *Routine) bool

Equals returns true if two routines are identical, false otherwise.

type RoutineDiff added in v0.8.14 

type RoutineDiff struct {
	From        *Routine
	To          *Routine
	ForMetadata bool // if true, routine is being replaced only to update creation-time metadata
}

RoutineDiff represents a difference between two routines.

func (*RoutineDiff) DiffType added in v0.8.14 

func (rd *RoutineDiff) DiffType() DiffType

DiffType returns the type of diff operation.

func (*RoutineDiff) ObjectKey added in v0.8.14 

func (rd *RoutineDiff) ObjectKey() ObjectKey

ObjectKey returns a value representing the type and name of the routine being diff'ed. The type will be either ObjectTypeFunc or ObjectTypeProc. The name will be the From side routine, unless this is a Create, in which case the To side routine name is used.

func (*RoutineDiff) Statement added in v0.8.14 

func (rd *RoutineDiff) Statement(mods StatementModifiers) (string, error)

Statement returns the full DDL statement corresponding to the RoutineDiff. A blank string may be returned if the mods indicate the statement should be skipped. If the mods indicate the statement should be disallowed, it will still be returned as-is, but the error will be non-nil. Be sure not to ignore the error value of this method.

type Schema 

type Schema struct {
	Name      string     `json:"databaseName"`
	CharSet   string     `json:"defaultCharSet"`
	Collation string     `json:"defaultCollation"`
	Tables    []*Table   `json:"tables,omitempty"`
	Routines  []*Routine `json:"routines,omitempty"`
}

Schema represents a database schema.

func (*Schema) AlterStatement 

func (s *Schema) AlterStatement(charSet, collation string) string

AlterStatement returns a SQL statement that, if run, would alter this schema's default charset and/or collation to the supplied values. If charSet is "" and collation isn't, only the collation will be changed. If collation is "" and charSet isn't, the default collation for charSet is used automatically. If both params are "", or if values equal to the schema's current charSet and collation are supplied, an empty string is returned.

func (*Schema) CreateStatement 

func (s *Schema) CreateStatement() string

CreateStatement returns a SQL statement that, if run, would create this schema.

func (*Schema) Diff 

func (s *Schema) Diff(other *Schema) *SchemaDiff

Diff returns the set of differences between this schema and another schema.

func (*Schema) DropStatement 

func (s *Schema) DropStatement() string

DropStatement returns a SQL statement that, if run, would drop this schema.

func (*Schema) FunctionsByName added in v0.8.14 

func (s *Schema) FunctionsByName() map[string]*Routine

FunctionsByName returns a mapping of function names to Routine struct pointers, for all functions in the schema.

func (*Schema) HasTable 

func (s *Schema) HasTable(name string) bool

HasTable returns true if a table with the given name exists in the schema.

func (*Schema) ObjectDefinitions added in v0.8.14 

func (s *Schema) ObjectDefinitions() map[ObjectKey]string

ObjectDefinitions returns a mapping of ObjectKey (type+name) to an SQL string containing the corresponding CREATE statement, for all supported object types in the schema. Note that the returned map does NOT include an entry for the schema itself.

func (*Schema) ProceduresByName added in v0.8.14 

func (s *Schema) ProceduresByName() map[string]*Routine

ProceduresByName returns a mapping of stored procedure names to Routine struct pointers, for all stored procedures in the schema.

func (*Schema) Table 

func (s *Schema) Table(name string) *Table

Table returns a table by name.

func (*Schema) TablesByName 

func (s *Schema) TablesByName() map[string]*Table

TablesByName returns a mapping of table names to Table struct pointers, for all tables in the schema.

type SchemaCreationOptions added in v0.10.4 

type SchemaCreationOptions struct {
	DefaultCharSet   string
	DefaultCollation string
	SkipBinlog       bool
}

SchemaCreationOptions specifies schema-level metadata when creating or altering a database.

type SchemaDiff 

type SchemaDiff struct {
	FromSchema   *Schema
	ToSchema     *Schema
	TableDiffs   []*TableDiff   // a set of statements that, if run, would turn tables in FromSchema into ToSchema
	RoutineDiffs []*RoutineDiff // " but for funcs and procs
}

SchemaDiff represents a set of differences between two database schemas, encapsulating diffs of various different object types.

func NewSchemaDiff 

func NewSchemaDiff(from, to *Schema) *SchemaDiff

NewSchemaDiff computes the set of differences between two database schemas.

func (*SchemaDiff) DatabaseDiff added in v0.8.13 

func (sd *SchemaDiff) DatabaseDiff() *DatabaseDiff

DatabaseDiff returns an object representing database-level DDL (CREATE DATABASE, ALTER DATABASE, DROP DATABASE), or nil if no database-level DDL is necessary.

func (*SchemaDiff) FilteredTableDiffs 

func (sd *SchemaDiff) FilteredTableDiffs(onlyTypes ...DiffType) []*TableDiff

FilteredTableDiffs returns any TableDiffs of the specified type(s).

func (*SchemaDiff) ObjectDiffs added in v0.8.13 

func (sd *SchemaDiff) ObjectDiffs() []ObjectDiff

ObjectDiffs returns a slice of all ObjectDiffs in the SchemaDiff. The results are returned in a sorted order, such that the diffs' Statements are legal. For example, if a CREATE DATABASE is present, it will occur in the slice prior to any table-level DDL in that schema.

func (*SchemaDiff) String 

func (sd *SchemaDiff) String() string

String returns the set of differences between two schemas as a single string. In building this string representation, note that no statement modifiers are applied, and any errors from Statement() are ignored. This means the returned string may contain destructive statements, and should only be used for display purposes, not for DDL execution.

type StatementModifiers 

type StatementModifiers struct {
	NextAutoInc            NextAutoIncMode  // How to handle differences in next-auto-inc values
	Partitioning           PartitioningMode // How to handle differences in partitioning status
	AllowUnsafe            bool             // Whether to allow potentially-destructive DDL (drop table, drop column, modify col type, etc)
	LockClause             string           // Include a LOCK=[value] clause in generated ALTER TABLE
	AlgorithmClause        string           // Include an ALGORITHM=[value] clause in generated ALTER TABLE
	IgnoreTable            *regexp.Regexp   // Generate blank DDL if table name matches this regexp
	StrictIndexOrder       bool             // If true, maintain index order even in cases where there is no functional difference
	StrictCheckOrder       bool             // If true, maintain check constraint order even though it never has a functional difference
	StrictForeignKeyNaming bool             // If true, maintain foreign key definition even if differences are cosmetic (name change, RESTRICT vs NO ACTION, etc)
	CompareMetadata        bool             // If true, compare creation-time sql_mode and db collation for funcs, procs (and eventually events, triggers)
	VirtualColValidation   bool             // If true, add WITH VALIDATION clause for ALTER TABLE affecting virtual columns
	SkipPreDropAlters      bool             // If true, skip ALTERs that were only generated to make DROP TABLE faster
	Flavor                 Flavor           // Adjust generated DDL to match vendor/version. Zero value is FlavorUnknown which makes no adjustments.
}

StatementModifiers are options that may be applied to adjust the DDL emitted for a particular table, and/or generate errors if certain clauses are present.

type Table 

type Table struct {
	Name               string             `json:"name"`
	Engine             string             `json:"storageEngine"`
	CharSet            string             `json:"defaultCharSet"`
	Collation          string             `json:"defaultCollation"`
	CollationIsDefault bool               `json:"collationIsDefault"`      // true if Collation is default for CharSet
	CreateOptions      string             `json:"createOptions,omitempty"` // row_format, stats_persistent, stats_auto_recalc, etc
	Columns            []*Column          `json:"columns"`
	PrimaryKey         *Index             `json:"primaryKey,omitempty"`
	SecondaryIndexes   []*Index           `json:"secondaryIndexes,omitempty"`
	ForeignKeys        []*ForeignKey      `json:"foreignKeys,omitempty"`
	Checks             []*Check           `json:"checks,omitempty"`
	Comment            string             `json:"comment,omitempty"`
	NextAutoIncrement  uint64             `json:"nextAutoIncrement,omitempty"`
	Partitioning       *TablePartitioning `json:"partitioning,omitempty"`       // nil if table isn't partitioned
	UnsupportedDDL     bool               `json:"unsupportedForDiff,omitempty"` // If true, tengo cannot diff this table or auto-generate its CREATE TABLE
	CreateStatement    string             `json:"showCreateTable"`              // complete SHOW CREATE TABLE obtained from an instance
}

Table represents a single database table.

func (*Table) AlterStatement 

func (t *Table) AlterStatement() string

AlterStatement returns the prefix to a SQL "ALTER TABLE" statement.

func (*Table) ClusteredIndexKey 

func (t *Table) ClusteredIndexKey() *Index

ClusteredIndexKey returns which index is used for an InnoDB table's clustered index. This will be the primary key if one exists; otherwise, it will be the first unique key with non-nullable columns. If there is no such key, or if the table's engine isn't InnoDB, this method returns nil.

func (*Table) ColumnsByName 

func (t *Table) ColumnsByName() map[string]*Column

ColumnsByName returns a mapping of column names to Column value pointers, for all columns in the table.

func (*Table) Diff 

func (t *Table) Diff(to *Table) (clauses []TableAlterClause, supported bool)

Diff returns a set of differences between this table and another table.

func (*Table) DropStatement 

func (t *Table) DropStatement() string

DropStatement returns a SQL statement that, if run, would drop this table.

func (*Table) GeneratedCreateStatement 

func (t *Table) GeneratedCreateStatement(flavor Flavor) string

GeneratedCreateStatement generates a CREATE TABLE statement based on the Table's Go field values. If t.UnsupportedDDL is false, this will match the output of MySQL's SHOW CREATE TABLE statement. But if t.UnsupportedDDL is true, this means the table uses MySQL features that Tengo does not yet support, and so the output of this method will differ from MySQL.

func (*Table) HasAutoIncrement 

func (t *Table) HasAutoIncrement() bool

HasAutoIncrement returns true if the table contains an auto-increment column, or false otherwise.

func (*Table) RowFormatClause added in v0.8.10 

func (t *Table) RowFormatClause() string

RowFormatClause returns the table's ROW_FORMAT clause, if one was explicitly specified in the table's creation options. If no ROW_FORMAT clause was specified, but a KEY_BLOCK_SIZE is, "COMPRESSED" will be returned since MySQL applies this automatically. If no ROW_FORMAT or KEY_BLOCK_SIZE was specified, a blank string is returned. This method does not query an instance to determine if the table's actual ROW_FORMAT differs from what was requested in creation options; nor does it query the default row format if none was specified.

func (*Table) SecondaryIndexesByName 

func (t *Table) SecondaryIndexesByName() map[string]*Index

SecondaryIndexesByName returns a mapping of index names to Index value pointers, for all secondary indexes in the table.

func (*Table) UnpartitionedCreateStatement added in v0.10.4 

func (t *Table) UnpartitionedCreateStatement(flavor Flavor) string

UnpartitionedCreateStatement returns the table's CREATE statement without its PARTITION BY clause. Supplying an accurate flavor improves performance, but is not required; FlavorUnknown still works correctly.

type TableAlterClause 

type TableAlterClause interface {
	Clause(StatementModifiers) string
}

TableAlterClause interface represents a specific single-element difference between two tables. Structs satisfying this interface can generate an ALTER TABLE clause, such as ADD COLUMN, MODIFY COLUMN, ADD KEY, etc.

type TableDiff 

type TableDiff struct {
	Type DiffType
	From *Table
	To   *Table
	// contains filtered or unexported fields
}

TableDiff represents a difference between two tables.

func NewAlterTable 

func NewAlterTable(from, to *Table) *TableDiff

NewAlterTable returns a *TableDiff representing an ALTER TABLE statement, i.e. a table that exists in the "from" and "to" side schemas but with one or more differences. If the supplied tables are identical, nil will be returned instead of a TableDiff.

func NewCreateTable 

func NewCreateTable(table *Table) *TableDiff

NewCreateTable returns a *TableDiff representing a CREATE TABLE statement, i.e. a table that only exists in the "to" side schema in a diff.

func NewDropTable 

func NewDropTable(table *Table) *TableDiff

NewDropTable returns a *TableDiff representing a DROP TABLE statement, i.e. a table that only exists in the "from" side schema in a diff.

func PreDropAlters added in v0.10.4 

func PreDropAlters(table *Table) []*TableDiff

PreDropAlters returns a slice of *TableDiff to run prior to dropping a table. For tables partitioned with RANGE or LIST partitioning, this returns ALTERs to drop all partitions but one. In all other cases, this returns nil.

func (*TableDiff) Clauses 

func (td *TableDiff) Clauses(mods StatementModifiers) (string, error)

Clauses returns the body of the statement represented by the table diff. For DROP statements, this will be an empty string. For CREATE statements, it will be everything after "CREATE TABLE [name] ". For ALTER statements, it will be everything after "ALTER TABLE [name] ".

func (*TableDiff) DiffType added in v0.8.13 

func (td *TableDiff) DiffType() DiffType

DiffType returns the type of diff operation.

func (*TableDiff) ObjectKey added in v0.8.14 

func (td *TableDiff) ObjectKey() ObjectKey

ObjectKey returns a value representing the type and name of the table being diff'ed. The type is always ObjectTypeTable. The name will be the From side table, unless the diffType is DiffTypeCreate, in which case the To side table name is used.

func (*TableDiff) SplitAddForeignKeys 

func (td *TableDiff) SplitAddForeignKeys() (*TableDiff, *TableDiff)

SplitAddForeignKeys looks through a TableDiff's alterClauses and pulls out any AddForeignKey clauses into a separate TableDiff. The first returned TableDiff is guaranteed to contain no AddForeignKey clauses, and the second returned value is guaranteed to only consist of AddForeignKey clauses. If the receiver contained no AddForeignKey clauses, the first return value will be the receiver, and the second will be nil. If the receiver contained only AddForeignKey clauses, the first return value will be nil, and the second will be the receiver. This method is useful for several reasons: it is desirable to only add FKs after other alters have been made (since FKs rely on indexes on both sides); it is illegal to drop and re-add an FK with the same name in the same ALTER; some versions of MySQL recommend against dropping and adding FKs in the same ALTER even if they have different names.

func (*TableDiff) SplitConflicts added in v0.10.4 

func (td *TableDiff) SplitConflicts() (result []*TableDiff)

SplitConflicts looks through a TableDiff's alterClauses and pulls out any clauses that need to be placed into a separate TableDiff in order to yield legal or error-free DDL. Currently this only handles attempts to add multiple FULLTEXT indexes in a single ALTER, but may handle additional cases in the future. This method returns a slice of TableDiffs. The first element will be equivalent to the receiver (td) with any conflicting clauses removed; subsequent slice elements, if any, will be separate TableDiffs each consisting of individual conflicting clauses. This method does not interact with AddForeignKey clauses; see dedicated method SplitAddForeignKeys for that logic.

func (*TableDiff) Statement 

func (td *TableDiff) Statement(mods StatementModifiers) (string, error)

Statement returns the full DDL statement corresponding to the TableDiff. A blank string may be returned if the mods indicate the statement should be skipped. If the mods indicate the statement should be disallowed, it will still be returned as-is, but the error will be non-nil. Be sure not to ignore the error value of this method.

type TablePartitioning added in v0.10.4 

type TablePartitioning struct {
	Method             string            `json:"method"`              // one of "RANGE", "RANGE COLUMNS", "LIST", "LIST COLUMNS", "HASH", "LINEAR HASH", "KEY", or "LINEAR KEY"
	SubMethod          string            `json:"subMethod,omitempty"` // one of "" (no sub-partitioning), "HASH", "LINEAR HASH", "KEY", or "LINEAR KEY"; not fully supported yet
	Expression         string            `json:"expression"`
	SubExpression      string            `json:"subExpression,omitempty"` // empty string if no sub-partitioning; not fully supported yet
	Partitions         []*Partition      `json:"partitions"`
	ForcePartitionList PartitionListMode `json:"forcePartitionList,omitempty"`
	AlgoClause         string            `json:"algoClause,omitempty"` // full text of optional ALGORITHM clause for KEY or LINEAR KEY
}

TablePartitioning stores partitioning configuration for a partitioned table. Note that despite subpartitioning fields being present and possibly populated, the rest of this package does not fully support subpartitioning yet.

func (*TablePartitioning) Definition added in v0.10.4 

func (tp *TablePartitioning) Definition(flavor Flavor) string

Definition returns the overall partitioning definition for a table.

func (*TablePartitioning) Diff added in v0.10.4 

func (tp *TablePartitioning) Diff(other *TablePartitioning) (clauses []TableAlterClause, supported bool)

Diff returns a set of differences between this TablePartitioning and another TablePartitioning. If supported==true, the returned clauses (if executed) would transform tp into other.

type Unsafer 

type Unsafer interface {
	Unsafe() bool
}

Unsafer interface represents a type of clause that may have the ability to destroy data. Structs satisfying this interface can indicate whether or not this particular clause destroys data.

type UnsupportedDiffError 

type UnsupportedDiffError struct {
	ObjectKey      ObjectKey
	ExpectedCreate string
	ActualCreate   string
}

UnsupportedDiffError can be returned by ObjectDiff.Statement if Tengo is unable to transform the object due to use of unsupported features.

func (*UnsupportedDiffError) Error 

func (e *UnsupportedDiffError) Error() string

Error satisfies the builtin error interface.

func (*UnsupportedDiffError) ExtendedError 

func (e *UnsupportedDiffError) ExtendedError() string

ExtendedError returns a string with more information about why the diff is not supported.

type Vendor added in v0.8.2 

type Vendor int

Vendor distinguishes between different database distributions/forks 

const (
	VendorUnknown Vendor = iota
	VendorMySQL
	VendorPercona
	VendorMariaDB
)

Constants representing different supported vendors

func ParseVendor added in v0.8.2 

func ParseVendor(versionComment string) Vendor

ParseVendor takes a version comment string (e.g. @@version_comment MySQL variable) and returns the corresponding Vendor constant, defaulting to VendorUnknown if the string is not recognized.

func (Vendor) String added in v0.8.2 

func (v Vendor) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.