Skip to main content

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:

SubfolderPurposeDeploy order
Platform/Infrastructure: core schema, base tables, triggers1st
Generated/Output of code-generation tools2nd
Application/Feature tables, seed data, stored procedures3rd

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.SourceConnection.Value
InlineThe connection string itself. Use only for local development without secrets.
EnvironmentVariableName of the environment variable holding the connection string. Fails if the variable is not set.
CryptexFilePath 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).

KeyRule
LicensedEmailA valid email address
RegistrationCodeAt 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.

KeyDefaultDescription
FolderDataDumpWhere dumpdata writes <Table>.csv files
Tables(empty)Tables dumpdata exports when none are named on the command line
DefaultMatchColumnUkeyBusiness key used to match CSV rows to existing rows on import
TableMatchColumns(empty)Per-table match-column overrides
CreatedBy / UpdatedByDubniumAudit user stamped on imported rows
FailFasttrueStop at the first failing file

SettingMigration​

Used by settingdump and settingdeploy. Settings are never applied by deploy.

KeyDefaultDescription
FolderSettingRoot folder for setting files. Each table gets a subfolder.
Tables(empty)Tables to dump and deploy. At least one is required.
MatchColumnUkeyBusiness 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.
FileNameColumnNameColumn that names each file. Falls back to MatchColumn when it is not exported.
IgnoreColumnsId, CreatedAt, CreatedBy, UpdatedAt, UpdatedByColumns left out so files stay environment-neutral. Omit the key to keep these defaults.
CreatedBy / UpdatedByDubniumAudit user stamped on rows written by settingdeploy
FailFasttrueStop 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
KeyDefaultDescription
MarkdownPathDocumentation\DatabaseSchema.mdMarkdown output
PdfPathDocumentation\DatabaseSchema.pdfPDF 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'
  • ConfigPath resolves 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 EnvironmentVariable or CryptexFile connections for shared environments, and keep the registration code out of committed files.
  • Commit the reviewable output: migration scripts, the SchemaPath dump, setting files, and the schema Markdown.
  • Check before deploying: dbm verify, then dbm deploy <target>. Use DryRun: true to preview.