Dream Consistency Platform Tool
Controlled console utility for validating, planning, installing, and upgrading versioned
shared system catalogs in Realm, Management, and Billing databases.
DreamConsistency.SystemCatalogInstaller.Cnsl is the single database-aware installer
for shared Dream Consistency system catalogs.
The executable consumes fixed versions of DreamConsistency.RealmCatalogs,
DreamConsistency.ManagementCatalogs, and
DreamConsistency.BillingCatalogs, maps their embedded JSON models to the corresponding
Tables contracts, and applies the required catalog rows to compatible physical databases.
Single-installer rule:
Realm, Management, and Billing use one executable with database-specific mappings.
Separate installation NuGet projects are not created for each database.
Run the installer only when one of the following operational events occurs:
- A new Dream Consistency environment is being provisioned.
- A new Realm, Management, or Billing database has been created.
- A new shared catalog package version has been published.
- A compatible database schema update introduces catalog content required by a new feature.
- A controlled catalog repair or verification operation is required.
The installer is not part of normal API startup and is not expected to run frequently.
- List the logical catalog packages embedded in the selected catalog libraries.
- Validate manifests, dependencies, identities, content, and installer mapping coverage.
- Verify the physical database identity using
SELECT DATABASE().
- Read the latest active database
ContractVersion.
- Verify that the database contract satisfies each package minimum version.
- Resolve package dependencies in topological order.
- Build a deterministic insert, update, unchanged, and conflict plan.
- Acquire a MySQL connection-scoped named lock.
- Apply one local transaction per physical database.
- Roll back the active database transaction when a conflict or database error occurs.
- Create or migrate database schemas.
- Insert schema-version history records.
- Create the authoritative self Realm.
- Create the first Core operator.
- Register product-specific packages, metrics, or import types.
- Install Hestino- or Legislator-specific tenant catalogs.
- Provide a distributed transaction across Realm, Management, and Billing.
- Run automatically when an API or application starts.
| Database |
Catalog Library |
Tables Contract |
| Realm |
DreamConsistency.RealmCatalogs |
DreamConsistency.RealmTables |
| Management |
DreamConsistency.ManagementCatalogs |
DreamConsistency.ManagementTables |
| Billing |
DreamConsistency.BillingCatalogs |
DreamConsistency.BillingTables |
- The target physical schema already exists.
- The relevant
INF_*SchemaVersions table contains an active deployed record.
- The latest record contains valid
SchemaVersion and ContractVersion values.
- The target database contract is compatible with the catalog package minimum requirement.
- The correct Catalogs and Tables NuGet versions are restored by the installer project.
- The configured database user can read, insert, update, use transactions, and acquire named locks.
- The expected database name is known and supplied explicitly.
Safe defaults belong in appsettings.json. Local connection strings belong in
appsettings.Local.json, which must be excluded from source control.
{
"DatabaseSettings": {
"RealmDatabaseConnection": "Server=...;Port=3306;Database=realmdb;User ID=...;Password=...;",
"ManagementDatabaseConnection": "Server=...;Port=3306;Database=managementdb;User ID=...;Password=...;",
"BillingDatabaseConnection": "Server=...;Port=3306;Database=billingdb;User ID=...;Password=...;"
}
}
Secret rule:
Never pass connection strings or passwords as command-line arguments.
¶ Supported Commands
| Command |
Purpose |
Writes to Database |
list-packages |
Lists available logical packages for one database or all databases. |
No |
validate |
Validates catalog sources, dependencies, identities, and installer mapping coverage. |
No |
plan |
Connects to the target database and produces the insert, update, unchanged, and conflict plan. |
No committed changes |
dry-run |
Alias for the non-committing planning operation where supported. |
No committed changes |
install |
Applies the selected package or all packages to the selected physical database. |
Yes |
Run these commands after restore and build. They do not change any database:
dotnet run --project .\DreamConsistency.SystemCatalogInstaller.Cnsl\DreamConsistency.SystemCatalogInstaller.Cnsl.csproj -- list-packages --database All
dotnet run --project .\DreamConsistency.SystemCatalogInstaller.Cnsl\DreamConsistency.SystemCatalogInstaller.Cnsl.csproj -- validate --database All
PowerShell note:
Keep the complete command on one line, or place the continuation character at the end of every
continued line. Do not run -- list-packages
dotnet run --project .\DreamConsistency.SystemCatalogInstaller.Cnsl\DreamConsistency.SystemCatalogInstaller.Cnsl.csproj -- plan --database Realm --package DreamConsistency.Realm.Foundation --expected-database-name realmdb
Review the database identity, deployed contract version, package version, planned inserts,
updates, unchanged rows, and conflicts.
dotnet run --project .\DreamConsistency.SystemCatalogInstaller.Cnsl\DreamConsistency.SystemCatalogInstaller.Cnsl.csproj -- install --database Realm --package DreamConsistency.Realm.Foundation --expected-database-name realmdb --allow-without-history
Confirm the write operation when prompted. Realm.Foundation installs the minimum catalogs required
by Realm bootstrap, including environments and Realm operational statuses.
dotnet run --project .\DreamConsistency.RealmBootstrap.Cnsl\DreamConsistency.RealmBootstrap.Cnsl.csproj -- bootstrap-self-realm
Bootstrap verifies Foundation, creates the self Realm, and creates the first Core operator.
¶ Step 4 — Install All Realm Packages
dotnet run --project .\DreamConsistency.SystemCatalogInstaller.Cnsl\DreamConsistency.SystemCatalogInstaller.Cnsl.csproj -- plan --database Realm --all --expected-database-name realmdb
dotnet run --project .\DreamConsistency.SystemCatalogInstaller.Cnsl\DreamConsistency.SystemCatalogInstaller.Cnsl.csproj -- install --database Realm --all --expected-database-name realmdb --allow-without-history
The already installed Foundation package should be reported as unchanged.
dotnet run --project .\DreamConsistency.SystemCatalogInstaller.Cnsl\DreamConsistency.SystemCatalogInstaller.Cnsl.csproj -- plan --database Management --all --expected-database-name managementdb
dotnet run --project .\DreamConsistency.SystemCatalogInstaller.Cnsl\DreamConsistency.SystemCatalogInstaller.Cnsl.csproj -- install --database Management --all --expected-database-name managementdb --allow-without-history
dotnet run --project .\DreamConsistency.SystemCatalogInstaller.Cnsl\DreamConsistency.SystemCatalogInstaller.Cnsl.csproj -- plan --database Billing --all --expected-database-name billingdb
dotnet run --project .\DreamConsistency.SystemCatalogInstaller.Cnsl\DreamConsistency.SystemCatalogInstaller.Cnsl.csproj -- install --database Billing --all --expected-database-name billingdb --allow-without-history
dotnet run --project .\DreamConsistency.SystemCatalogInstaller.Cnsl\DreamConsistency.SystemCatalogInstaller.Cnsl.csproj -- plan --database All --all --expected-realm-database-name realmdb --expected-management-database-name managementdb --expected-billing-database-name billingdb
dotnet run --project .\DreamConsistency.SystemCatalogInstaller.Cnsl\DreamConsistency.SystemCatalogInstaller.Cnsl.csproj -- install --database All --all --expected-realm-database-name realmdb --expected-management-database-name managementdb --expected-billing-database-name billingdb --allow-without-history
No distributed transaction:
All mode executes Realm, Management, and Billing sequentially.
Each physical database has its own transaction and commit.
If Billing fails after Realm and Management succeed, the first two databases remain committed.
The installer reads the latest active ContractVersion from:
INF_RealmSchemaVersions
INF_ManagementSchemaVersions
INF_BillingSchemaVersions
A catalog package is compatible when:
Current database ContractVersion
>= package MinimumSchemaPackageVersion
For example, a database contract version 1.2.0 satisfies a package minimum
requirement of 1.1.1.
When a new catalog version uses a table or column introduced in a newer Tables contract,
its manifest minimum version must be increased accordingly.
| Database State |
Installer Action |
| Expected UUID does not exist |
Insert a new row and generate the database-local RefID. |
| Expected UUID exists with equal managed fields |
Report Unchanged. |
| Expected UUID exists with allowed managed-field differences |
Plan and apply an explicit update. |
| Expected name exists under another UUID |
Report a conflict and stop. |
| Expected UUID is soft-deleted |
Report a conflict by default; do not silently restore it. |
| An item is missing from a newer JSON package |
Do not automatically delete the database row. |
No generic force option:
Identity repair, soft-deleted-row recovery, and controlled downgrade require a dedicated,
reviewed recovery operation.
A successful installation can be followed by the same plan command.
The expected result is that all installed package-managed rows are reported as unchanged
and the conflict count is zero.
Inserted: 0
Updated: 0
Unchanged: expected catalog item count
Conflicts: 0
Applied: False
Succeeded: True
The current Realm, Management, and Billing schemas do not yet contain dedicated system catalog
installation-history tables. Until those tables and mappings are introduced, DEV installation uses:
--allow-without-history
Temporary DEV exception:
This switch is acceptable for the current controlled local DEV process.
It is not the intended long-term Production execution mode.
Database-local installation history is required before authoritative installed-package status,
content-hash drift detection, downgrade protection, and a complete show-status
workflow can be considered Production-ready.
- Do not run
install when plan reports conflicts.
- Correct schema-version, identity, or mapping problems before retrying.
- A failed active database transaction is rolled back.
- Successfully committed earlier databases in All mode are not rolled back.
- After correcting a failure, rerun
plan before rerunning install.
- Never manually change published catalog UUID identities to work around a conflict.
The installer is currently executed locally against Hestino DEV because system catalog installation
is infrequent and should not block product development.
Catalog libraries are still built and published through their manual Jenkins NuGet release jobs.
A versioned installer artifact and controlled QA or Production execution pipeline can be added later.
dream-consistency
platform-tools
system-catalogs
catalog-installer
realm
management
billing
environment-provisioning
| Date |
Change |
Author |
| 2026-08-03 |
Created detailed operational documentation after successful installation of all shared
Realm, Management, and Billing catalogs in the Hestino DEV environment.
|
Branko |