fix: PR #4039 F1c — MySQL fresh install honors SchemaName end-to-end (builder + V2..V7 ALTERs + detection)

PR #4039 reviewer item M4-1 (comment 4485697019) — MySQL half of F1.

In MySQL "schema" is synonymous with "database". The pre-F1c behaviour:
- MySqlOutboxBuilder / MySqlInboxBuilder GetDDL emitted unqualified
  `CREATE TABLE IF NOT EXISTS {table}`, landing the table in DATABASE() (the
  connection's bound database).
- V2..V7 ALTERs used unqualified `{table}` and probed
  `information_schema.columns WHERE table_schema = DATABASE()`.
- MySqlBoxDetectionHelper used the configured SchemaName for box-table
  existence checks AND for the history-table existence check.

When SchemaName != connection.Database (a legitimate multi-tenant scenario),
the box table landed in DATABASE() while detection looked in SchemaName — the
silent split the reviewer flagged. A second run reported "no table" and
re-ran fresh install, producing PK conflicts on history insert.

Fix (Full schema-aware approach per user direction):

1. MySqlOutboxBuilder.GetDDL + MySqlInboxBuilder.GetDDL gain optional
   `schemaName` parameter — when non-null, emit `\`schema\`.\`table\`` (backticked);
   otherwise unqualified as before.
2. MySqlOutboxMigrationCatalog + MySqlInboxMigrationCatalog:
   - FreshInstallDdl threads configuration.SchemaName through to the builder
     with defence-in-depth Identifiers.AssertSafe.
   - V2..V7 ALTERs (via AddColumn helpers) take an optional `schema` parameter.
     When non-null, the table_schema probe filter and the ALTER target are both
     schema-qualified; when null, original behaviour (DATABASE() / unqualified)
     is preserved bit-for-bit.
3. MySqlBoxDetectionHelper.DoesHistoryExistAsync — the history table itself
   always lives in connection.Database (the runner's EnsureHistoryTableAsync
   emits unqualified DDL targeting DATABASE()), so the table-existence probe
   now uses connection.Database. The schemaName parameter still scopes the
   ROW lookup via the SchemaName column filter. Comment updated.

V1HistoricalDdl on both catalogs stays unqualified (historical literal — pre-
SchemaName-era). The unusual chain-bootstrap-at-V1 path with non-default
SchemaName is not exercised in practice; documented constraint.

Integration tests:
- When_mysql_outbox_provisioner_runs_on_fresh_database_with_non_default_schema_it_should_create_in_configured_schema
- When_mysql_inbox_provisioner_runs_on_fresh_database_with_non_default_schema_it_should_create_in_configured_schema
Both pre-create a non-default database, configure SchemaName to it, run the
provisioner twice, and assert (a) table lands in configured database (not
BrighterTests/connection-default), (b) second run is idempotent, (c) history
records exactly one V_latest row. Pre-fix: outbox test failed at "must exist
in 'brighter_billing_*'"; after the builder+ALTER fix, detection bug surfaced
as PK conflict on history insert (second run). Post-detection-fix: both tests
GREEN.

Full MySQL BoxProvisioning suite: 76/76 GREEN net9.0 (+2 vs the 74 post-F2
baseline).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: iancooper

src/Paramore.Brighter.BoxProvisioning.MySql/MySqlBoxDetectionHelper.cs

@@ -75,15 +75,26 @@ SELECT EXISTS(SELECT 1 FROM information_schema.tables
     /// Returns true if the migration history table exists and has at least one row for the given
     /// box table.
     /// </summary>
-    /// <param name="schemaName">Optional. Null is substituted with <c>connection.Database</c> per ADR 0057 §A.1.</param>
+    /// <param name="schemaName">
+    /// Optional. Filters the history rows by their <c>SchemaName</c> column. Null is substituted
+    /// with <c>connection.Database</c> per ADR 0057 §A.1. Note: this parameter scopes the
+    /// content lookup, NOT the existence check for the history table itself — the history table
+    /// always lives in the connection's bound database, even when the box table is provisioned
+    /// in a different schema (per PR #4039 F1c).
+    /// </param>
     /// <param name="transaction">Accepted and ignored — MySQL DDL auto-commits per ADR 0057 §5a.</param>
     public async Task<bool> DoesHistoryExistAsync(
         MySqlConnection connection, string tableName, string? schemaName,
         CancellationToken cancellationToken = default,
         MySqlTransaction? transaction = null)
     {
+        // The history table always resides in connection.Database (the MySQL runner's
+        // EnsureHistoryTableAsync emits an unqualified CREATE TABLE IF NOT EXISTS targeting
+        // DATABASE()). Probe its existence against connection.Database — not the
+        // box-table SchemaName — so a non-default SchemaName configuration (F1c) does not
+        // misreport HistoryAbsent and trigger a redundant bootstrap path.
         var historyTableExists = await DoesTableExistAsync(
-            connection, "__BrighterMigrationHistory", schemaName, cancellationToken);
+            connection, "__BrighterMigrationHistory", connection.Database, cancellationToken);
         if (!historyTableExists)
             return false;
 

src/Paramore.Brighter.BoxProvisioning.MySql/MySqlInboxMigrationCatalog.cs

@@ -96,7 +96,19 @@ public string FreshInstallDdl(IAmARelationalDatabaseConfiguration configuration)
         Identifiers.AssertSafe(
             configuration.InBoxTableName,
             nameof(IAmARelationalDatabaseConfiguration.InBoxTableName));
-        return MySqlInboxBuilder.GetDDL(configuration.InBoxTableName, configuration.BinaryMessagePayload);
+        // Pass SchemaName so the builder schema-qualifies the CREATE TABLE. Per PR #4039
+        // reviewer item M4-1 (F1c). See MySqlOutboxMigrationCatalog for the full rationale.
+        if (configuration.SchemaName is not null)
+        {
+            Identifiers.AssertSafe(
+                configuration.SchemaName,
+                nameof(IAmARelationalDatabaseConfiguration.SchemaName));
+        }
+        return MySqlInboxBuilder.GetDDL(
+            configuration.InBoxTableName,
+            configuration.BinaryMessagePayload,
+            jsonMessage: false,
+            schemaName: configuration.SchemaName);
     }
 
     /// <summary>
@@ -107,8 +119,13 @@ public string FreshInstallDdl(IAmARelationalDatabaseConfiguration configuration)
     public IReadOnlyList<IAmABoxMigration> All(IAmARelationalDatabaseConfiguration configuration)
     {
         var table = configuration.InBoxTableName;
+        var schema = configuration.SchemaName;
 
         Identifiers.AssertSafe(table, nameof(IAmARelationalDatabaseConfiguration.InBoxTableName));
+        if (schema is not null)
+        {
+            Identifiers.AssertSafe(schema, nameof(IAmARelationalDatabaseConfiguration.SchemaName));
+        }
 
         return
         [
@@ -121,7 +138,7 @@ public IReadOnlyList<IAmABoxMigration> All(IAmARelationalDatabaseConfiguration c
             new BoxMigration(
                 Version: 2,
                 Description: "Add ContextKey column",
-                UpScript: AddColumn(table, "ContextKey", "VARCHAR(256)"),
+                UpScript: AddColumn(schema, table, "ContextKey", "VARCHAR(256)"),
                 LogicalColumns: Cumulative(2),
                 SourceReference: "787c31c52")
         ];
@@ -137,19 +154,24 @@ private static IReadOnlyCollection<string> Cumulative(int upToVersion)
 
     /// <summary>
     /// MySQL 5.7+ idempotent ADD COLUMN — runtime <c>information_schema.columns</c> probe drives
-    /// a prepared-statement that conditionally emits the ALTER. Runs against
-    /// <c>DATABASE()</c> (the connection's bound schema), matching the un-qualified ALTER target.
-    /// The added column is <c>NULL</c>-able — required because MySQL ADD COLUMN against a
-    /// non-empty table must permit NULL or supply a DEFAULT, and we make no assumption about
-    /// emptiness during bootstrap.
+    /// a prepared-statement that conditionally emits the ALTER. When <paramref name="schema"/>
+    /// is null, the probe targets <c>DATABASE()</c> and the ALTER is unqualified — original
+    /// behaviour preserved. When non-null, both probe and ALTER are pinned to the configured
+    /// schema (per PR #4039 reviewer item M4-1 / F1c). The added column is <c>NULL</c>-able —
+    /// required because MySQL ADD COLUMN against a non-empty table must permit NULL or supply
+    /// a DEFAULT, and we make no assumption about emptiness during bootstrap.
     /// </summary>
-    private static string AddColumn(string table, string column, string type) =>
-        $@"SET @q = (SELECT IF(
+    private static string AddColumn(string? schema, string table, string column, string type)
+    {
+        var tableScopeForProbe = schema is null ? "DATABASE()" : $"'{schema}'";
+        var qualifiedAlterTarget = schema is null ? $"`{table}`" : $"`{schema}`.`{table}`";
+        return $@"SET @q = (SELECT IF(
     (SELECT COUNT(*) FROM information_schema.columns
-     WHERE table_schema = DATABASE() AND table_name = '{table}' AND column_name = '{column}') = 0,
-    'ALTER TABLE `{table}` ADD COLUMN `{column}` {type} NULL',
+     WHERE table_schema = {tableScopeForProbe} AND table_name = '{table}' AND column_name = '{column}') = 0,
+    'ALTER TABLE {qualifiedAlterTarget} ADD COLUMN `{column}` {type} NULL',
     'SELECT 1'));
 PREPARE stmt FROM @q;
 EXECUTE stmt;
 DEALLOCATE PREPARE stmt;";
+    }
 }

src/Paramore.Brighter.BoxProvisioning.MySql/MySqlOutboxMigrationCatalog.cs

@@ -97,7 +97,21 @@ public string FreshInstallDdl(IAmARelationalDatabaseConfiguration configuration)
         Identifiers.AssertSafe(
             configuration.OutBoxTableName,
             nameof(IAmARelationalDatabaseConfiguration.OutBoxTableName));
-        return MySqlOutboxBuilder.GetDDL(configuration.OutBoxTableName, configuration.BinaryMessagePayload);
+        // In MySQL "schema" is synonymous with "database". When SchemaName is set, the
+        // builder schema-qualifies the CREATE TABLE so the table lands in the configured
+        // database rather than the connection's bound DATABASE(). V2..V7 ALTERs below pick
+        // up the same qualification via the `schema` parameter on AddColumns. Per PR #4039
+        // reviewer item M4-1 (F1c).
+        if (configuration.SchemaName is not null)
+        {
+            Identifiers.AssertSafe(
+                configuration.SchemaName,
+                nameof(IAmARelationalDatabaseConfiguration.SchemaName));
+        }
+        return MySqlOutboxBuilder.GetDDL(
+            configuration.OutBoxTableName,
+            configuration.BinaryMessagePayload,
+            configuration.SchemaName);
     }
 
     /// <summary>
@@ -108,8 +122,13 @@ public string FreshInstallDdl(IAmARelationalDatabaseConfiguration configuration)
     public IReadOnlyList<IAmABoxMigration> All(IAmARelationalDatabaseConfiguration configuration)
     {
         var table = configuration.OutBoxTableName;
+        var schema = configuration.SchemaName;
 
         Identifiers.AssertSafe(table, nameof(IAmARelationalDatabaseConfiguration.OutBoxTableName));
+        if (schema is not null)
+        {
+            Identifiers.AssertSafe(schema, nameof(IAmARelationalDatabaseConfiguration.SchemaName));
+        }
 
         return
         [
@@ -122,14 +141,14 @@ public IReadOnlyList<IAmABoxMigration> All(IAmARelationalDatabaseConfiguration c
             new BoxMigration(
                 Version: 2,
                 Description: "Add Dispatched column",
-                UpScript: AddColumns(table, ("Dispatched", "TIMESTAMP(3)")),
+                UpScript: AddColumns(schema, table, ("Dispatched", "TIMESTAMP(3)")),
                 LogicalColumns: Cumulative(2),
                 SourceReference: "3c30343fa"),
 
             new BoxMigration(
                 Version: 3,
                 Description: "Add CorrelationId, ReplyTo, ContentType columns",
-                UpScript: AddColumns(table,
+                UpScript: AddColumns(schema, table,
                     ("CorrelationId", "VARCHAR(255)"),
                     ("ReplyTo", "VARCHAR(255)"),
                     ("ContentType", "VARCHAR(128)")),
@@ -139,14 +158,14 @@ public IReadOnlyList<IAmABoxMigration> All(IAmARelationalDatabaseConfiguration c
             new BoxMigration(
                 Version: 4,
                 Description: "Add PartitionKey column",
-                UpScript: AddColumns(table, ("PartitionKey", "VARCHAR(128)")),
+                UpScript: AddColumns(schema, table, ("PartitionKey", "VARCHAR(128)")),
                 LogicalColumns: Cumulative(4),
                 SourceReference: "1cdc04b60 / #2560"),
 
             new BoxMigration(
                 Version: 5,
                 Description: "Add CloudEvents columns (Source, Type, DataSchema, Subject, TraceParent, TraceState, Baggage)",
-                UpScript: AddColumns(table,
+                UpScript: AddColumns(schema, table,
                     ("Source", "VARCHAR(255)"),
                     ("Type", "VARCHAR(255)"),
                     ("DataSchema", "VARCHAR(255)"),
@@ -160,7 +179,7 @@ public IReadOnlyList<IAmABoxMigration> All(IAmARelationalDatabaseConfiguration c
             new BoxMigration(
                 Version: 6,
                 Description: "Add WorkflowId, JobId columns",
-                UpScript: AddColumns(table,
+                UpScript: AddColumns(schema, table,
                     ("WorkflowId", "VARCHAR(255)"),
                     ("JobId", "VARCHAR(255)")),
                 LogicalColumns: Cumulative(6),
@@ -169,7 +188,7 @@ public IReadOnlyList<IAmABoxMigration> All(IAmARelationalDatabaseConfiguration c
             new BoxMigration(
                 Version: 7,
                 Description: "Add DataRef, SpecVersion columns",
-                UpScript: AddColumns(table,
+                UpScript: AddColumns(schema, table,
                     ("DataRef", "VARCHAR(255)"),
                     ("SpecVersion", "VARCHAR(255)")),
                 LogicalColumns: Cumulative(7),
@@ -190,24 +209,32 @@ private static IReadOnlyCollection<string> Cumulative(int upToVersion)
         return set;
     }
 
-    private static string AddColumns(string table, params (string Column, string Type)[] columns) =>
-        string.Join(Environment.NewLine, columns.Select(c => AddColumn(table, c.Column, c.Type)));
+    private static string AddColumns(string? schema, string table, params (string Column, string Type)[] columns) =>
+        string.Join(Environment.NewLine, columns.Select(c => AddColumn(schema, table, c.Column, c.Type)));
 
     /// <summary>
     /// MySQL 5.7+ idempotent ADD COLUMN — runtime <c>information_schema.columns</c> probe drives
-    /// a prepared-statement that conditionally emits the ALTER. Runs against
-    /// <c>DATABASE()</c> (the connection's bound schema), matching the un-qualified ALTER target.
+    /// a prepared-statement that conditionally emits the ALTER. When <paramref name="schema"/>
+    /// is null, the probe targets <c>DATABASE()</c> (the connection's bound database) and the
+    /// ALTER is unqualified — original behaviour preserved. When <paramref name="schema"/> is
+    /// non-null, both the probe's <c>table_schema</c> filter and the ALTER target are pinned
+    /// to that schema, so the chain reaches the box table created in the configured database
+    /// (per PR #4039 reviewer item M4-1 / F1c).
     /// All added columns are <c>NULL</c>-able — required because MySQL ADD COLUMN against a
     /// non-empty table must permit NULL or supply a DEFAULT, and we make no assumption about
     /// emptiness during bootstrap.
     /// </summary>
-    private static string AddColumn(string table, string column, string type) =>
-        $@"SET @q = (SELECT IF(
+    private static string AddColumn(string? schema, string table, string column, string type)
+    {
+        var tableScopeForProbe = schema is null ? "DATABASE()" : $"'{schema}'";
+        var qualifiedAlterTarget = schema is null ? $"`{table}`" : $"`{schema}`.`{table}`";
+        return $@"SET @q = (SELECT IF(
     (SELECT COUNT(*) FROM information_schema.columns
-     WHERE table_schema = DATABASE() AND table_name = '{table}' AND column_name = '{column}') = 0,
-    'ALTER TABLE `{table}` ADD COLUMN `{column}` {type} NULL',
+     WHERE table_schema = {tableScopeForProbe} AND table_name = '{table}' AND column_name = '{column}') = 0,
+    'ALTER TABLE {qualifiedAlterTarget} ADD COLUMN `{column}` {type} NULL',
     'SELECT 1'));
 PREPARE stmt FROM @q;
 EXECUTE stmt;
 DEALLOCATE PREPARE stmt;";
+    }
 }

src/Paramore.Brighter.Inbox.MySql/MySqlInboxBuilder.cs

@@ -76,19 +76,30 @@ PRIMARY KEY (`CommandId`)
         /// Gets the DDL statements to create an Inbox in MySQL
         /// </summary>
         /// <param name="inboxTableName">The Inbox Table Name</param>
+        /// <param name="binaryMessage">Should the command body be stored as binary.</param>
+        /// <param name="jsonMessage">Should the command body be stored using the JSON type.</param>
+        /// <param name="schemaName">
+        /// Optional MySQL schema (database) name. When non-null, the emitted DDL schema-qualifies
+        /// the table as <c>`schemaName`.`inboxTableName`</c>; otherwise the table is emitted
+        /// unqualified and lands in the connection's bound database. Per PR #4039 reviewer
+        /// item M4-1 (F1c). See the outbox builder for the full rationale.
+        /// </param>
         /// <returns></returns>
-        public static string GetDDL(string inboxTableName, bool binaryMessage = false, bool jsonMessage = false)
+        public static string GetDDL(string inboxTableName, bool binaryMessage = false, bool jsonMessage = false, string? schemaName = null)
         {
+            var qualifiedTable = schemaName is null
+                ? inboxTableName
+                : $"`{schemaName}`.`{inboxTableName}`";
             if (jsonMessage)
             {
-                return string.Format(JsonInboxDDL, inboxTableName);
+                return string.Format(JsonInboxDDL, qualifiedTable);
             }
             if (binaryMessage)
             {
-                return string.Format(BinaryInboxxDDL, inboxTableName);
+                return string.Format(BinaryInboxxDDL, qualifiedTable);
             }
 
-            return string.Format(TextInboxDDL, inboxTableName);
+            return string.Format(TextInboxDDL, qualifiedTable);
         }
 
         /// <summary>

src/Paramore.Brighter.Outbox.MySql/MySqlOutboxBuilder.cs

@@ -104,13 +104,25 @@ PRIMARY KEY (`MessageId`)
         /// </summary>
         /// <param name="outboxTableName">The name of the table to store messages in</param>
         /// <param name="hasBinaryMessagePayload">Should the message body be stored as binary? Conversion of binary data to/from UTF-8 is lossy</param>
+        /// <param name="schemaName">
+        /// Optional MySQL schema (database) name. When non-null, the emitted DDL schema-qualifies
+        /// the table as <c>`schemaName`.`outboxTableName`</c>; otherwise the table is emitted
+        /// unqualified and lands in the connection's bound database (<c>DATABASE()</c>). In MySQL
+        /// "schema" is synonymous with "database"; per PR #4039 reviewer item M4-1 (F1c),
+        /// configuring <see cref="Paramore.Brighter.IAmARelationalDatabaseConfiguration.SchemaName"/>
+        /// to a database different from the connection's bound database requires schema-qualified
+        /// DDL — without it, detection looks in SchemaName while creation lands in DATABASE().
+        /// </param>
         /// <returns></returns>
-        public static string GetDDL(string outboxTableName, bool hasBinaryMessagePayload = false)
+        public static string GetDDL(string outboxTableName, bool hasBinaryMessagePayload = false, string? schemaName = null)
         {
             if (string.IsNullOrEmpty(outboxTableName))
                 throw new ArgumentNullException(outboxTableName, $"You must provide a tablename for the OutBox table");
 
-            return string.Format(hasBinaryMessagePayload ? BinaryOutboxDdl : TextOutboxDdl, outboxTableName);
+            var qualifiedTable = schemaName is null
+                ? outboxTableName
+                : $"`{schemaName}`.`{outboxTableName}`";
+            return string.Format(hasBinaryMessagePayload ? BinaryOutboxDdl : TextOutboxDdl, qualifiedTable);
         }
 
         /// <summary>