Getting Started with SchemaSmith for MariaDB

Extract a live MariaDB database to JSON files, deploy to a fresh target, and watch SchemaSmith compute the DDL. Full walk-through in about 15 minutes.

By the SchemaSmith Team · Last reviewed

Developer running SchemaSmith from a terminal alongside JSON schema files

In the next 15 minutes, you'll extract a real database into version-controlled files, deploy them to a fresh empty database, make a schema change, and watch SchemaSmith compute the exact DDL needed to bring the target in line.

Prerequisites

By the end, you'll have completed the full SchemaSmith cycle — and you'll understand why teams stop writing migration scripts once they've seen this. This walkthrough uses the Northwind demo database on MariaDB. Every supported engine has its own Getting Started walkthrough; pick yours from the documentation hub.

You need three things:

SchemaSmith tools. Get them from the downloads page.

A database server. Run the demo in containers if you have Docker and the .NET SDK, or on your own server if you already run MariaDB. The containers path uses the repository's Docker Compose file, which starts the demo server for you; the run-demo launcher compiles SchemaQuench before Docker Compose packages it, which is why the SDK is needed. To use your own server, see Use your own server below.

The repository. Clone the whole repository at the release the downloads page serves, so the demo scripts match the tools you installed. The demo packages live under Demos/, but the helpers that stand them up live in the folders above them, so do not download one folder on its own:

git clone --branch v2.8.0 https://github.com/Schema-Smith/SchemaSmith.git
cd SchemaSmith

The checkout stays on the tagged release, so git prints a "detached HEAD" notice. That is expected and harmless for running the demo.

Start the Demo Environment

Each platform has its own demo folder under Demos/ with a run-demo launcher, a docker-compose.yml, and a .env credentials file. From the repository root, launch the MariaDB demo:

cd Demos\MariaDB
run-demo.cmd
cd Demos/MariaDB
./run-demo.sh

The launcher runs build-schemaquench.cmd / .sh to compile the SchemaQuench binary (requires the .NET SDK on the host), then docker compose up --build packages that binary into a local Docker image, starts a MariaDB instance on port 3317, and deploys the demo databases using SchemaQuench. The launcher blocks until the completed service exits, which signals the databases are ready. Credentials live in Demos/MariaDB/.env:

SettingValue
MariaDBlocalhost:3317
UserTestUser
Password(see Demos/MariaDB/.env)

Use your own server

Already run MariaDB? Deploy the demo databases onto your own server instead of running them in containers. This path does not need Docker, but it does need the MariaDB command-line client on your PATH. Point one helper script at any reachable instance and it stands up the entire demo — the same databases the Docker demo builds, minus the containers.

The helper, deploy-to-endpoint, sits beside the Docker launcher in Demos/MariaDB/. It uses the engine's command-line client, mariadb, to create, stamp and drop the demo databases, so that client must be on your PATH. None are bundled; install it and re-open your shell: macOS: brew install mariadb. Linux: apt-get install mariadb-client / dnf install MariaDB-client. Windows: take the ZIP package and use its bin\mariadb.exe; winget install MariaDB.Server is server-and-all. Verify with mariadb --version. The helper calls mariadb, or mysql where that is the only client, as on MariaDB 10.2–10.4.

A client is not a server. On Windows the vendors mostly ship the client inside the server package, so a winget install puts a database service on your machine, bound to a default port — exactly where your existing server or containers already live. The ZIP archives hold the same executables with nothing to install and nothing to collide with.

Then give the helper your server and a login that can create and drop databases. It runs the schemaquench on your PATH, the one you installed above.

cd Demos\MariaDB
.\deploy-to-endpoint.ps1 -Server localhost -Port 3306 -User root -Password 'YourPassword'
cd Demos/MariaDB
./deploy-to-endpoint.sh --server localhost --port 3306 --user root --password 'YourPassword'

The port is a separate -Port / --port, shown with MariaDB's default. A user and password are always required.

On every run the helper resets — drops the demo databases it previously created, and only those — then creates the shared TestMain control database, then runs SchemaQuench against each demo package, exactly as the Docker demo does. Before dropping anything it prints the list of databases it will replace and waits for you to type yes; pass -Force (PowerShell) or --force (bash) to skip the prompt in automation.

It never touches a database it did not create. Each database it provisions carries a small SchemaSmith_DemoProvisioned marker table inside it, and if a demo name such as northwind already exists without that stamp — your real database — the helper stops and names the collision. To proceed, open Demos/MariaDB/demo-databases.manifest, change that row's NAME column to a free name, and re-run; only NAME changes:

product|demo_northwind|NorthwindDb|Northwind

In the steps that follow, use your own server address and login wherever this page shows the demo's localhost:3317 and TestUser. If you renamed a colliding demo database in the manifest, use that new name wherever this page shows northwind, or the later steps will point at your own real database.

Cast with SchemaTongs

Now let's go the other direction. Pretend you already have a database and want to bring it under SchemaSmith management. SchemaTongs grips your live schema and casts it into structured files. Create a SchemaTongs configuration file called tongs-extract.json:

{
  "Source": {
    "Platform": "MariaDb",
    "Server": "localhost",
    "Port": "3317",
    "User": "TestUser",
    "Password": "your-password-here",
    "Database": "northwind"
  },
  "Product": {
    "Path": "./my-northwind",
    "Name": "Northwind"
  },
  "Template": {
    "Name": "Northwind"
  },
  "ShouldCast": {
    "Tables": true,
    "Functions": true,
    "Views": true,
    "Procedures": true,
    "TableTriggers": true,
    "Events": true
  }
}

Run the extraction:

schematongs --ConfigFile:tongs-extract.json

Look at what appeared in the my-northwind/ folder. You now have a complete schema package:

my-northwind/
  Product.json                     ← Platform, templates, tokens
  .json-schemas/                   ← JSON Schema validation, generated on the fly
  Templates/
    Northwind/
      Template.json
      Tables/
        Categories.json
        Customers.json
        Orders.json
        ... (14 tables)
      Views/
        Alphabetical list of products.sql
        ...
      Procedures/
        CustOrderHist.sql
        ...
      Functions/
      Triggers/
      Events/
      Table Data/

One of those tables is recyclebin_Registry — part of the Northwind demo package itself, extracted like any other table in the database. Every table is a JSON file describing its columns, indexes, and constraints. Every stored procedure and view is a plain SQL file. This is your entire database — materialized as readable, diffable, reviewable source files. Commit this to source control and you have a complete history of every schema change from this point forward. For the full set of extraction options, see the SchemaTongs reference.

That's the cast. A live database, captured in files you can read, review, and version.

Explore the Package

No GUI editor needed — the schema package is designed to read clearly in any editor or IDE. Open my-northwind/ in VS Code, JetBrains Rider, Visual Studio, or whatever your team uses. The .json-schemas/ folder gives you validation and autocomplete for every JSON file in the package automatically.

Click through Tables/Categories.json. You'll see the column definitions, the primary key, and any indexes. Open a stored procedure in Procedures/ and you see the full SQL definition ready to diff in a pull request. This is what schema review looks like when the files are designed for it: structured enough for tools, readable enough for humans, diff-friendly enough for code review.

Take a minute to click around. Every table, every view, every procedure in the Northwind database is here, structured and browsable. No server connection needed to explore.

Quench with SchemaQuench

Here's where it gets powerful. You just extracted the live Northwind schema into my-northwind/. Now let's quench that package back at the same database to prove the round-trip — declared state in, target verified against it, exact-delta DDL out. Create a SchemaQuench configuration file called quench-deploy.json:

{
  "Target": {
    "Server": "localhost",
    "Port": "3317",
    "User": "TestUser",
    "Password": "your-password-here"
  },
  "WhatIfONLY": false,
  "SchemaPackagePath": "./my-northwind",
  "ScriptTokens": {
    "NorthwindDb": "northwind"
  }
}

Notice the ScriptTokens section: SchemaQuench resolves the {{NorthwindDb}} token in the package's scripts to northwind, the database we want to manage. Tokens parameterize a package so the same source files can deploy to dev, staging, and production by changing one value at deploy time — point a token at a different database name to spin up a clone for testing without touching another file. You'll learn more about tokens in Products and Templates, and the full token system is documented in Script Token Mechanics.

Run the deployment:

schemaquench --ConfigFile:quench-deploy.json

SchemaQuench reads the schema package, connects to the live northwind database, and compares your declared state to what's actually there. Since you just extracted this package from that exact database, the two are in sync — no DDL is emitted on this first run. That's the point: SchemaSmith only changes what's actually different. The diff comes alive in the next step.

One package. One command. A target verified against your declared source of truth. That's what quenching looks like.

Make a Change

Now for the real satisfaction. Let's modify the schema and watch SchemaSmith figure out exactly what needs to change.

Open my-northwind/Templates/Northwind/Tables/Shippers.json. The file declares the current state of the table: columns, indexes, the primary key. Add a new column for tracking email addresses. Insert this entry into the Columns array after the `Phone` column:

{
  "Name": "`Email`",
  "DataType": "varchar(100)",
  "Nullable": true,
  "OldName": ""
}

You just declared the desired state: "the Shippers table should have an Email column." You didn't write an ALTER TABLE script. You didn't check whether the column already exists. You described what the table should look like. You decide the shape. The forge handles the rest.

Now let's see what SchemaSmith will do — without changing your schema. Run SchemaQuench in WhatIf mode by setting "WhatIfONLY": true in a copy of your settings file:

{
  "Target": {
    "Server": "localhost",
    "Port": "3317",
    "User": "TestUser",
    "Password": "your-password-here"
  },
  "WhatIfONLY": true,
  "SchemaPackagePath": "./my-northwind",
  "ScriptTokens": {
    "NorthwindDb": "northwind"
  }
}

Save this as quench-whatif.json and run:

schemaquench --ConfigFile:quench-whatif.json

In the output, you'll see [WhatIf] entries showing the computed changes. SchemaQuench compared the declared state (your JSON with the new Email column) against the live northwind database (which has no Email column) and determined that an ALTER TABLE ... ADD COLUMN is needed. None of your objects were changed. WhatIf does install or update SchemaSmith's own helper schema on the target, the same one a real run uses, so it needs the same permissions. Preview before you commit. Confidence before you deploy.

Now apply it for real. Re-run the original quench-deploy.json from Step 4 — it already has "WhatIfONLY": false, so this run actually writes the change:

schemaquench --ConfigFile:quench-deploy.json

SchemaQuench connects to the northwind database, sees that Shippers is missing the Email column, and adds it. Every other table, view, and procedure is already in sync, so nothing else changes. Exactly the right delta, computed automatically. No more, no less.

Verify the Change

Connect to the database with whatever SQL client you prefer and look at the Shippers table:

SELECT `CompanyName`, `Phone`, `Email` FROM `Shippers` LIMIT 1;

The Email column is there, just as you declared it. The file is the truth, the database matches, and your next commit records the change for posterity.

The Cycle Is Complete

You just completed the full SchemaSmith workflow:

  1. Cast — SchemaTongs gripped a live database and cast it into structured, version-controlled files
  2. Review — The JSON and SQL files are human-readable and diff-friendly, ready for pull requests
  3. Quench — SchemaQuench built a complete database from those files, reproducibly
  4. Change — You edited a JSON file to declare a new column
  5. Preview — WhatIf mode showed you the computed change without applying it
  6. Apply — SchemaQuench made the target match the declared state, changing only what needed to change

No migration scripts. No ordered chains of ALTERs. No guessing what the target looks like. You declare the state you want, and SchemaSmith gets you there. Every time.

What's Next

What's Next

You just did state-based schema management. Now let's understand what's happening under the hood — products, templates, tokens, and the deployment pipeline that makes it all work. The same concepts carry across every supported engine.

Hands-on lab

Install the SchemaSmith CLI and connect to a MariaDB instance in this hands-on sandbox lesson.

Start the install lab

Shape. Strengthen. Succeed.

Free schema-as-code for SQL Server, PostgreSQL, MySQL, and MariaDB.

The source is on GitHub for anyone to read.

Get Started on GitHub