Skip to main content

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