The full SchemaTongs reference for MariaDB extractions — configuration, ShouldCast flags, orphan detection, script validation, and custom-property preservation across re-extraction.
By the SchemaSmith Team · Last reviewed
Cast your live database into version-controlled code with a single command.
SchemaTongs grips every object in your database and extracts them into a clean schema package: tables as JSON, programmable objects as SQL scripts, everything organized and ready to commit to source control. Point it at a database, run it, and you have a deployable package that SchemaQuench can quench onto any compatible target.
The same tool, the same package format, every supported engine. Whatever your team runs, SchemaTongs casts it.
Downloads — Get the latest release from the downloads page.
From the directory containing your SchemaTongs.settings.json:
schematongs
With a custom config file:
schematongs --ConfigFile:/etc/schemasmith/extract-staging.json
With a full MariaDB connection string override:
schematongs --ConnectionString:"Server=db1;Database=northwind;User=tongs"
SchemaTongs connects to the source database, reads every enabled object type, and writes the results to the configured product path. On first run it creates the full package structure; on subsequent runs it updates existing files in place and preserves any custom metadata you have attached under Extensions.
If you just need to regenerate the .json-schemas/*.schema validation files for an existing product — without connecting to a database — use the --WriteSchemasOnly switch. The product path comes from your SchemaTongs.settings.json (or an environment variable override), not from the command line:
Run from the directory that contains SchemaTongs.settings.json with Product:Path already set:
schematongs --WriteSchemasOnly
Or set the path inline via environment variable (note the double underscore for the nested key):
$env:SmithySettings_Product__Path = "./my-product"
SchemaTongs --WriteSchemasOnly
SmithySettings_Product__Path=./my-product schematongs --WriteSchemasOnly
This reads the Platform from Product.json, regenerates the schema files on the fly from the current engine's C# domain types, and exits. No database connection, no extraction. Useful when you've updated SchemaSmith and want CI validation to match the new engine without re-extracting.
Before extraction begins, SchemaTongs detects the source server's version, records it in the run log, and checks it against the minimum supported floor. The version line is written on every run:
Source MariaDb version 11.4.12-MariaDB-ubu2404
The floor is intrinsic — you do not declare it, configure it, or disable it. It is the version below which SchemaSmith's engine scripts do not run at all: MariaDB 10.2.13. A below-floor source aborts before any schema retrieval starts, rather than failing partway through:
srv01: detected MariaDb version 10.1.48-MariaDB is below the minimum
supported version 10.2.13. SchemaSmith cannot run against it.
Without the pre-flight, a below-floor source dies deep inside extraction with a raw engine error, which obscures the real cause and reads like a SchemaSmith defect rather than an unsupported server.
This is separate from Product.MinimumVersion. The intrinsic floor is always enforced and cannot be lowered; MinimumVersion is an optional per-product gate that raises the floor further, and it applies at deployment time in SchemaQuench. See SchemaQuench — Engine version compatibility.
A package carries what the source server reports, so a package extracted from a newer server can name things an older one does not have. The common case is the collation: from 11.4 (and in Debian and Ubuntu packages from 11.3.2) a table or column that takes the default is reported with utf8mb4_uca1400_ai_ci, which MariaDB before 10.10 does not know, and the deploy there fails with 1273 Unknown collation. Replace it in the package with a collation the older server has, such as utf8mb4_unicode_ci, before deploying it there. A declared sequence with a DataType other than bigint deploys below 11.5 as a bigint, with a downgrade recorded; a CREATE SEQUENCE ... AS in one of your own scripts fails there.
SchemaTongs reads configuration from multiple sources, merged in precedence order (highest priority last):
SchemaTongs.settings.json in the working directory (or the file specified by --ConfigFile)SmithySettings_ prefixFor the full explanation of configuration loading, environment variable mapping, and CLI switches, see Configuration.
{
"Source": {
"Server": "",
"Port": "",
"User": "",
"Password": "",
"Database": "",
"Platform": "MariaDb",
"ConnectionProperties": {}
},
"Product": {
"Path": "",
"Name": "",
"CheckConstraintStyle": "ColumnLevel",
"ObjectOrder": "Physical",
"PreserveExistingOrder": true
},
"Template": {
"Name": ""
},
"ShouldCast": {
"Tables": true,
"Views": true,
"Functions": true,
"Procedures": true,
"TableTriggers": true,
"ObjectList": "",
"ValidateScripts": false,
"SaveInvalidScripts": true,
"Events": true,
"Packages": true,
"Sequences": true
},
"OrphanHandling": {
"Mode": "Detect"
},
"FolderMapping": {
"Functions": "Functions",
"Views": "Views",
"Procedures": "Procedures",
"Triggers": "Triggers"
}
}
Every ShouldCast object flag defaults to true when it is left out; ValidateScripts defaults to false.
| Key | Type | Default | Description |
|---|---|---|---|
Source:Platform | string | (required, or its Target:Platform twin) | Set to MariaDb to select the MariaDB extraction adapter. |
Source:Server | string | (required, or its Target:Server twin) | Database server hostname or IP. |
Source:Port | string | 3306 | TCP port. |
Source:User | string | (empty) | Login username. |
Source:Password | string | (empty) | Login password. |
Source:Database | string | (required) | Name of the database to extract from. (MariaDB treats databases and schemas as the same concept.) |
Source:ConnectionProperties | object | {} | Arbitrary key-value pairs appended to the connection string. Platform-specific keys — see Configuration. |
Each connection key falls back to its Target: twin when the Source: key is absent — Platform, Server, Port, User, Password, and ConnectionProperties — so one settings file can point SchemaQuench and SchemaTongs at the same server.
The --ConnectionString switch bypasses all Source settings entirely. When provided, Server, Port, User, Password, Database, and ConnectionProperties are all ignored. Source:Platform (or its Target:Platform twin) is still required so the right adapter can claim the connection.
| Key | Type | Default | Description |
|---|---|---|---|
Product:Path | string | (required) | Directory where the schema package is created or updated. |
Product:Name | string | (directory name) | Product name written to Product.json. If blank, defaults to the last segment of Product:Path. |
Product:CheckConstraintStyle | string | ColumnLevel | No effect on MariaDB: a column-level check, the one MariaDB names after its column, extracts as that column's CheckExpression, and every other check table-level, whatever this says. See CheckConstraintStyle. |
Product:ObjectOrder | string | Physical | Sequence used for a table's column list when there is nothing to preserve. Physical uses the table's own column order; Name sorts alphabetically. Every other list is always name-ordered. See Column and object order. |
Product:PreserveExistingOrder | bool | true | When a table file already exists, keep the order it already had. See Column and object order. |
Template:Name | string | Source database name | Template name. Creates the template directory under Templates/<Name>/. Defaults to the Source:Database value when not specified. |
Control exactly what gets cast from the database. Each object type can be individually enabled or disabled.
| Flag | Default | What it extracts |
|---|---|---|
Tables | true | Table definitions as JSON files |
Views | true | View definitions as SQL scripts |
Functions | true | User-defined functions |
Procedures | true | Stored procedures |
TableTriggers | true | Table-level triggers |
Events | true | MariaDB scheduled events |
Packages | true | MariaDB packages (10.3 and later) and their bodies, to Packages/ |
Sequences | true | MariaDB sequences (10.3 and later), as declared JSON in Sequences/ |
ObjectList | (empty) | Comma- or semicolon-separated list of specific objects to extract. See ObjectList Filtering. |
ValidateScripts | false | Parses each extracted SQL script for validity. See Script Validation. |
SaveInvalidScripts | true | When ValidateScripts is enabled, saves failing scripts as .sqlerror files. |
MariaDB doesn't distinguish schemas from databases, so there is no Schemas flag — the database itself is the schema.
Views, functions, procedures and triggers are written from the engine's own DDL (SHOW CREATE), so everything the server knows about the object comes with it: parameter modes and character sets, parameter defaults, AGGREGATE and RETURNS ROW functions, multi-event and UPDATE OF triggers, COMMENT, SQL SECURITY, and a view's ALGORITHM and CHECK OPTION. The DEFINER clause is removed, so a deployed object's definer is the account that deploys it. Two things are added to what the server returns:
sql_mode around its CREATE and restores the session's mode afterwards. The server renders the text in that mode (double-quoted identifiers under ANSI_QUOTES, Oracle syntax under ORACLE) and runs the body under it, so the deployed object keeps it whatever mode the target server runs.FOLLOWS is rebuilt from the catalog's ACTION_ORDER. SHOW CREATE TRIGGER returns the statement as it was written, which never carries the order. A follower whose file sorts before its predecessor fails on the deploy's first pass and is created on the retry pass.A package and its body are one file in Packages/: DROP PACKAGE IF EXISTS, then each half under the sql_mode it was created in (ORACLE, or from 11.4 any mode), so a redeploy replaces both. A package with no body is written without one. A sequence is written as declared JSON in Sequences/, its options read from SHOW CREATE SEQUENCE and its current value never, so the deploy converges each attribute in place and never resets it. A column default of nextval(`db`.`s`) is written with the bare sequence name, so the package deploys to any database.
A view is written as CREATE OR REPLACE VIEW, so a view that fails to deploy leaves the previous view in place. A reference to a table in the same database is written unqualified, and a reference to another database keeps its qualifier, so the package deploys to a database of any name.
The account needs SELECT on the database, SHOW VIEW for views, TRIGGER for triggers, EVENT for events, and, for the body of a routine it did not create, global SELECT or SELECT on mysql.proc. An object whose definition the server will not return is logged as skipped and counted in the run's skipped objects; without the TRIGGER privilege the catalog lists no triggers at all, and SchemaTongs says so once.
By default, each extracted object type lands in the standard folder for the active platform (see Schema Packages — Folder Structure). The optional FolderMapping section lets you rename those default folders without breaking SchemaQuench's recognition of them.
{
"FolderMapping": {
"Functions": "01_Functions",
"Views": "02_Views",
"Procedures": "03_Procedures",
"Triggers": "04_Triggers",
"Events": "05_Events"
}
}
The keys are ScriptObjectType values (e.g., Functions, Views, Procedures, Triggers, Events). The values are the folder names you want to use under each template directory.
A few rules:
Tables/.FolderMapping keeps its standard folder name.This pairs naturally with the ScriptFolders array on Template.json. You can extract using your renamed folder layout and SchemaQuench will still pick up the right slot for each folder.
The ObjectList setting restricts extraction to a specific set of objects. Provide a comma- or semicolon-separated list of object names:
{
"ShouldCast": {
"ObjectList": "Customers,vw_ActiveCustomers,usp_GetOrders"
}
}
Matching is case-insensitive. When ObjectList is empty (the default), all objects matching the enabled ShouldCast flags are extracted.
When ObjectList is active, orphan detection is automatically disabled — SchemaTongs can't tell which files are genuinely orphaned when only a subset of objects is being extracted.
Databases change. Objects get dropped or renamed. The old script files linger in your package — unless you tell SchemaTongs what to do about them. Configure orphan behavior with OrphanHandling:Mode:
| Mode | Behavior |
|---|---|
Detect | Orphaned files are logged as warnings. No files are modified or deleted. Default. |
DetectWithCleanupScripts | Orphaned files are logged. For each orphan in a script folder, a cleanup script containing a DROP statement is generated as _OrphanCleanup_<FolderName>.sql in the log directory. The orphaned files themselves are left in place. |
DetectDeleteAndCleanup | Orphaned files are deleted from the package. Cleanup DROP scripts are generated in the log directory. |
Detect — Safe default. Use during routine re-extraction when you want to review orphans manually before taking action.DetectWithCleanupScripts — Use when you want SchemaTongs to prepare the cleanup work but you want to review the generated scripts and delete orphaned files yourself.DetectDeleteAndCleanup — Use when you trust the extraction to be authoritative and want a fully clean package after each run. Particularly useful in automated pipelines.SchemaTongs builds a file index for each extraction folder before extraction begins. As objects are extracted and written to disk, each file is marked as "written." After extraction completes, any indexed file that wasn't written is an orphan. Cleanup scripts from previous runs are archived into numbered SchemaTongs.NNNN backup directories before new ones are generated.
Orphan detection only runs for object types that were fully extracted (ShouldCast flag enabled and no ObjectList filter active).
Two kinds of file are never orphans, because extraction was never going to write them:
SchemaSmith_<name>. Extraction does not read that namespace (see Excluded objects), but your own objects can live there: the recycle-bin hooks do.ShouldApplyExpression whose table is absent from this source. The gate kept it off this database; it was not removed.An "orphan" might be a script for an object that was genuinely removed from the database, OR it might be a new object you added to the package that has not been deployed yet. Deleting it automatically would destroy your pending work. The default (Detect) is conservative because it never destroys anything — it just tells you.
Custom metadata you've attached to your tables under Extensions is preserved across re-extractions. When SchemaTongs writes a table file, it checks whether a previous file existed for the same table and copies the previous Extensions content forward onto the freshly extracted table.
The preservation pass uses the component's Name (with quote/bracket characters stripped, case-insensitive). For columns and the table itself, matching also falls back to OldName, so renamed components keep their custom metadata as long as you set OldName correctly before the rename is deployed.
| Component | Matched by |
|---|---|
| Table | root object |
| Column | Name, then OldName |
| Index | Name |
| ForeignKey | Name |
| CheckConstraint | Name |
| FullTextIndex | Name |
This is what makes Custom Properties trustworthy across the SchemaTongs / SchemaQuench round-trip: you attach metadata once, and it survives every re-extraction as long as the underlying object stays.
SchemaTongs writes each table file under a canonical name derived from the table's content:
<table>[.<VariantName>].json
The optional VariantName segment comes after the table name, so a table's conditional variants sort together in source control and in a file listing. MariaDB packages carry no per-table schema, so the canonical name has no schema segment.
A table's identity lives in its file content — Name and VariantName — not in its filename. SchemaTongs matches an existing file to an extracted table by that content identity, so a file you renamed by hand is still found and refreshed in place rather than duplicated. The canonical name is a convention, not a contract: if a file's name drifts from canonical, the deploy still works and --Validate emits an SS-FILE-NAME-003 warning pointing at the canonical name.
When a table — or one of its components (column, index, foreign key, constraint, full-text index) — carries an authored variant set (two or more same-named entries each gated by ShouldApplyExpression), SchemaTongs can only ever see one physical shape on the source database. Rather than discard what it extracted, it evaluates each variant's gate against the source and folds the extracted shape into the variant that is active there, keeping that variant's gate and VariantName and leaving the inactive variants untouched. Real drift on the deployed variant is captured, not lost.
If no single variant's gate is active on the source, the extracted shape is written as an ungated entry alongside the authored variants; --Validate then flags the ungated-plus-gated mix (SS-DUP-001) so you can fold it into the right variant or gate it. A malformed or erroring gate fails the extraction rather than guessing (fail-closed).
Catch problems at extraction time instead of discovering them during deployment. When ShouldCast:ValidateScripts is true, SchemaTongs tests each extracted SQL script for validity immediately after writing it, and flags the ones that fail.
On MariaDB there is no rollback for DDL, so a view, function or procedure is validated by creating it under a temporary name (_validate_ followed by twelve hex characters) on the source database and dropping it straight after, under the object's own sql_mode. Triggers are not validated: CREATE TRIGGER cannot be parsed without being created, and a temporary trigger would be live on the source table while it was checked. Events, packages and other object types are not validated either.
Scripts that fail validation are handled according to ShouldCast:SaveInvalidScripts:
| SaveInvalidScripts | Behavior |
|---|---|
true (default) | The script is saved with a .sqlerror extension instead of .sql. The original .sql file (if any) is removed. |
false | The script isn't written to disk at all. |
.sqlerror files are SQL scripts that failed extraction validation. They serve as a record of potential problems without blocking the rest of the package.
| Tool | Behavior |
|---|---|
| SchemaQuench | Skips .sqlerror files — only .sql files are loaded and executed. |
| SchemaTongs | On re-extraction, overwrites .sqlerror files with the latest content. If the script still fails validation, it stays as .sqlerror. If it now passes, it's written as .sql and the .sqlerror is removed. |
Validation failures aren't always genuine errors. Common false positives include:
To override a false positive, rename the file from .sqlerror to .sql. SchemaQuench will then include it in the next deployment.
When any scripts fail validation, SchemaTongs generates an _InvalidObjectCleanup.sql file in the log directory containing diagnostic information for all invalid objects detected during the extraction run.
Extraction carries on past an object it cannot write, and the exit code tells a pipeline whether the package is complete:
| Code | Meaning |
|---|---|
0 | Every object was extracted. |
1 | Finished, but the package is missing something: a script failed validation (saved as .sqlerror or removed), an existing .sqlerror was skipped with validation off, or an object's definition came back empty. The summary counts them under Skipped and Invalid. |
2 | At least one table failed to extract. |
The full table of codes, for every tool, is in Logging — Exit codes.
Organize your scripts however makes sense for your team — SchemaTongs respects that structure across re-extractions. Any extracted script folder supports user-created subfolders for organizing scripts. For example, you might organize stored procedures by domain:
Procedures/
Orders/
usp_GetOrder.sql
usp_CreateOrder.sql
Customers/
usp_GetCustomer.sql
SchemaTongs preserves these subfolders across re-extraction. Before extraction begins, it builds a file index that maps every .sql, .sqlerror, and .json file to its full path, including any subfolder. When writing an extracted object, SchemaTongs checks the index:
New objects always appear in the root of their folder. Move them into subfolders as desired — SchemaTongs will remember the location on the next run. This means you can shape your extracted package to fit your code review and team conventions, not the other way around.
The first extraction is where your schema package is born. When SchemaTongs runs against a path that doesn't yet contain a schema package, it creates the full structure:
Product:Path.Product.json with the configured product name and the Platform from Source:Platform.Templates/<TemplateName>/.Template.json with a DatabaseIdentificationScript targeting the source database..json-schemas/ directory with JSON Schema validation files generated on the fly from the live engine types.$schema reference into each package JSON, pointing at the matching file from step 6, so editors validate the package with no per-user configuration.On subsequent runs against an existing package, SchemaTongs overwrites object scripts and table definitions with the current database state. It does not modify the content of Product.json or Template.json — if you change Platform, Name, or TemplateOrder after the first extraction, or add keys of your own, those edits stick. Extracting a template the product does not list yet adds it to TemplateOrder and adds its <Template>Db script token, and nothing else. The one exception is the $schema reference from step 7: it is added if absent and otherwise left alone, which means a reference you deleted on purpose is written again on the next run — there is no record distinguishing it from one that was never there.
SchemaTongs maintains lightweight helper procedures in the source database, prefixed SchemaSmith_ — installing them where writes are allowed, and verifying them where they are not (see Extracting from a read-only replica). These procedures generate the JSON representation of tables and views and are used internally by the extraction adapter. They're read-only, name-prefixed, and excluded from extraction output.
SchemaTongs installs a small set of helper procedures into the database it reads from, and refreshes them whenever they are out of date. That needs write access — which the copy you most want to extract from often will not give you. On MariaDB that is a replica: read-only by design, and precisely the copy you are allowed to query hard without upsetting anyone.
Against a read-only target SchemaTongs verifies the helpers instead of installing them, then extracts as normal. Four outcomes:
| What it finds | What happens |
|---|---|
| Helpers present and matching this build | Extraction proceeds; nothing to report. |
| Helpers present but older than this build | Warning, then extraction proceeds. |
| Helpers present, version not determinable | Warning saying the install was skipped and they might be out of date, then extraction proceeds. |
| Helpers absent | Error. Nothing is extracted. |
If extraction stops because the helpers are absent, run SchemaSmith once against the primary — any deploy, or any extraction against a writable copy, installs them — and let the change reach the replica. SchemaSmith does not attempt the install itself, because a read-only target rejects every write it needs.
A stale-helpers warning is not fatal on purpose. Refusing would make a replica useless the moment the primary is one version ahead of your CLI, which is most of the time. The warning exists because an extraction taken with older helpers can be quietly incomplete — it may not know about properties this build understands — so treat it as a reason to check the result against the primary if anything looks wrong, not as a reason to stop.
Deployment is unaffected: SchemaQuench still requires a writable target, because applying a schema genuinely cannot work without one. Use SkipIfReadOnly on a template if you want a deploy to pass over a read-only target rather than fail against it.
Two settings decide the sequence of the lists inside an extracted table file — Columns, Indexes, ForeignKeys and CheckConstraints. They answer different questions and compose without conflict.
This defaults to true. When SchemaTongs overwrites a table file that already exists, every entry still present keeps the position that file gave it. Entries the database no longer has drop out. Entries that are genuinely new are appended using ObjectOrder. The point is that re-extracting should produce a diff of what actually changed — without it, a one-column change arrives buried in a whole-file reshuffle, and a package whose ordering was arranged by hand loses that arrangement every time it is refreshed.
It preserves the order in the file. It does not make a deployed table's physical column order match the package — reordering the columns of an existing table is a change to the table, not a formatting preference, and is a separate opt-in (RebuildPolicy OnOrderMismatch), carried out by a table rebuild or, under OnlineApply Prefer or Require, by moving the columns in place. If you have never re-extracted over an existing file, this setting has no effect on anything.
Set it to false to have every extraction re-sequence the whole file from scratch using ObjectOrder.
This defaults to Physical, which writes the columns in the table's own order. It is the default because SchemaQuench creates a new table with its columns in file order: a table deployed fresh from the package then has the same column order as the table it came from, so code that relies on position — an INSERT without a column list, a SELECT * read by ordinal — behaves the same against both.
Name sorts the columns alphabetically instead. It is stable: the same table extracts identically whichever server it came from, and it does not shift when a source table's column order changes. Two points worth knowing: the setting applies to the column list only — indexes, foreign keys and check constraints have no ordinal that anyone authors toward, so those stay alphabetical either way — and the physical order is a property of that database, so the same logical table on another server can order its columns differently and a package extracted with Physical is not guaranteed to match elsewhere.
Because PreserveExistingOrder defaults to true, ObjectOrder decides a first extraction and any newly-added entries after that. Once a file exists, its order is what survives.
On MariaDB, Product:CheckConstraintStyle has no effect. A column-level check — the one MariaDB names after its column — extracts as that column's CheckExpression, and every other check extracts table-level, as a named entry in the table's CheckConstraints array:
{
"CheckConstraints": [
{
"Name": "`CK_Orders_Status`",
"Expression": "`Status` IN ('Active','Inactive','Pending')"
}
]
}
A column-level check rides the column definition: CREATE, ADD and MODIFY COLUMN carry it, a MODIFY without it removes it, and it is never dropped as an undeclared table-level check. --Validate stops a CheckConstraints entry named like a column (SS-CHK-002), which MariaDB itself refuses from 10.11.19, 11.4.13 and 13.0.2.
SchemaTongs leaves out:
mysql, information_schema, performance_schema and sys are outside its scope: SchemaTongs extracts only the database named in Source:Database.SchemaSmith_* (the helper procedures SchemaTongs and SchemaQuench deploy). Files you keep under that prefix, such as the recycle-bin hooks, are left alone by Orphan detection.Free schema-as-code for SQL Server, PostgreSQL, MySQL, and MariaDB.
The source is on GitHub for anyone to read.
Get Started on GitHub