Categorygithub.com/planetscale/tengo
modulepackage
0.10.3-ps.v9-vitess
Repository: https://github.com/planetscale/tengo.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
20
Dependents
0
Files
5.2k SLOC

# README

Go La Tengo

build status code coverage godoc latest release

Golang library for MySQL and MariaDB database automation

PlanetScale fork

This is a fork of upstream https://github.com/skeema/tengo

It has a few modifications specific to Vitess that do not make sense to add upstream.

Otherwise it adds some changes that make sense to contribute back. We generate patch files for those, and we are happy if upstream receives them.

PlanetScale: use ./planetscale/release.sh to generate new releases (both for close-tracking of upstream as well as stripped down release for Vitess)

Features

Schema introspection and diff

Go La Tengo examines several information_schema tables in order to build Go struct values representing schemas (databases), tables, columns, indexes, foreign key constraints, stored procedures, and functions. These values can be diff'ed to generate corresponding DDL statements.

Instance modeling

The tengo.Instance struct models a single database instance. It keeps track of multiple, separate connection pools for using different default schema and session settings. This helps to avoid problems with Go's database/sql methods, which are incompatible with USE statements and SET SESSION statements.

Status

This is package is battle-tested from years of production use at many companies. The release numbering is still pre-1.0 though as the API is subject to minor changes. Backwards-incompatible changes are generally avoided whenever possible, but no guarantees are made.

As of September 2021, open source development of this repo is mostly frozen until further notice.

Supported databases

Tagged releases are tested against the following databases, all running on Linux:

  • MySQL 5.5 - 8.0
  • Percona Server 5.5 - 8.0
  • MariaDB 10.1 - 10.6

Outside of a tagged release, every commit to the main branch is automatically tested against MySQL 5.7 and 8.0.

Unsupported in table diffs

Go La Tengo cannot diff tables containing any of the following MySQL features:

  • spatial indexes
  • sub-partitioning (two levels of partitioning in the same table)
  • special features of non-InnoDB storage engines

Go La Tengo also does not yet support rename operations, e.g. column renames or table renames.

Ignored object types

The following object types are completely ignored by this package. Their presence won't break anything, but they will not be introspected or represented by the structs in this package.

  • views
  • triggers
  • events
  • grants / users / roles

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.

# Functions

EscapeIdentifier is for use in safely escaping MySQL identifiers (table names, column names, etc).
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.
IsAccessError returns true if err indicates an authentication or authorization problem, at connection time or query time.
IsDatabaseError returns true if err came from a database server, typically as a response to a query or connection attempt.
IsForbiddenDiff returns true if err represents an "unsafe" alteration that has not explicitly been permitted by the supplied StatementModifiers.
IsSyntaxError returns true if err is a SQL syntax error, or false otherwise.
IsUnsupportedDiff returns true if err represents an object that cannot be diff'ed due to use of features not supported by this package.
NewAlterTable returns a *TableDiff representing an ALTER TABLE statement, i.e.
NewAlterView returns a *ViewDiff representing an ALTER TABLE statement, i.e.
NewCreateTable returns a *TableDiff representing a CREATE TABLE statement, i.e.
NewCreateView returns a *ViewDiff representing a CREATE VIEW statement, i.e.
NewDropTable returns a *TableDiff representing a DROP TABLE statement, i.e.
NewDropView returns a *ViewDiff representing a DROP TABLE statement, i.e.
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").
NewInstance returns a pointer to a new Instance corresponding to the supplied driver and dsn.
NewSchemaDiff computes the set of differences between two database schemas.
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.
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.
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.
ParseFlavor returns a Flavor value based on inputs obtained from server vars @@global.version and @@global.version_comment.
ParseVendor takes a version comment string (e.g.
ParseVersion takes a version string (e.g.
PreDropAlters returns a slice of *TableDiff to run prior to dropping a table.
QuerySchemaTable reads and returns a single, specific table.
QuerySchemaView reads and returns a single, specific view.
RunSuite runs all test methods in the supplied suite once per backend.
SplitEnv examines the specified environment variable and splits its value on commas to return a list of strings.
SplitHostOptionalPort takes an address string containing a hostname, ipv4 addr, or ipv6 addr; *optionally* followed by a colon and port number.
StripDisplayWidth removes integer display width from the supplied column type string, in a way that matches MySQL 8.0.19+'s behavior.

# Constants

Constants representing the types of diff operations.
Constants representing the types of diff operations.
Constants representing the types of diff operations.
Constants representing the types of diff operations.
Constants representing the types of diff operations.
always include auto-inc value in diff.
only include auto-inc value if the "from" side is already greater than 1.
only include auto-inc value if the "from" side is less than the "to" side.
omit auto-inc value changes in diff.
Constants enumerating valid object types.
Constants enumerating valid object types.
Constants enumerating valid object types.
Constants enumerating valid object types.
Constants enumerating valid object types.
negate REMOVE PARTITIONING clauses from ALTERs.
don't negate any partitioning-related clauses.
negate PARTITION BY clauses from DDL.
Just use a count of partitions.
Default behavior based on partitioning method.
List each partition individually.
Omit partition list and count, implying just 1 partition.
Constants representing different supported vendors.
Constants representing different supported vendors.
Constants representing different supported vendors.
Constants representing different supported vendors.

# Variables

FlavorMariaDB101 represents MariaDB 10.1.x.
FlavorMariaDB102 represents MariaDB 10.2.x.
FlavorMariaDB103 represents MariaDB 10.3.x.
FlavorMariaDB104 represents MariaDB 10.4.x.
FlavorMariaDB105 represents MariaDB 10.5.x.
FlavorMariaDB106 represents MariaDB 10.6.x.
FlavorMySQL55 represents MySQL 5.5.x.
FlavorMySQL56 represents MySQL 5.6.x.
FlavorMySQL57 represents MySQL 5.7.x.
FlavorMySQL80 represents MySQL 8.0.x.
FlavorPercona55 represents Percona Server 5.5.x.
FlavorPercona56 represents Percona Server 5.6.x.
FlavorPercona57 represents Percona Server 5.7.x.
FlavorPercona80 represents Percona Server 8.0.x.
FlavorUnknown represents a flavor that cannot be parsed.

# Structs

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.
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.
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.
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.
AlterCheck represents a change in a check's enforcement status in MySQL 8+.
AlterIndex represents a change in an index's visibility in MySQL 8+ or MariaDB 10.6+.
BulkDropOptions controls how objects are dropped in bulk.
ChangeAlgorithm represents a difference in the algorithm of a view.
ChangeAutoIncrement represents a difference in next-auto-increment value between two versions of a table.
ChangeCharSet represents a difference in default character set and/or collation between two versions of a table.
ChangeCheckOption represents a difference in the check option of a view.
ChangeComment represents a difference in the table-level comment between two versions of a table.
ChangeCreateOptions represents a difference in the create options (row_format, stats_persistent, stats_auto_recalc, etc) between two versions of a table.
ChangeDefiner reprsents a difference in the definer of a view.
ChangeSecurityType represents a difference in the security type of a view.
ChangeStorageEngine represents a difference in the table's storage engine.
ChangeViewDefinition represents a difference in the definition within a view.
Check represents a single check constraint in a table.
Column represents a single column of a table.
DatabaseDiff represents differences of schema characteristics (default character set or default collation), or a difference in the existence of the the schema.
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.
DropColumn represents a column that was present on the left-side ("from") schema version of the table, but not the right-side ("to") version.
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.
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.
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).
ForbiddenDiffError can be returned by ObjectDiff.Statement when the supplied statement modifiers do not permit the generated ObjectDiff to be used in this situation.
ForeignKey represents a single foreign key constraint in a table.
Index represents a single index (primary key, unique secondary index, or non- unique secondard index) in a table.
IndexPart represents an individual indexed column or expression.
Instance represents a single database server running on a specific host or address.
ModifyColumn represents a column that exists in both versions of the table, but with a different definition.
ModifyPartitions represents a change to the partition list for a table using RANGE, RANGE COLUMNS, LIST, or LIST COLUMNS partitioning.
ObjectKey is useful as a map key for indexing database objects within a single schema.
Partition stores information on a single partition.
PartitionBy represents initially partitioning a previously-unpartitioned table, or changing the partitioning method and/or expression on an already- partitioned table.
RemovePartitioning represents de-partitioning a previously-partitioned table.
RenameColumn represents a column that exists in both versions of the table, but with a different name.
Routine represents a stored procedure or function.
RoutineDiff represents a difference between two routines.
Schema represents a database schema.
SchemaCreationOptions specifies schema-level metadata when creating or altering a database.
SchemaDiff represents a set of differences between two database schemas, encapsulating diffs of various different object types.
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.
Table represents a single database table.
TableDiff represents a difference between two tables.
TablePartitioning stores partitioning configuration for a partitioned table.
UnsupportedDiffError can be returned by ObjectDiff.Statement if Tengo is unable to transform the object due to use of unsupported features.
View represents a query stored as a view.
ViewDiff represents a diff between two views.

# Interfaces

IntegrationTestSuite is the interface for a suite of test methods.
ObjectDiff is an interface allowing generic handling of differences between two objects.
TableAlterClause interface represents a specific single-element difference between two tables.
Unsafer interface represents a type of clause that may have the ability to destroy data.
ViewAlterClause interface represents a specific single-element difference between two views.

# Type aliases

DiffType enumerates possible ways that two objects differ.
NextAutoIncMode enumerates various ways of handling AUTO_INCREMENT discrepancies between two tables.
ObjectType defines a class of object in a relational database system.
PartitioningMode enumerates ways of handling partitioning status -- that is, presence or lack of a PARTITION BY clause.
PartitionListMode values control edge-cases for how the list of partitions is represented in SHOW CREATE TABLE.
Vendor distinguishes between different database distributions/forks.