Request for comments: Skeema v2 roadmap

May 12, 2025

Development of Skeema v2 is now underway, with a release target of later this year. We’re excited to share an overview of the potential changes, and would love to hear your feedback.

New functionality

This isn’t a complete list, and all plans are still tentative at this early stage, but here are three of the most impactful new features being considered for the initial 2.0 release.

skeema exec: New command for finer-grained lint/diff/push

Currently, all of Skeema’s subcommands process a subdirectory at a time, performing operations for an entire logical database schema. Synchronizing a schema/directory is a very straightforward workflow for manual use, but it can be unnecessarily rigid when building a larger automation pipeline on top of the Skeema CLI.

To provide more flexibility for power users, a new CLI subcommand will unlock entirely new workflows and capabilities:

  • Partial applier: Lint, diff, or push only the objects in specific .sql files, instead of an entire directory
  • Streaming input: Ability to pipe SQL from STDIN, instead of using .sql files at all
  • Dynamic targeting: Specify host and schema on the command-line, rather than using a named environment
  • Coexist with incremental migration flows: Use Skeema’s linter, safety checks, and OSC wrapping functionality directly on ALTER TABLE statements from an imperative migration tool

Future 2.x releases may expand the automation possibilities further by adding JSON output mode and optional Git integrations.

Improved INSTANT table alterations

In modern MySQL and MariaDB, some types of table alterations can be performed instantly. In these situations, running a direct ALTER TABLE is generally preferable to invoking a much-slower external OSC tool. Although Skeema v1 already provides the ability to bypass an OSC tool on the command-line (e.g. skeema push --skip-alter-wrapper --alter-algorithm=instant), currently that requires manual intervention on a case-by-case basis.

Some OSC tools, such as gh-ost and spirit, offer a built-in ability to attempt INSTANT alteration before falling back to their usual shadow-table build process. This is a nice quality-of-life improvement overall. However, these tools don’t provide a way to preview ahead-of-time whether a given ALTER TABLE can use INSTANT, making it difficult to predict the time required for the operation. There are also inherent risks with this approach, since instantly-altered tables have been affected by edge-case server bugs, including one that was fixed as recently as MySQL 8.0.40 (Oct 2024).

Skeema is well-positioned to provide a more comprehensive solution here, since it fully introspects table state and has a complete understanding of the ALTER TABLE clauses it is emitting. Planned INSTANT improvements in Skeema v2 include:

  • Output logging of skeema diff can show whether INSTANT is usable for each ALTER TABLE
  • Exit-code-based ability to determine whether all changes in a diff are INSTANT, for use in automation pipelines
  • skeema push can automatically bypass alter-wrapper for alterations where INSTANT can be used safely
  • Avoid INSTANT in cases where there are known bugs in your version of MySQL or MariaDB
  • Skip INSTANT for empty tables in MySQL, to avoid wasting total_row_versions (mimicking a server change normally only found in very recent MySQL point releases)

Due to the development time involved in mapping out all INSTANT edge cases for various alteration types and server versions, most aspects of this feature will only be found in Skeema Premium, but some related improvements will be made to Skeema Community as well.

Expanding support for MariaDB objects

Skeema v2 will likely add support for several MariaDB-only features, such as:

  • System-versioned tables
  • Sequences
  • Routine packages

These will most likely be added incrementally. For example, Skeema 2.0 might add initial support for creating (but not diffing/altering) system-versioned tables, with expanded support coming in a future 2.x release.

Behavior changes and backwards compatibility

Throughout Skeema’s nine-year development history, we’ve largely avoided backwards-incompatible changes in our periodic v1.x feature releases. With Skeema v2, we finally have an opportunity to iron out some old wrinkles. We’re avoiding any overly-drastic breaking changes, but there may still be a few things that affect your configuration.

For any functionality scheduled for outright removal in Skeema v2, deprecation warnings will be logged starting in the upcoming Skeema v1.12.4 point release.

Dropping support for ancient database versions

Historically, Skeema has only added support for new versions of MySQL and MariaDB over time, but never pruned old ones. However, as both database vendors moved to a “new features every quarter” release model in recent years, supporting an ever-growing range of server versions has become impractical.

As such, Skeema v2 will drop support for MySQL 5.5 (GA Dec 2010, EOL Dec 2018) and MariaDB 10.1 (GA Jun 2014, EOL Oct 2020). Given their age, these server versions are nearly unused in the industry today. Removing them from our codebase will simplify our integration testing and release overhead, and allow the deletion of some old conditional logic. For example, MySQL 5.5 does not even support InnoDB online DDL (ALGORITHM and LOCK clauses) at all.

Skeema v2 will also likely deprecate (but not remove) support for MySQL 5.6, MariaDB 10.2, and possibly other versions that have been EOL for multiple years. These server versions will still be fully supported in Skeema v2.x, but a warning log will be emitted, with full removal occurring in a future Skeema v3. Moving forwards, we anticipate new Skeema major version releases every 12 to 24 months.

Potential configuration changes

Option file naming: Skeema has always used directory-level .skeema files to store cascading configuration. These files are automatically hidden on Unix-like operating systems, which may or may not be desirable for Skeema configuration. For v2, we are considering a move to a non-hidden underscore-prefixed naming scheme, such as _skeema.cnf or similar, while still supporting the old .skeema naming as well. The goal would be to make the configuration more explicit, while still keeping the file name sorted at the top of the directory list.

Deprecating connect-options: In Skeema v1, this option controls database session variables and client-side driver/connection-level fields, which is confusing. In v2, we may support direct use of SET SQL statements as the preferred approach for session variables, while adding dedicated options for some driver-level fields. Use of connect-options would still be supported in v2, but with a deprecation warning log.

Docker workspaces and tmpfs: Recent Skeema releases have massively improved the performance of workspace=docker, including use of an in-memory tmpfs data mount whenever docker-cleanup=destroy is explicitly configured. In v2, we plan to move this tmpfs behavior to a separate option, which will be enabled by default. Since Skeema workspace metadata is always inherently ephemeral, tmpfs can be beneficial regardless of the overall container’s lifecycle.

AUTO_INCREMENT column type linting: The default value for allow-auto-inc has always excluded signed types, since storing negative numbers in an AUTO_INCREMENT column is typically unnecessary. However, over the years we’ve found this default creates far more noise than any other linter rule, so Skeema v2 will adjust the default to include both signed and unsigned types.

Dumping multiple schemas: When running skeema init without a specific --schema, currently all databases are dumped, and a multi-level directory layout is created – even if the server only has one non-system schema. This behavior may become explicitly opt-in (perhaps like mysqldump’s use of --all-databases) or otherwise be improved to reduce confusion for new users. Similarly, the default for skeema pull would likely be reversed so that --new-schemas must be provided explicitly if you wish to auto-detect and dump any new / previously-unexported schemas.

No auto-reformatting: In Skeema v1, by default both skeema lint and skeema pull reformat all CREATE statements to use the database server’s canonical format, unless you supply option --skip-format. In Skeema v2+, this default will flip, so that you must explicitly enable --format to get that behavior. The old default reformatting behavior predated the existence of the separate skeema format command, and makes less sense with its presence.

Removal of unnecessary options: To reduce cognitive overload, several options are being considered for removal.

Community discussions

We warmly welcome community feedback on all of these proposed changes, as well as suggestions for additional items to consider. Share your thoughts on the GitHub Discussions thread.