Skip to main content

Execution Commands

Execution commands create scripts, deploy them, compare and document schemas, and move data and settings. <target> is always the Key of a database listed under Databases in dubnium.yml.

CommandAliasLicenseUsage
new-nFreedbm new [--platform | --generated | --application] <description>
build-bPaiddbm build <target>
deployPaiddbm deploy <target>
compare-cFreedbm compare <source> <target>
setsource-ssFreedbm setsource <target>
schemadoc-sdocFreedbm schemadoc <target>
dumpdata-ddFreedbm dumpdata <target> [table ...]
settingdump-sdFreedbm settingdump <target>
settingdeploy-sdpFreedbm settingdeploy <target>
backup-bkFreedbm backup <target>
clean-xFreedbm clean
shiftPaidNot yet available

new​

Create an empty, correctly numbered migration script.

Alias: -n
License: Free

dbm new <description words>
dbm new --platform <description words>
dbm new --generated <description words>
FlagFolder
(none) or --applicationMigrationPath/Application/
--platformMigrationPath/Platform/
--generatedMigrationPath/Generated/

Each script type has its own number sequence: the new script gets the highest version in its folder plus one, starting at 100000. The description words are joined with _, so the file name is <version> - <Description_Words>.sql. The description must be 10 to 90 characters of letters, digits, spaces, -, or _.

dbm new Add Users Table
# -> Migration/Application/100000 - Add_Users_Table.sql

dbm new --platform Create Core Schema
# -> Migration/Platform/100000 - Create_Core_Schema.sql

With OpenNewScriptFile: true, Dubnium opens the new file in its default editor; otherwise it prints the full path.


build​

Same as deploy.

Alias: -b
License: Paid

dbm build <target>

deploy​

Run every migration script the target has not run yet.

License: Paid

dbm deploy <target>
dbm deploy test

Order: all Platform scripts run first, then Generated, then Application. Within each folder, scripts run in ascending version order. Scripts left directly in MigrationPath (the older layout) count as Application scripts.

Version tracking: each script type has its own watermark in dbo.__DubniumInfo. A script runs only when its version is higher than the highest version already recorded for its type, and each successful script is recorded straight away. To run every script of a type again on each deployment, list that type under RerunScriptTypes. Only do this for scripts written to be re-runnable.

Script processing:

  • {{NAME}} variables are replaced from the Variables section before the script runs. An undefined variable fails the deployment.
  • A script may contain several batches separated by a GO line.
  • A failing script stops the deployment and reports the file and SQL error. Scripts that already succeeded stay recorded.
  • Before running, every script name is validated and duplicate version numbers within a folder fail the deployment.

Deploy never promotes settings. Rows captured by settingdump are applied only by settingdeploy, so a routine deployment cannot carry development settings into another environment.

With DryRun: true, the SQL that would run is printed and nothing is executed or recorded.


compare​

Compare the schemas of two database targets.

Alias: -c
License: Free

dbm compare <source> <target>
dbm compare local test

Dubnium dumps both schemas (tables, table SQL, views, triggers, and stored procedures, respecting Skip) into a new session folder under TempPath, then reports:

  • objects that exist in only one database
  • lines (such as column definitions) that differ between the two

An HTML side-by-side report is written to TempPath\schema-diff.html. When no differences are found, output.txt containing All good is written to the session folder. Remove old session folders with dbm clean.


setsource​

Dump a target's schema into SchemaPath as the reference copy kept in source control.

Alias: -ss
License: Free

dbm setsource <target>

setsource deletes every file in SchemaPath first, then writes one text file per object:

FileContent
table-<Name>.txtOne line per column: name, type, computed, length, precision, scale, nullable, collation
tablesql-<Name>.txtThe table's CREATE TABLE script
view-<Name>.txtView definition
trigger-<Name>.txtTrigger definition
sp-<Name>.txtStored procedure definition

Dubnium's own __ tables and anything excluded by Skip are left out. Committing this folder makes every schema change visible as a diff. Keep nothing else in SchemaPath.


schemadoc​

Generate schema documentation as Markdown and PDF.

Alias: -sdoc
License: Free

dbm schemadoc <target>
dbm schemadoc local

Reads every dbo table of the target without changing the database and writes one numbered section per table. Each section lists the table's columns:

FieldTypeNullLengthRef / Rule
Titlenvarchar(200)No200 chars
OrderIdintNoOrder.Id
Ukeyvarchar(50)No50 bytesvarchar(32); NN
  • Ref / Rule shows the foreign key a column references and, when StandardColumns is configured, the standard a column breaks.
  • Standard columns that meet their standard are left out, so each table shows only what is specific to it. A missing standard column is listed as Missing.
  • The Markdown file is deterministic, so schema changes show up as diffs in source control. The PDF is a compact two-column A4 layout for printing, with page numbers and a printed date.
  • Dubnium's own __ tables, sysdiagrams, and tables excluded by Skip.Tables / Skip.TableRegexPatterns are left out.

Output paths and column standards come from the SchemaDocumentation section. Keep the output outside SchemaPath, which setsource clears. With DryRun: true, nothing is written.

PDF output needs Windows, because it uses the installed Windows fonts.


dumpdata​

Export table data to CSV files.

Alias: -dd
License: Free

dbm dumpdata <target>                     # tables from configuration
dbm dumpdata <target> Users Products # these tables only

When no tables are named, Dubnium dumps DataMigration.Tables, or TablesToDump if that list is empty. Each table is written to DataMigration.Folder\<Table>.csv with a header row. Empty tables produce no file, and a table that fails to dump is reported without stopping the others.


settingdump​

Write table settings as one file per row.

Alias: -sd
License: Free

dbm settingdump <target>

Writes every row of each table in SettingMigration.Tables to its own file under SettingMigration.Folder\<Table>\. A file holds one row as Column=Value lines, so a settings change shows up as a readable line-by-line diff.

Database/Setting/BaseModule/Account.setting
# Table: BaseModule
# Match: UKey
UKey=e83ca7901670474da714ad308cd2265e
Name=Account
DisplayName=Account
ShowInManage=False
SortOn=1
  • Identity, computed, and IgnoreColumns columns are left out, so re-dumping unchanged settings produces identical files.
  • Stale files in the table folder are removed first, so a row deleted in development disappears from the dump.
  • File names come from FileNameColumn (default Name) alone, so a row always writes to the same path.

Because the file name is a natural key, two rows sharing a value would overwrite each other. The dump then fails and writes nothing, listing every clash:

ERROR: Table dbo.BaseModule has 2 duplicate Name value(s).
Setting files are named from Name alone, so these rows would overwrite each other:
Account.setting <- UKey=7fd8622351b6481cb268393862eaf5b4, UKey=e8c091b65d48409298f3ef710779d3bb
Resolve the duplicate rows, then run the dump again.

Add a unique index on the name column so this cannot happen.


settingdeploy​

Apply dumped settings to a target.

Alias: -sdp
License: Free

dbm settingdeploy <target>
dbm settingdeploy test

This is deliberately separate from deploy, so settings being tried out in development are never promoted as a side effect of a script deployment. It prints the target, folder, tables, and mode before it starts. To preview without writing, set DryRun: true.

Rows are matched on MatchColumn (default Ukey, overridable per table with TableMatchColumns), never on the identity Id, because identities differ between environments. Each table is applied in one transaction and rolls back completely if any row fails. With FailFast: true (the default), the first failing table stops the deployment.

ColumnBehaviour
IdNever inserted or updated; the target assigns its own
CreatedAt, CreatedBySet on insert, preserved on update
UpdatedAt, UpdatedByAlways stamped, using SettingMigration.UpdatedBy
Everything elseUpdated from the setting file

settingdeploy never deletes: rows in the target that are missing from the dump are left alone. Whole-table CSV files placed directly in the setting folder root are imported the same way, matched on DataMigration.DefaultMatchColumn (or DataMigration.TableMatchColumns).


backup​

Back up a target database.

Alias: -bk
License: Free

dbm backup <target>

Runs BACKUP DATABASE ... WITH INIT to <parent of MigrationPath>\Backup\<Database>_<yyyyMMdd_HHmmss>.back. SQL Server writes the file itself, so that folder must be reachable and writable from the SQL Server machine.


clean​

Delete temporary comparison sessions.

Alias: -x
License: Free

dbm clean

Deletes the session folders that compare creates under TempPath (folders named yyyy-MM-ddTHHmmss). Other files in TempPath are left alone.


shift​

Reserved for reorganising migration scripts.

License: Paid

This command is not implemented yet.