Skeema currently supports the following databases:
- MySQL 5.5, 5.6, 5.7, 8.0
- Percona Server 5.6, 5.7
- MariaDB 10.1, 10.2, 10.3
Only the InnoDB storage engine is primarily supported. Other storage engines are often perfectly functional in Skeema, but it depends on whether any esoteric features of the engine are used.
Some MySQL features -- such as partitioned tables, fulltext indexes, and generated/virtual columns -- are not yet supported in Skeema's diff operations. Skeema automatically detects this situation, so there is no risk of generating an incorrect diff. If Skeema does not yet support a table/column feature that you need, please open a GitHub issue so that the work can be prioritized appropriately.
Skeema is not currently intended for use on multi-master replication topologies, including Galera, InnoDB Cluster, and traditional active-active master-master configurations. It also has not yet been evaluated on Amazon Aurora.
As of August 2018, support for MySQL 8.0 is still quite new and should be considered experimental. Please file an issue if you encounter anything unexpected.
The easiest way to run Skeema is with a user having SUPER privileges in MySQL. However, this isn't always practical or possible.
As described in the FAQ, most Skeema commands need to perform operations in a temporary schema that by default is created, used, and then dropped for each command invocation. The temporary schema name is _skeema_tmp by default, but this may be changed via the temp-schema option.
The MySQL user used by Skeema will need these privileges for the temporary schema:
CREATE-- to create the temporary schema, and create tables in itDROP-- to drop tables in the temporary schema, as well as the temporary schema itself when no longer in useSELECT-- to verify that tables are still empty prior to dropping themALTER-- to verify that generated DDL is correctINDEX-- to verify that generated DDL is correct with respect to manipulating indexes
You can prevent Skeema from dropping the temporary schema entirely after each run via the reuse-temp-schema option. In this case, Skeema will still leave the temporary schema empty (tableless) after each run, but won't drop the schema itself, nor need to recreate it on the next run. However, this doesn't remove the need for CREATE or DROP privileges on the temporary schema itself, as these privileges are still needed to create or drop tables in the schema.
In order for all functionality in Skeema to work, it needs the following privileges in your application schemas (i.e., all databases aside from system schemas and the temporary schema):
CREATE-- in order forskeema pushto execute CREATE TABLE statementsDROP-- in order forskeema push --allow-unsafeto execute DROP TABLE statements; omit this privilege on application schemas if you do not plan to ever drop tables via SkeemaALTER-- in order forskeema pushto execute ALTER TABLE statementsINDEX-- in order forskeema pushto execute ALTER TABLE statements that manipulate indexes
When first testing out Skeema, it is fine to omit these privileges if you do not plan on using skeema push initially. However, Skeema still needs some privilege to see each application schema (either SELECT on each database, or the global SHOW DATABASES privilege).
If using the alter-wrapper option to execute a third-party online schema change tool, you will likely need to provide additional privileges as required by the tool; or you may configure the third-party tool to connect to the database using a different user than Skeema does.
Skeema should not need to interact with the mysql system schema, nor with performance_schema.
Skeema interacts extensively with information_schema, but MySQL grants appropriate access automatically based on other privileges provided.
The SHOW DATABASES global privilege is recommended. Technically it should be redundant with the privileges granted on each application schema. However by granting SHOW DATABASES, other privilege problems become more obvious, e.g. when trying to diagnose why Skeema can't "see" one or more application schemas.
- Skeema does not perform online ALTERs unless configured to do so. Be aware that most regular ALTERs lock the table and may cause replication lag.
- Skeema does not automatically verify that there is sufficient free disk space to perform an ALTER operation.
- External online schema change tools can, in theory, be buggy and cause data loss. Skeema does not endorse or guarantee any particular third-party tool.
- There is no tracking of in-flight operations yet. This means in a large production environment where schema changes take a long time to run, it is the user's responsibility to ensure that Skeema is only run from one location in a manner that prevents concurrent execution. This will be improved in future releases.
- Accidentally running schema changes against a replica directly, instead of the master, may break replication. It is the user's responsibility to ensure that the host and port options in each
.skeemaconfiguration file point only to masters. - As with the vast majority of open source software, Skeema is distributed without warranties of any kind. See LICENSE.
Many of these will be added in future releases.
At this time, Skeema does not support configuring a specific client-side SSL cert or CA when connecting to MySQL.
The following features are completely ignored by Skeema. Their presence in a schema won't immediately break anything, but Skeema will not interact with them. This means that skeema init and skeema pull won't create file representations of them; skeema diff and skeema push will not detect or alter them.
- views
- triggers
- stored procedures
Skeema can CREATE or DROP tables using these features, but cannot ALTER them. The output of skeema diff and skeema push will note that it cannot generate or run ALTER TABLE for tables using these features, so the affected table(s) will be skipped, but the rest of the operation will proceed as normal.
- partitioned tables
- some features of non-InnoDB storage engines
- fulltext indexes
- spatial types
- generated/virtual columns (MySQL 5.7+)
- column-level compression, with or without predefined dictionary (Percona Server 5.6.33+)
You can still ALTER these tables externally from Skeema (e.g., direct invocation of ALTER TABLE or pt-online-schema-change). Afterwards, you can update your schema repo using skeema pull, which will work properly even on these tables.
Skeema cannot currently be used to rename columns within a table, or to rename entire tables. This is a shortcoming of Skeema's declarative approach: by expressing everything as a CREATE TABLE, there is no way for Skeema to know (with absolute certainty) the difference between a column rename vs dropping an existing column and adding a new column. A similar problem exists around renaming tables.
A solution may be added in a future release. The prioritization will depend on user demand. Many companies disallow renames in production anyway, as they present substantial deploy-order complexity (e.g. it's impossible to deploy application code changes at the exact same time as a column or table rename in the database).
Currently, Skeema will interpret attempts to rename as DROP-then-ADD operations. But since Skeema automatically flags any destructive action as unsafe, execution of these operations will be prevented unless the allow-unsafe option is used, or the table is below the size limit specified in the safe-below-size option.
Note that for empty tables as a special-case, a rename is technically equivalent to a DROP-then-ADD anyway. In Skeema, if you configure safe-below-size=1, the tool will permit this operation on tables with 0 rows. This is completely safe, and can aid in rapid development.
For tables with data, the work-around to handle renames is to do the appropriate ALTER TABLE manually (outside of Skeema) on all relevant databases. You can update your schema repo afterwards by running skeema pull.