Docs: FAQ

Is Skeema another online schema change tool?

No. Skeema is a tool for managing schemas, and the workflow around how schema changes are requested, reviewed, and performed. Skeema does not implement its own method for online schema changes, but it can be configured to shell out to any external online schema change tool. It can be used as a “glue” layer between git and online schema change tools, or as part of a continuous integration / continuous deployment pipeline, among other possibilities.

Skeema is designed to be a unified solution to the following common problems:

  • Exporting schemas to a repo and managing them like code, using pull requests and code review
  • Configuring use of an external online schema change tool, optionally only for certain table sizes, clusters, schema names, or environments
  • Enforcing company policies regarding schema design, and operational safety of schema changes
  • Keeping schemas in sync across development, staging, and production environments
  • Preventing schema drift across multiple shards

Is it safe for production?

Yes, absolutely. Schema changes can be scary, and this is why Skeema includes many forms of safety mechanisms to ensure correct operation.

Since its initial release in 2016, Skeema has been downloaded over 1.5 million times. A number of large well-known public tech companies have adopted Skeema as a critical part of their development and deployment toolchain. Between the Community and Premium editions, the Skeema CLI is now installed over 60,000 times per month, powering thousands of schema management operations worldwide every day among hundreds of companies.

Rest assured that safety of data is baked into Skeema’s DNA. Skeema’s creator has been using MySQL extensively since 2003, and is a former member of Facebook’s elite team responsible for maintaining and automating the world’s largest MySQL deployment. Prior to Facebook, he started and led the database engineering team at Tumblr, and created the open-source Ruby database automation library and shard-split tool Jetpants.

Skeema’s codebase has an extensive suite of unit, integration, and end-to-end functional tests. Every commit goes through automated testing against the most commonly-used versions of MySQL and MariaDB. For new Skeema releases, the test suite is run using every supported version of MySQL, MariaDB, and Percona Server. Skeema Premium is additionally tested against every supported version of Amazon Aurora.

All outside open source contributions are held to a high standard of code quality review and automated test coverage.

That all said, please see the requirements doc for important notes relating to running Skeema safely in your environment.

Do schema changes get pushed automatically when I change files?

No; the Skeema CLI is not a daemon / server. When using the CLI tool, schema changes only occur when you run skeema push.

To achieve automated deployment, you may optionally wrap skeema push in custom automation. The CLI is designed to be easy to integrate into a pipeline, in terms of exit codes and STDOUT vs STDERR. Additionally, Skeema Cloud Linter is designed to provide configurable guardrails around pull-request-driven automation pipelines.

Should I commit the per-directory .skeema config files to version control?

Yes, these files are designed to be versioned (for example in Git) along with the rest of your schema definitions.

To avoid storing passwords in Git, you can use an environment variable for them, or supply them interactively; see the password option doc. Alternatively, you can set the password option in a configuration file outside of your repo, such as ~/.my.cnf.

If you need to dynamically adjust connectivity options (host, schema, user, etc), use environment variables in .skeema files in Skeema v1.9+. For handling more complicated situations, you can use external program shell-outs in some cases.

I have several database schemas. How do I interact with just one at a time?

The simplest solution is to cd to the desired schema’s subdirectory before invoking skeema. Most Skeema commands operate recursively from the current working directory. This means you can run e.g. skeema diff from a parent directory to diff everything, or from a specific schema subdirectory to diff just that schema.

If you prefer to always invoke skeema from a parent / top-level directory, another solution is to leverage environment names in .skeema files. A bottom-level schema directory is only processed if its .skeema file defines the schema name option for the current environment. By default, skeema init places schema names in .skeema files “outside” of any environment section (applying to all environments), but you can freely edit this configuration to restrict subdirs to specific environment names.

For example, say you have multiple schemas, one of which is called “blog”. By default, skeema init makes blog/.skeema look something like this:


You could manually change it to this instead:





Now even if you invoke skeema from a parent directory, this directory will be processed when running skeema diff blog, skeema diff blog_dev, skeema diff production, or skeema diff with no environment (defaults to “production”). However, the blog directory will not be processed for skeema diff otherapp since it does not define a schema name in an “otherapp” section, nor does it define a default schema name “outside” (above) any section.

How do I configure Skeema to use online schema change tools?

Refer to the online schema change documentation page.

How do I force Skeema to use the database’s built-in online DDL functionality?

Refer to the online schema change documentation page.

How do I configure Skeema to use service discovery?

Our sharding documentation also describes use of service discovery. The techniques for dynamically mapping a directory to N databases can be used even if your database layout isn’t sharded (that is, N=1).