Frequently Asked Questions

SchemaSmith is a database schema migration toolset that uses state-based deployments instead of hand-written ALTER scripts. You define the desired end-state of your schema as JSON metadata, and SchemaSmith generates the migration automatically.

The toolset includes SchemaTongs for extracting existing schemas, SchemaQuench for deploying changes, and DataTongs for exporting seed data. All three tools work across SQL Server, PostgreSQL, MySQL, and MariaDB and are free under the SchemaSmith Community License (SSCL v2.0) .

Migration-based: You write a series of numbered migration scripts (e.g., 001_AddColumn.sql, 002_CreateIndex.sql). Each script must be run in order, and you're responsible for handling conflicts and rollbacks.

State-based: You define what your schema should look like (the desired state), and the tool compares it to the current database state, automatically generating the required ALTER/CREATE scripts. This eliminates manual script writing and reduces merge conflicts.

Learn more in our Declarative vs Imperative Migrations comparison.

Yes. SchemaSmith is completely free for SQL Server, PostgreSQL, MySQL, and MariaDB under the SchemaSmith Community License (SSCL v2.0) . Any organization, any size, any number of environments.

The license permits using SchemaSmith to manage your own databases and products, whether you host them yourself or your customers do. It restricts redistributing SchemaSmith as a standalone product and operating it as an ongoing managed service on behalf of others. See the License FAQ for more details.

SchemaSmith supports these platforms, all free:

• Microsoft SQL Server: Version 2008 or higher (compatibility level 100+)
• PostgreSQL: Version 12 or higher
• MySQL: Version 5.7 or higher
• MariaDB: Version 10.2 or higher

Each platform uses its own schema definitions with platform-native DDL output. Same tools, same workflow, whichever engine you run.

1. Download SchemaSmith from our GitHub repository
2. Configure your connection in a settings file or via environment variables
3. Run SchemaTongs to extract your existing database schema
4. Review the generated metadata files
5. Use SchemaQuench to deploy changes to target environments

See our Getting Started guide for detailed instructions.

Absolutely! SchemaSmith is designed to work with existing databases. Use SchemaTongs to extract your current schema into metadata files, then use SchemaQuench to manage future changes. This is actually the recommended way to get started.

Metadata is a JSON representation of your database schema. It describes tables, columns, indexes, constraints, and other database objects in a structured, version-controllable format.

Unlike raw SQL scripts, metadata is declarative - you describe what you want, not how to get there. This makes it easier to review, merge, and maintain across teams and environments.

See Schema Packages for a deeper explanation of how metadata is organized.

1. Modify your metadata files (add a column, change a data type, etc.)
2. Commit the changes to source control
3. Run SchemaQuench against your target database
4. SchemaQuench compares the metadata to the live database and generates the required ALTER statements automatically

See the SchemaQuench Walkthrough for a detailed example.

SchemaQuench writes checkpoints as it progresses — every completed step and migration script is recorded to disk. If a deployment fails on a network blip, a lock timeout, or a bad data row at step 14 of 20, those checkpoint files stay in place, ready for recovery.

Re-run the same command with the --ResumeQuench flag and SchemaQuench skips any work already recorded as complete and picks up at the first incomplete step. By default, checkpoints live in your system's temp directory; override with --CheckpointDirectory if your CI runner's temp storage is ephemeral.

For clean deployments or CI pipelines that rebuild databases from scratch, leave --ResumeQuench off — there's no cost, and SchemaQuench clears checkpoint files automatically when a quench completes successfully.

DataTongs exports table data as deployable MERGE scripts, useful for seed data, lookup tables, and test data.

For complex data transformations during schema changes, SchemaSmith supports migration scripts - pre/post deployment scripts that run alongside the automated schema changes.

SchemaSmith is built by the engineering team behind it, and the written content on this site is published under that team's byline. The software is source-available under the SSCL v2.0 license — free for any use, including commercial and internal, with the source published on GitHub. You can modify it for your own use and contribute back, but you may not redistribute it. More on the team and how we work is on the About page.