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.
| Command | Alias | License | Usage |
|---|---|---|---|
| new | -n | Free | dbm new [--platform | --generated | --application] <description> |
| build | -b | Paid | dbm build <target> |
| deploy | Paid | dbm deploy <target> | |
| compare | -c | Free | dbm compare <source> <target> |
| setsource | -ss | Free | dbm setsource <target> |
| schemadoc | -sdoc | Free | dbm schemadoc <target> |
| dumpdata | -dd | Free | dbm dumpdata <target> [table ...] |
| settingdump | -sd | Free | dbm settingdump <target> |
| settingdeploy | -sdp | Free | dbm settingdeploy <target> |
| backup | -bk | Free | dbm backup <target> |
| clean | -x | Free | dbm clean |
| shift | Paid | Not 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>
| Flag | Folder |
|---|---|
(none) or --application | MigrationPath/Application/ |
--platform | MigrationPath/Platform/ |
--generated | MigrationPath/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 theVariablessection before the script runs. An undefined variable fails the deployment.- A script may contain several batches separated by a
GOline. - 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:
| File | Content |
|---|---|
table-<Name>.txt | One line per column: name, type, computed, length, precision, scale, nullable, collation |
tablesql-<Name>.txt | The table's CREATE TABLE script |
view-<Name>.txt | View definition |
trigger-<Name>.txt | Trigger definition |
sp-<Name>.txt | Stored 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:
| Field | Type | Null | Length | Ref / Rule |
|---|---|---|---|---|
| Title | nvarchar(200) | No | 200 chars | |
| OrderId | int | No | Order.Id | |
| Ukey | varchar(50) | No | 50 bytes | varchar(32); NN |
- Ref / Rule shows the foreign key a column references and, when
StandardColumnsis 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 bySkip.Tables/Skip.TableRegexPatternsare 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
IgnoreColumnscolumns 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(defaultName) 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.
| Column | Behaviour |
|---|---|
Id | Never inserted or updated; the target assigns its own |
CreatedAt, CreatedBy | Set on insert, preserved on update |
UpdatedAt, UpdatedBy | Always stamped, using SettingMigration.UpdatedBy |
| Everything else | Updated 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.