Examples
Common Dubnium workflows with the dbm command.
New Project
mkdir MyAppDatabase
cd MyAppDatabase
dbm init
Edit dubnium.yml: set ProjectName, then point the local target at your database:
Databases:
- Key: 'local'
Name: 'Local'
Connection:
Source: EnvironmentVariable
Value: 'DUBNIUM_LOCAL_CONNECTION_STRING'
# PowerShell
$env:DUBNIUM_LOCAL_CONNECTION_STRING = 'Integrated Security=SSPI;Initial Catalog=MyAppDev;Data Source=(local);Encrypt=True'
dbm setup local
Writing Migration Scripts
dbm new Create Users Table
# -> Migration/Application/100000 - Create_Users_Table.sql
dbm new --platform Create Core Schema
# -> Migration/Platform/100000 - Create_Core_Schema.sql
dbm new --generated Refresh Generated Module
# -> Migration/Generated/100000 - Refresh_Generated_Module.sql
Scripts run again whenever a database's watermark for their folder is below their version, so write them to be safe to re-run:
IF NOT EXISTS (
SELECT 1 FROM INFORMATION_SCHEMA.TABLES
WHERE TABLE_SCHEMA = '{{SCHEMA_NAME}}' AND TABLE_NAME = 'Users'
)
BEGIN
CREATE TABLE [{{SCHEMA_NAME}}].[Users] (
[Id] INT IDENTITY(1,1) NOT NULL,
[Ukey] VARCHAR(32) NOT NULL,
[Email] NVARCHAR(254) NOT NULL,
[IsActive] BIT NOT NULL CONSTRAINT [DF_Users_IsActive] DEFAULT 1,
[CreatedAt] DATETIME NOT NULL CONSTRAINT [DF_Users_CreatedAt] DEFAULT GETUTCDATE(),
CONSTRAINT [PK_Users] PRIMARY KEY CLUSTERED ([Id] ASC)
);
END
Variables:
SCHEMA_NAME: 'dbo'
Deploying
dbm verify
dbm deploy local
dbm deploy test
All Platform scripts run first, then Generated, then Application, each in version order. To preview, set DryRun: true and run the same command.
Comparing Environments
dbm compare local test
Differences are printed and written as an HTML report to TempPath\schema-diff.html. Remove old comparison sessions with dbm clean.
Tracking the Schema in Source Control
dbm setsource local # refresh the reference dump in SchemaPath
dbm schemadoc local # refresh DatabaseSchema.md and DatabaseSchema.pdf
Commit both. The SchemaPath dump and the schema Markdown make every schema change reviewable as a diff. Keep the schemadoc output outside SchemaPath, because setsource clears that folder.
Promoting Settings
SettingMigration:
Folder: 'Setting'
Tables:
- 'BaseModule'
TableMatchColumns:
BaseModule: 'Name'
dbm settingdump local # write one file per row, then review and commit
To promote to another environment, preview first, then apply:
DryRun: true # preview
dbm settingdeploy test
Set DryRun: false and run dbm settingdeploy test again to apply. deploy never applies settings.
Exporting Data
dbm dumpdata local # DataMigration.Tables
dbm dumpdata local Users Products # these tables only
DataDump/Users.csv
DataDump/Products.csv
Backing Up
dbm backup test
Writes <Database>_<yyyyMMdd_HHmmss>.back to a Backup folder beside MigrationPath. The SQL Server must be able to write to that folder.
Keeping the Configuration Elsewhere
Keep the real configuration in a secured folder and leave a placeholder where dbm runs:
MyApp/
|-- Config/
| `-- dubnium.yml # real configuration (kept encrypted in source control)
`-- Tools/
`-- dubnium.yml # ConfigPath: '..\Config\dubnium.yml'
cd Tools
dbm deploy local # reads ..\Config\dubnium.yml
Relative paths in Config/dubnium.yml resolve from Config.
CI/CD
name: Database CI
on:
push:
branches: [ main ]
jobs:
database:
runs-on: windows-latest
env:
MYAPP_TEST_CONNECTION_STRING: ${{ secrets.MYAPP_TEST_CONNECTION_STRING }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-dotnet@v4
with:
dotnet-version: '10.x'
- name: Install Dubnium CLI
run: dotnet tool install --global dubnium-cli
- name: Verify
run: dbm verify
working-directory: ./database
- name: Deploy scripts
run: dbm deploy test
working-directory: ./database
- name: Deploy settings
run: dbm settingdeploy test
working-directory: ./database
Here the test target uses Source: EnvironmentVariable with Value: 'MYAPP_TEST_CONNECTION_STRING', so the connection string comes from a CI secret.
Project Layout
MyAppDatabase/
|-- dubnium.yml
|-- Migration/
| |-- Platform/
| | `-- 100000 - Create_Core_Schema.sql
| |-- Generated/
| | `-- 100000 - Refresh_Generated_Module.sql
| `-- Application/
| |-- 100000 - Create_Users_Table.sql
| `-- 100001 - Add_Email_Column.sql
|-- Schema/ # dbm setsource output; nothing else here
|-- Documentation/ # dbm schemadoc output
|-- Setting/ # dbm settingdump output
| `-- BaseModule/
| `-- Account.setting
`-- DataDump/ # dbm dumpdata output
`-- Users.csv