Configuration
Dubnium reads dubnium.yml from the folder dbm runs in. Create one with dbm init.
Dubnium rejects settings it does not recognise, so a typo in a setting name fails the load instead of being silently ignored. A file that still contains the >>>> placeholder also fails to load.
Example
ConfigurationVersion: 2
CreatedByDubniumVersion: '1.1.94'
ProjectName: 'MyApp'
MigrationPath: '..\Database\Migration'
SchemaPath: '..\Database\Schema'
TempPath: 'c:\temp\'
Databases:
- Key: 'local'
Name: 'Local'
Connection:
Source: Inline
Value: 'Integrated Security=SSPI;Initial Catalog=MyAppDev;Data Source=(local);Encrypt=True'
- Key: 'test'
Name: 'Test'
Connection:
Source: EnvironmentVariable
Value: 'MYAPP_TEST_CONNECTION_STRING'
ScaffoldDatabaseKey: 'local'
Registration:
LicensedEmail: 'you@company.com'
RegistrationCode: '<<SET_LOCALLY>>'
Variables:
SCHEMA_NAME: 'dbo'
RerunScriptTypes: []
DataMigration:
Folder: '..\Data\DataDump'
Tables:
- 'BaseCountry'
DefaultMatchColumn: 'Ukey'
SettingMigration:
Folder: '..\Database\Setting'
Tables:
- 'BaseModule'
TableMatchColumns:
BaseModule: 'Name'
SchemaDocumentation:
MarkdownPath: '..\Database\Documentation\DatabaseSchema.md'
PdfPath: '..\Database\Documentation\DatabaseSchema.pdf'
Skip:
StoredProcedures:
- sp_creatediagram
OpenNewScriptFile: false
Verbose: false
DryRun: false
Paths
Relative paths resolve from the folder of the configuration file. When dubnium.yml is not redirected, that is the folder dbm runs in. This applies to MigrationPath, SchemaPath, DataMigration.Folder, SettingMigration.Folder, SchemaDocumentation.MarkdownPath / PdfPath, and CryptexFile connection values. TempPath is the exception: use an absolute path, ending in \.
Settings
ConfigurationVersion
Required: Yes. Must be 2, the named-target format described on this page.
CreatedByDubniumVersion
Informational only. dbm init writes the Dubnium version that created the file. It is optional, never validated, and does not change behaviour. Verbose output shows it when the configuration loads.
ProjectName
Required: Yes. A descriptive name for the project.
MigrationPath
Required: Yes. Default: Migration
Root folder of the migration scripts. Dubnium uses three subfolders, each with its own number sequence and deployment watermark:
| Subfolder | Purpose | Deploy order |
|---|---|---|
Platform/ | Infrastructure: core schema, base tables, triggers | 1st |
Generated/ | Output of code-generation tools | 2nd |
Application/ | Feature tables, seed data, stored procedures | 3rd |
dbm setup <target> creates the folders. Backups go to a Backup folder beside MigrationPath.
SchemaPath
Required: Yes. Default: Schema
Folder that setsource fills with the reference schema dump. setsource deletes everything in it first, so keep nothing else there.
TempPath
Required: Yes. Default: c:\temp\
Working folder for comparison sessions, the HTML diff report, verbose command logs, and decrypted Cryptex files (which are deleted straight after use).
Databases
Required: At least one target.
Each target has a Key (what you pass to commands, such as dbm deploy test), a display Name, and a Connection. Keys and names must each be unique, ignoring case.
Connection.Source | Connection.Value |
|---|---|
Inline | The connection string itself. Use only for local development without secrets. |
EnvironmentVariable | Name of the environment variable holding the connection string. Fails if the variable is not set. |
CryptexFile | Path to a Cryptex-encrypted file holding the connection string. Needs the cryptex tool on the PATH and the CRYPTEX_PASSPHRASE environment variable. |
Databases:
- Key: 'prod'
Name: 'Production'
Connection:
Source: CryptexFile
Value: 'prod.connection.enc'
ScaffoldDatabaseKey
Optional. The target that tooling should scaffold from. When set, it must match a configured Key.
Registration
Required for paid commands (build, deploy, shift).
| Key | Rule |
|---|---|
LicensedEmail | A valid email address |
RegistrationCode | At least 6 characters |
Treat the registration code as a secret: keep it out of committed files (see Redirecting to a configuration file elsewhere).
Variables
Optional. Values for {{NAME}} tokens in migration scripts. Names are letters, digits, and _, with no spaces inside the braces. A script that uses an undefined variable fails the deployment, and a script with variables cannot be run directly in SSMS by mistake.
Variables:
SCHEMA_NAME: 'dbo'
TABLE_PREFIX: 'APP'
RerunScriptTypes
Optional. Script types (Platform, Generated, Application) whose scripts all run on every deployment, even if already recorded. Only list types whose scripts are written to be re-runnable. An unknown type fails the load.
OpenNewScriptFile
Default: false. When true, dbm new opens the new script in its default editor.
Verbose
Default: false. Prints detailed progress and appends every command to a dubnium-commands_<timestamp>.log file in TempPath.
DryRun
Default: false. Commands report what they would do without changing databases or files.
TablesToDump
Optional. Fallback table list for dumpdata when DataMigration.Tables is empty.
DataMigration
Used by dumpdata, and by settingdeploy for whole-table CSV files.
| Key | Default | Description |
|---|---|---|
Folder | DataDump | Where dumpdata writes <Table>.csv files |
Tables | (empty) | Tables dumpdata exports when none are named on the command line |
DefaultMatchColumn | Ukey | Business key used to match CSV rows to existing rows on import |
TableMatchColumns | (empty) | Per-table match-column overrides |
CreatedBy / UpdatedBy | Dubnium | Audit user stamped on imported rows |
FailFast | true | Stop at the first failing file |
SettingMigration
Used by settingdump and settingdeploy. Settings are never applied by deploy.
| Key | Default | Description |
|---|---|---|
Folder | Setting | Root folder for setting files. Each table gets a subfolder. |
Tables | (empty) | Tables to dump and deploy. At least one is required. |
MatchColumn | Ukey | Business key used to match rows across environments. Never the identity Id. |
TableMatchColumns | (empty) | Per-table match-column overrides; a table or schema-qualified table name maps to a column. |
FileNameColumn | Name | Column that names each file. Falls back to MatchColumn when it is not exported. |
IgnoreColumns | Id, CreatedAt, CreatedBy, UpdatedAt, UpdatedBy | Columns left out so files stay environment-neutral. Omit the key to keep these defaults. |
CreatedBy / UpdatedBy | Dubnium | Audit user stamped on rows written by settingdeploy |
FailFast | true | Stop the whole deployment when one table fails |
SchemaDocumentation
Used by schemadoc. The whole section is optional.
SchemaDocumentation:
MarkdownPath: '..\Database\Documentation\DatabaseSchema.md'
PdfPath: '..\Database\Documentation\DatabaseSchema.pdf'
StandardColumns:
- Name: 'Id'
Types: ['int', 'bigint']
Nullable: false
PrimaryKey: true
- Name: 'Ukey'
Types: ['varchar(32)']
- Name: 'UpdatedAt'
Types: ['datetime']
Nullable: true
| Key | Default | Description |
|---|---|---|
MarkdownPath | Documentation\DatabaseSchema.md | Markdown output |
PdfPath | Documentation\DatabaseSchema.pdf | PDF output |
StandardColumns | (empty) | Columns every table should have. A column that meets its standard is left out of the document; one that deviates is listed with the standard in Ref / Rule; a missing one is listed as Missing. |
Each standard column takes Name, Types (accepted types as the document prints them, such as varchar(32), nvarchar(max) or decimal(18, 2)), Nullable (default false), and PrimaryKey (default false; when true, the column must be part of the primary key). Names must be unique, and each needs at least one type.
Skip
Objects left out of setsource, compare, and schemadoc (stored-procedure entries apply to the schema dumps only).
Skip:
Tables:
- 'AuditLog'
TableRegexPatterns:
- '^tmp_'
StoredProcedures:
- sp_creatediagram
StoredProcedureRegexPatterns: []
Redirecting to a Configuration File Elsewhere
The dubnium.yml in the folder where dbm runs can be a placeholder holding only ConfigPath, which names the real configuration file:
# Tools/dubnium.yml - placeholder only; the real configuration lives in Config
ConfigPath: '..\Config\dubnium.yml'
ConfigPathresolves from the placeholder's folder, or can be absolute.- The placeholder must contain only
ConfigPath; anything else fails the load, so it is always clear which file is in effect. - The target must be a real configuration file, not another redirect.
- Relative paths inside the target resolve from the target's folder.
This keeps one real configuration (for example, beside other secured configuration files) while dbm still runs from its usual folder.
Best Practices
- Keep secrets out of source control. Use
EnvironmentVariableorCryptexFileconnections for shared environments, and keep the registration code out of committed files. - Commit the reviewable output: migration scripts, the
SchemaPathdump, setting files, and the schema Markdown. - Check before deploying:
dbm verify, thendbm deploy <target>. UseDryRun: trueto preview.