From 9080689b1335135b1e1e5be4f035c3f011617951 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9ctor=20Franco?= Date: Sun, 22 Nov 2026 21:55:13 +0100 Subject: [PATCH 1/7] docs(upgrading): set the table default collation on workflow_definition_sequence --- docs/CHANGELOG.md | 4 ++++ docs/UPGRADING.md | 18 +++++++++++++++--- 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 47492c5..072404e 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -66,6 +66,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Fixed + +- **Documentation: the `workflow_definition_sequence` `CREATE TABLE` in UPGRADING ("To 2.2.0") now sets the table's default collation** (`DEFAULT CHARACTER SET utf8mb4 COLLATE `) so a column added later without an explicit `COLLATE` cannot inherit the server's case-insensitive default and fail joins with MySQL error 1267. UPGRADING also gives the repair statement for an existing table and warns never to use `ALTER TABLE … CONVERT TO CHARACTER SET`, which would rewrite `tenant_key` and `slug` out of their binary collation. No code change. + ## [2.2.0] - 2026-11-22 ### Changed diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md index eadfad5..c3a1a6b 100644 --- a/docs/UPGRADING.md +++ b/docs/UPGRADING.md @@ -127,12 +127,24 @@ php bin/console doctrine:migrations:migrate `definition_sequence`): ```sql - -- MySQL 8.0.17+ (MariaDB: COLLATE `utf8mb4_nopad_bin`; older MySQL: `utf8mb4_bin`) - CREATE TABLE workflow_definition_sequence (tenant_key VARCHAR(128) CHARACTER SET utf8mb4 NOT NULL COLLATE `utf8mb4_0900_bin`, slug VARCHAR(128) CHARACTER SET utf8mb4 NOT NULL COLLATE `utf8mb4_0900_bin`, last_version INT NOT NULL, PRIMARY KEY (tenant_key, slug)); - -- PostgreSQL + -- MySQL 8.0.17+ (MariaDB: COLLATE `utf8mb4_nopad_bin`; older MySQL: `utf8mb4_bin`, in the columns and in the table default) + CREATE TABLE workflow_definition_sequence (tenant_key VARCHAR(128) CHARACTER SET utf8mb4 NOT NULL COLLATE `utf8mb4_0900_bin`, slug VARCHAR(128) CHARACTER SET utf8mb4 NOT NULL COLLATE `utf8mb4_0900_bin`, last_version INT NOT NULL, PRIMARY KEY (tenant_key, slug)) DEFAULT CHARACTER SET utf8mb4 COLLATE `utf8mb4_0900_bin`; + -- PostgreSQL (no table-level collation there, nothing to add) CREATE TABLE workflow_definition_sequence (tenant_key VARCHAR(128) NOT NULL, slug VARCHAR(128) NOT NULL, last_version INT NOT NULL, PRIMARY KEY (tenant_key, slug)); ``` +- **Keep the table default collation.** The trailing `DEFAULT CHARACTER SET utf8mb4 COLLATE …` matters for *future* + columns, not for the two that exist (those carry their own `COLLATE`). A text column added later without an explicit + `COLLATE` inherits the table default, and without this clause that is the server's accent- and case-insensitive one + (typically `utf8mb4_0900_ai_ci`); a join against `tenant_key` or `slug` then fails with MySQL error 1267 (illegal + mix of collations), long after and far from the change that caused it. +- **Repairing a table created without it.** Run + `ALTER TABLE workflow_definition_sequence DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin;` (MariaDB: + `utf8mb4_nopad_bin`; older MySQL: `utf8mb4_bin`). It changes only the default for columns added from now on. **Never + use `ALTER TABLE … CONVERT TO CHARACTER SET …` for this:** `CONVERT TO` rewrites every column, which would move + `tenant_key` and `slug` out of their binary collation and start folding look-alike tenant keys, the exact failure + REQ-SEC-006 exists to prevent. + - **No data migration needed.** The counter row of a scope is created at its first claim, seeded with the highest version already stored. To backfill every scope at once anyway (optional, in the same migration, after the `CREATE TABLE`): From 097cf918d30c0b6f6e6c564fc5d6a02f82e08649 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9ctor=20Franco?= Date: Sun, 22 Nov 2026 22:01:03 +0100 Subject: [PATCH 2/7] docs(upgrading): present the sequence table statement as what to run, not the raw diff --- docs/CHANGELOG.md | 2 +- docs/UPGRADING.md | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 072404e..d83353f 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -68,7 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed -- **Documentation: the `workflow_definition_sequence` `CREATE TABLE` in UPGRADING ("To 2.2.0") now sets the table's default collation** (`DEFAULT CHARACTER SET utf8mb4 COLLATE `) so a column added later without an explicit `COLLATE` cannot inherit the server's case-insensitive default and fail joins with MySQL error 1267. UPGRADING also gives the repair statement for an existing table and warns never to use `ALTER TABLE … CONVERT TO CHARACTER SET`, which would rewrite `tenant_key` and `slug` out of their binary collation. No code change. +- **Documentation: the `workflow_definition_sequence` `CREATE TABLE` in UPGRADING ("To 2.2.0") now sets the table's default collation** (the generated diff and `nowo:workflow:sync-schema` omit it, so the page says to add it or run the repair statement) (`DEFAULT CHARACTER SET utf8mb4 COLLATE `) so a column added later without an explicit `COLLATE` cannot inherit the server's case-insensitive default and fail joins with MySQL error 1267. UPGRADING also gives the repair statement for an existing table and warns never to use `ALTER TABLE … CONVERT TO CHARACTER SET`, which would rewrite `tenant_key` and `slug` out of their binary collation. No code change. ## [2.2.0] - 2026-11-22 diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md index c3a1a6b..5463d19 100644 --- a/docs/UPGRADING.md +++ b/docs/UPGRADING.md @@ -123,8 +123,9 @@ php bin/console doctrine:migrations:migrate again) was `SELECT MAX(version)+1`. It now comes from a per-scope counter row, claimed with an atomic `UPDATE … SET last_version = last_version + 1` in the transaction that inserts the version. See [CONCURRENCY.md, "Definition versions"](CONCURRENCY.md#definition-versions). -- **The table.** What the diff generates without a table prefix (with `nowo_workflow.table_prefix` the table is - `definition_sequence`): +- **The table.** What to run, without a table prefix (with `nowo_workflow.table_prefix` the table is + `definition_sequence`). The diff generates this without the trailing table-level + `DEFAULT CHARACTER SET … COLLATE`; add it yourself and keep it when you compare against the diff: ```sql -- MySQL 8.0.17+ (MariaDB: COLLATE `utf8mb4_nopad_bin`; older MySQL: `utf8mb4_bin`, in the columns and in the table default) @@ -137,7 +138,8 @@ php bin/console doctrine:migrations:migrate columns, not for the two that exist (those carry their own `COLLATE`). A text column added later without an explicit `COLLATE` inherits the table default, and without this clause that is the server's accent- and case-insensitive one (typically `utf8mb4_0900_ai_ci`); a join against `tenant_key` or `slug` then fails with MySQL error 1267 (illegal - mix of collations), long after and far from the change that caused it. + mix of collations), long after and far from the change that caused it. `nowo:workflow:sync-schema` builds the table from the ORM metadata and has the same gap: after + using it (or the diff without the edit), run the repair statement below. - **Repairing a table created without it.** Run `ALTER TABLE workflow_definition_sequence DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin;` (MariaDB: `utf8mb4_nopad_bin`; older MySQL: `utf8mb4_bin`). It changes only the default for columns added from now on. **Never From a0d1ecc4d2941102a7c0068defee4e7ec5f6fac3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9ctor=20Franco?= Date: Sun, 22 Nov 2026 22:03:26 +0100 Subject: [PATCH 3/7] docs(upgrading): name the ORM dump routes and add the table collation check --- docs/CHANGELOG.md | 2 +- docs/UPGRADING.md | 16 ++++++++++++++-- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index d83353f..819b6fc 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -68,7 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed -- **Documentation: the `workflow_definition_sequence` `CREATE TABLE` in UPGRADING ("To 2.2.0") now sets the table's default collation** (the generated diff and `nowo:workflow:sync-schema` omit it, so the page says to add it or run the repair statement) (`DEFAULT CHARACTER SET utf8mb4 COLLATE `) so a column added later without an explicit `COLLATE` cannot inherit the server's case-insensitive default and fail joins with MySQL error 1267. UPGRADING also gives the repair statement for an existing table and warns never to use `ALTER TABLE … CONVERT TO CHARACTER SET`, which would rewrite `tenant_key` and `slug` out of their binary collation. No code change. +- **Documentation: the `workflow_definition_sequence` `CREATE TABLE` in UPGRADING ("To 2.2.0") now sets the table's default collation** (neither `doctrine:schema:update --dump-sql` nor `nowo:workflow:sync-schema` emits it, so the page says to add it or run the repair statement, and gives the `information_schema.TABLES.TABLE_COLLATION` query to verify) (`DEFAULT CHARACTER SET utf8mb4 COLLATE `) so a column added later without an explicit `COLLATE` cannot inherit the server's case-insensitive default and fail joins with MySQL error 1267. UPGRADING also gives the repair statement for an existing table and warns never to use `ALTER TABLE … CONVERT TO CHARACTER SET`, which would rewrite `tenant_key` and `slug` out of their binary collation. No code change. ## [2.2.0] - 2026-11-22 diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md index 5463d19..991abaf 100644 --- a/docs/UPGRADING.md +++ b/docs/UPGRADING.md @@ -138,8 +138,20 @@ php bin/console doctrine:migrations:migrate columns, not for the two that exist (those carry their own `COLLATE`). A text column added later without an explicit `COLLATE` inherits the table default, and without this clause that is the server's accent- and case-insensitive one (typically `utf8mb4_0900_ai_ci`); a join against `tenant_key` or `slug` then fails with MySQL error 1267 (illegal - mix of collations), long after and far from the change that caused it. `nowo:workflow:sync-schema` builds the table from the ORM metadata and has the same gap: after - using it (or the diff without the edit), run the repair statement below. + mix of collations), long after and far from the change that caused it. Neither route that builds the DDL from the ORM metadata + emits the table default: `doctrine:schema:update --dump-sql` (and a migration written from that dump, as one host + did) and `nowo:workflow:sync-schema`. With `sync-schema` there is also no statement the host can read and correct, it + executes the DDL itself, so the host must run the repair `ALTER TABLE` below afterwards. **The clause cannot be + checked by looking at the new table's columns:** every existing column can be correct while the table default is + wrong, and `SHOW CREATE TABLE` read column by column will look fine. Check the table instead: + + ```sql + SELECT TABLE_COLLATION FROM information_schema.TABLES + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'workflow_definition_sequence'; + ``` + + Expected: `utf8mb4_0900_bin` (MySQL 8.0.17+), `utf8mb4_nopad_bin` (MariaDB), `utf8mb4_bin` (older MySQL). Anything + ending in `_ai_ci` means the table needs the repair. - **Repairing a table created without it.** Run `ALTER TABLE workflow_definition_sequence DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin;` (MariaDB: `utf8mb4_nopad_bin`; older MySQL: `utf8mb4_bin`). It changes only the default for columns added from now on. **Never From 038b0f45e81df21c68d53d6f303cd95901d8009e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9ctor=20Franco?= Date: Sun, 22 Nov 2026 22:07:44 +0100 Subject: [PATCH 4/7] docs(upgrading): drop the anecdote about who hit the dump gap --- docs/UPGRADING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md index 991abaf..364d1d6 100644 --- a/docs/UPGRADING.md +++ b/docs/UPGRADING.md @@ -139,8 +139,8 @@ php bin/console doctrine:migrations:migrate `COLLATE` inherits the table default, and without this clause that is the server's accent- and case-insensitive one (typically `utf8mb4_0900_ai_ci`); a join against `tenant_key` or `slug` then fails with MySQL error 1267 (illegal mix of collations), long after and far from the change that caused it. Neither route that builds the DDL from the ORM metadata - emits the table default: `doctrine:schema:update --dump-sql` (and a migration written from that dump, as one host - did) and `nowo:workflow:sync-schema`. With `sync-schema` there is also no statement the host can read and correct, it + emits the table default: `doctrine:schema:update --dump-sql` (and any migration written from that + dump) and `nowo:workflow:sync-schema`. With `sync-schema` there is also no statement the host can read and correct, it executes the DDL itself, so the host must run the repair `ALTER TABLE` below afterwards. **The clause cannot be checked by looking at the new table's columns:** every existing column can be correct while the table default is wrong, and `SHOW CREATE TABLE` read column by column will look fine. Check the table instead: From 0922d681688388619cfa26629a294345e0d802bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9ctor=20Franco?= Date: Sun, 22 Nov 2026 22:11:52 +0100 Subject: [PATCH 5/7] docs(upgrading): recommend default_table_options as the host-level fix --- docs/CHANGELOG.md | 2 +- docs/UPGRADING.md | 40 +++++++++++++++++++++++++++++----------- 2 files changed, 30 insertions(+), 12 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 819b6fc..92f12a8 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -68,7 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed -- **Documentation: the `workflow_definition_sequence` `CREATE TABLE` in UPGRADING ("To 2.2.0") now sets the table's default collation** (neither `doctrine:schema:update --dump-sql` nor `nowo:workflow:sync-schema` emits it, so the page says to add it or run the repair statement, and gives the `information_schema.TABLES.TABLE_COLLATION` query to verify) (`DEFAULT CHARACTER SET utf8mb4 COLLATE `) so a column added later without an explicit `COLLATE` cannot inherit the server's case-insensitive default and fail joins with MySQL error 1267. UPGRADING also gives the repair statement for an existing table and warns never to use `ALTER TABLE … CONVERT TO CHARACTER SET`, which would rewrite `tenant_key` and `slug` out of their binary collation. No code change. +- **Documentation: the `workflow_definition_sequence` `CREATE TABLE` in UPGRADING ("To 2.2.0") now sets the table's default collation** (Doctrine's schema routes, `doctrine:schema:update --dump-sql`, `doctrine:migrations:diff` and `nowo:workflow:sync-schema`, emit it only when the host sets `doctrine.dbal.default_table_options`, so the page recommends setting that once, and gives the `information_schema.TABLES.TABLE_COLLATION` query to verify) (`DEFAULT CHARACTER SET utf8mb4 COLLATE `) so a column added later without an explicit `COLLATE` cannot inherit the server's case-insensitive default and fail joins with MySQL error 1267. UPGRADING also gives the repair statement for an existing table and warns never to use `ALTER TABLE … CONVERT TO CHARACTER SET`, which would rewrite `tenant_key` and `slug` out of their binary collation. No code change. ## [2.2.0] - 2026-11-22 diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md index 364d1d6..c01217c 100644 --- a/docs/UPGRADING.md +++ b/docs/UPGRADING.md @@ -124,8 +124,9 @@ php bin/console doctrine:migrations:migrate `UPDATE … SET last_version = last_version + 1` in the transaction that inserts the version. See [CONCURRENCY.md, "Definition versions"](CONCURRENCY.md#definition-versions). - **The table.** What to run, without a table prefix (with `nowo_workflow.table_prefix` the table is - `definition_sequence`). The diff generates this without the trailing table-level - `DEFAULT CHARACTER SET … COLLATE`; add it yourself and keep it when you compare against the diff: + `definition_sequence`). The diff generates the trailing table-level + `DEFAULT CHARACTER SET … COLLATE` only when the host sets `default_table_options` (see below); otherwise add it + yourself, and keep it when you compare against the diff: ```sql -- MySQL 8.0.17+ (MariaDB: COLLATE `utf8mb4_nopad_bin`; older MySQL: `utf8mb4_bin`, in the columns and in the table default) @@ -134,16 +135,33 @@ php bin/console doctrine:migrations:migrate CREATE TABLE workflow_definition_sequence (tenant_key VARCHAR(128) NOT NULL, slug VARCHAR(128) NOT NULL, last_version INT NOT NULL, PRIMARY KEY (tenant_key, slug)); ``` -- **Keep the table default collation.** The trailing `DEFAULT CHARACTER SET utf8mb4 COLLATE …` matters for *future* +- **Set the table default once, in the host (recommended).** The table's default collation matters for *future* columns, not for the two that exist (those carry their own `COLLATE`). A text column added later without an explicit - `COLLATE` inherits the table default, and without this clause that is the server's accent- and case-insensitive one - (typically `utf8mb4_0900_ai_ci`); a join against `tenant_key` or `slug` then fails with MySQL error 1267 (illegal - mix of collations), long after and far from the change that caused it. Neither route that builds the DDL from the ORM metadata - emits the table default: `doctrine:schema:update --dump-sql` (and any migration written from that - dump) and `nowo:workflow:sync-schema`. With `sync-schema` there is also no statement the host can read and correct, it - executes the DDL itself, so the host must run the repair `ALTER TABLE` below afterwards. **The clause cannot be - checked by looking at the new table's columns:** every existing column can be correct while the table default is - wrong, and `SHOW CREATE TABLE` read column by column will look fine. Check the table instead: + `COLLATE` inherits the table default, and when that is the server's accent- and case-insensitive one (typically + `utf8mb4_0900_ai_ci`) a join against `tenant_key` or `slug` fails with MySQL error 1267 (illegal mix of collations), + long after and far from the change that caused it. Doctrine builds every table from `default_table_options`, so the + host should configure it once instead of patching each table: + + ```yaml + # config/packages/doctrine.yaml + doctrine: + dbal: + default_table_options: + charset: utf8mb4 + collation: utf8mb4_0900_bin # MariaDB: utf8mb4_nopad_bin; older MySQL: utf8mb4_bin + ``` + + With that, `doctrine:schema:update --dump-sql`, `doctrine:migrations:diff` and `nowo:workflow:sync-schema` emit the + `DEFAULT CHARACTER SET … COLLATE` clause on their own, for this table and every other one, and nothing has to be + remembered per table. Use the one binary collation your application already uses uniformly. Without the setting those + routes create the table with the server's default. +- **Why the statement above carries the clause anyway.** A host that has not configured `default_table_options`, or that + runs the `CREATE TABLE` by hand, needs it written out; keeping it does no harm to a host that has configured it. + `nowo:workflow:sync-schema` is the worst case without the setting: it executes the DDL itself, so there is no + statement to read and correct, and the only remedy left is the repair `ALTER TABLE` below. +- **Check the table, not its columns.** The clause cannot be verified by looking at the new table's columns: every + existing column can be correct while the table default is wrong, and `SHOW CREATE TABLE` read column by column will + look fine. Check the table instead: ```sql SELECT TABLE_COLLATION FROM information_schema.TABLES From b5e5df88f7c76b823643ca5d1346ba8bdc567710 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9ctor=20Franco?= Date: Sun, 22 Nov 2026 22:14:56 +0100 Subject: [PATCH 6/7] docs(upgrading): table default is the uniform collation, not the exact-key one --- docs/CHANGELOG.md | 2 +- docs/UPGRADING.md | 43 +++++++++++++++++++++++++------------------ 2 files changed, 26 insertions(+), 19 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 92f12a8..463047d 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -68,7 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed -- **Documentation: the `workflow_definition_sequence` `CREATE TABLE` in UPGRADING ("To 2.2.0") now sets the table's default collation** (Doctrine's schema routes, `doctrine:schema:update --dump-sql`, `doctrine:migrations:diff` and `nowo:workflow:sync-schema`, emit it only when the host sets `doctrine.dbal.default_table_options`, so the page recommends setting that once, and gives the `information_schema.TABLES.TABLE_COLLATION` query to verify) (`DEFAULT CHARACTER SET utf8mb4 COLLATE `) so a column added later without an explicit `COLLATE` cannot inherit the server's case-insensitive default and fail joins with MySQL error 1267. UPGRADING also gives the repair statement for an existing table and warns never to use `ALTER TABLE … CONVERT TO CHARACTER SET`, which would rewrite `tenant_key` and `slug` out of their binary collation. No code change. +- **Documentation: the `workflow_definition_sequence` `CREATE TABLE` in UPGRADING ("To 2.2.0") now sets the table's default collation to the database's uniform collation** (`DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci`, not the binary key collation), and recommends setting `doctrine.dbal.default_table_options` once in the host, since Doctrine's schema routes (`doctrine:schema:update --dump-sql`, `doctrine:migrations:diff`, `nowo:workflow:sync-schema`) emit the clause only then. Without it a column added later without an explicit `COLLATE` inherits the server default and fails joins with MySQL error 1267. UPGRADING also gives the `information_schema.TABLES.TABLE_COLLATION` check, the repair `ALTER TABLE`, and warns never to use `ALTER TABLE … CONVERT TO CHARACTER SET`, which would rewrite `tenant_key` and `slug` out of their binary collation. No code change. ## [2.2.0] - 2026-11-22 diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md index c01217c..bd03f8e 100644 --- a/docs/UPGRADING.md +++ b/docs/UPGRADING.md @@ -129,18 +129,20 @@ php bin/console doctrine:migrations:migrate yourself, and keep it when you compare against the diff: ```sql - -- MySQL 8.0.17+ (MariaDB: COLLATE `utf8mb4_nopad_bin`; older MySQL: `utf8mb4_bin`, in the columns and in the table default) - CREATE TABLE workflow_definition_sequence (tenant_key VARCHAR(128) CHARACTER SET utf8mb4 NOT NULL COLLATE `utf8mb4_0900_bin`, slug VARCHAR(128) CHARACTER SET utf8mb4 NOT NULL COLLATE `utf8mb4_0900_bin`, last_version INT NOT NULL, PRIMARY KEY (tenant_key, slug)) DEFAULT CHARACTER SET utf8mb4 COLLATE `utf8mb4_0900_bin`; + -- MySQL 8.0.17+ (MariaDB: the key columns take COLLATE `utf8mb4_nopad_bin`; older MySQL: `utf8mb4_bin`). + -- The trailing table default is NOT the key collation: use your database's uniform collation (`utf8mb4_unicode_ci` here). + CREATE TABLE workflow_definition_sequence (tenant_key VARCHAR(128) CHARACTER SET utf8mb4 NOT NULL COLLATE `utf8mb4_0900_bin`, slug VARCHAR(128) CHARACTER SET utf8mb4 NOT NULL COLLATE `utf8mb4_0900_bin`, last_version INT NOT NULL, PRIMARY KEY (tenant_key, slug)) DEFAULT CHARACTER SET utf8mb4 COLLATE `utf8mb4_unicode_ci`; -- PostgreSQL (no table-level collation there, nothing to add) CREATE TABLE workflow_definition_sequence (tenant_key VARCHAR(128) NOT NULL, slug VARCHAR(128) NOT NULL, last_version INT NOT NULL, PRIMARY KEY (tenant_key, slug)); ``` - **Set the table default once, in the host (recommended).** The table's default collation matters for *future* - columns, not for the two that exist (those carry their own `COLLATE`). A text column added later without an explicit - `COLLATE` inherits the table default, and when that is the server's accent- and case-insensitive one (typically - `utf8mb4_0900_ai_ci`) a join against `tenant_key` or `slug` fails with MySQL error 1267 (illegal mix of collations), - long after and far from the change that caused it. Doctrine builds every table from `default_table_options`, so the - host should configure it once instead of patching each table: + columns, not for the two that exist (those carry their own binary `COLLATE`). A text column added later without an + explicit `COLLATE` inherits the table default; when that is the server's own default (typically + `utf8mb4_0900_ai_ci`) instead of the database's uniform collation, the column no longer matches the rest of the + database and a join against it fails with MySQL error 1267 (illegal mix of collations), long after and far from the + change that caused it. Doctrine builds every table from `default_table_options`, so the host should configure it + once instead of patching each table: ```yaml # config/packages/doctrine.yaml @@ -148,15 +150,19 @@ php bin/console doctrine:migrations:migrate dbal: default_table_options: charset: utf8mb4 - collation: utf8mb4_0900_bin # MariaDB: utf8mb4_nopad_bin; older MySQL: utf8mb4_bin + collation: utf8mb4_unicode_ci # the database's uniform collation, NOT the exact-key one ``` - With that, `doctrine:schema:update --dump-sql`, `doctrine:migrations:diff` and `nowo:workflow:sync-schema` emit the - `DEFAULT CHARACTER SET … COLLATE` clause on their own, for this table and every other one, and nothing has to be - remembered per table. Use the one binary collation your application already uses uniformly. Without the setting those - routes create the table with the server's default. + **This is the database's uniform collation, not the binary one.** The exact-key columns (`tenant_key`, `slug`) are + declared separately and are binary NO PAD precisely because the database default is not; putting a binary collation + here would make every new table binary, break the uniform-collation check (`check-collations`, + `collation_check.expected_collation`), change how ordinary text (names, titles) compares, and leave the exact-key + columns indistinguishable from the rest. With the setting, `doctrine:schema:update --dump-sql`, + `doctrine:migrations:diff` and `nowo:workflow:sync-schema` emit the `DEFAULT CHARACTER SET … COLLATE` clause on their + own, for this table and every other one. Without it those routes create the table with the server's default. - **Why the statement above carries the clause anyway.** A host that has not configured `default_table_options`, or that - runs the `CREATE TABLE` by hand, needs it written out; keeping it does no harm to a host that has configured it. + runs the `CREATE TABLE` by hand, needs it written out (with its own uniform collation in place of + `utf8mb4_unicode_ci`); keeping it does no harm to a host that has configured it. `nowo:workflow:sync-schema` is the worst case without the setting: it executes the DDL itself, so there is no statement to read and correct, and the only remedy left is the repair `ALTER TABLE` below. - **Check the table, not its columns.** The clause cannot be verified by looking at the new table's columns: every @@ -168,12 +174,13 @@ php bin/console doctrine:migrations:migrate WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'workflow_definition_sequence'; ``` - Expected: `utf8mb4_0900_bin` (MySQL 8.0.17+), `utf8mb4_nopad_bin` (MariaDB), `utf8mb4_bin` (older MySQL). Anything - ending in `_ai_ci` means the table needs the repair. + Expected: your database's uniform collation (not `utf8mb4_0900_bin`: the binary collation is checked per column, by + the exact-key check). A different value, typically the server default `utf8mb4_0900_ai_ci`, means the table needs the + repair. - **Repairing a table created without it.** Run - `ALTER TABLE workflow_definition_sequence DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin;` (MariaDB: - `utf8mb4_nopad_bin`; older MySQL: `utf8mb4_bin`). It changes only the default for columns added from now on. **Never - use `ALTER TABLE … CONVERT TO CHARACTER SET …` for this:** `CONVERT TO` rewrites every column, which would move + `ALTER TABLE workflow_definition_sequence DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;` (with your + database's uniform collation). It changes only the default for columns added from now on. **Never use + `ALTER TABLE … CONVERT TO CHARACTER SET …` for this:** `CONVERT TO` rewrites every column, which would move `tenant_key` and `slug` out of their binary collation and start folding look-alike tenant keys, the exact failure REQ-SEC-006 exists to prevent. From b504436d58e2a207f043f44aa1bd02ed4d429749 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9ctor=20Franco?= Date: Sun, 22 Nov 2026 22:21:48 +0100 Subject: [PATCH 7/7] docs(upgrading): state what default_table_options buys and what it does not --- docs/CHANGELOG.md | 2 +- docs/UPGRADING.md | 38 ++++++++++++++++++++++++-------------- 2 files changed, 25 insertions(+), 15 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 463047d..951e5b1 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -68,7 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed -- **Documentation: the `workflow_definition_sequence` `CREATE TABLE` in UPGRADING ("To 2.2.0") now sets the table's default collation to the database's uniform collation** (`DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci`, not the binary key collation), and recommends setting `doctrine.dbal.default_table_options` once in the host, since Doctrine's schema routes (`doctrine:schema:update --dump-sql`, `doctrine:migrations:diff`, `nowo:workflow:sync-schema`) emit the clause only then. Without it a column added later without an explicit `COLLATE` inherits the server default and fails joins with MySQL error 1267. UPGRADING also gives the `information_schema.TABLES.TABLE_COLLATION` check, the repair `ALTER TABLE`, and warns never to use `ALTER TABLE … CONVERT TO CHARACTER SET`, which would rewrite `tenant_key` and `slug` out of their binary collation. No code change. +- **Documentation: the `workflow_definition_sequence` `CREATE TABLE` in UPGRADING ("To 2.2.0") now sets the table's default collation to the database's uniform collation** (`DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci`, not the binary key collation), and recommends setting `doctrine.dbal.default_table_options` once in the host, since Doctrine's schema routes (`doctrine:schema:update --dump-sql`, `doctrine:migrations:diff`, `nowo:workflow:sync-schema`) emit the clause only then. The page states what that buys (new tables follow the uniform collation; no more 1267 between ordinary text columns) and what it does not (it does not stop a new column from folding case and accents, nor a 1267 against a binary key column; only declaring the column as an exact key does). UPGRADING also gives the `information_schema.TABLES.TABLE_COLLATION` check, the repair `ALTER TABLE`, and warns never to use `ALTER TABLE … CONVERT TO CHARACTER SET`, which would rewrite `tenant_key` and `slug` out of their binary collation. No code change. ## [2.2.0] - 2026-11-22 diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md index bd03f8e..7b2c7f9 100644 --- a/docs/UPGRADING.md +++ b/docs/UPGRADING.md @@ -136,13 +136,10 @@ php bin/console doctrine:migrations:migrate CREATE TABLE workflow_definition_sequence (tenant_key VARCHAR(128) NOT NULL, slug VARCHAR(128) NOT NULL, last_version INT NOT NULL, PRIMARY KEY (tenant_key, slug)); ``` -- **Set the table default once, in the host (recommended).** The table's default collation matters for *future* - columns, not for the two that exist (those carry their own binary `COLLATE`). A text column added later without an - explicit `COLLATE` inherits the table default; when that is the server's own default (typically - `utf8mb4_0900_ai_ci`) instead of the database's uniform collation, the column no longer matches the rest of the - database and a join against it fails with MySQL error 1267 (illegal mix of collations), long after and far from the - change that caused it. Doctrine builds every table from `default_table_options`, so the host should configure it - once instead of patching each table: +- **Set the table default once, in the host (recommended).** The table's default collation applies to *future* + columns, not to the two that exist (those carry their own binary `COLLATE`). A text column added later without an + explicit `COLLATE` inherits the table default. Doctrine builds every table from `default_table_options`, so the host + should configure it once instead of patching each table: ```yaml # config/packages/doctrine.yaml @@ -153,13 +150,26 @@ php bin/console doctrine:migrations:migrate collation: utf8mb4_unicode_ci # the database's uniform collation, NOT the exact-key one ``` - **This is the database's uniform collation, not the binary one.** The exact-key columns (`tenant_key`, `slug`) are - declared separately and are binary NO PAD precisely because the database default is not; putting a binary collation - here would make every new table binary, break the uniform-collation check (`check-collations`, - `collation_check.expected_collation`), change how ordinary text (names, titles) compares, and leave the exact-key - columns indistinguishable from the rest. With the setting, `doctrine:schema:update --dump-sql`, - `doctrine:migrations:diff` and `nowo:workflow:sync-schema` emit the `DEFAULT CHARACTER SET … COLLATE` clause on their - own, for this table and every other one. Without it those routes create the table with the server's default. + **This is the database's uniform collation (the example is `utf8mb4_unicode_ci`; use your own), not the binary + one.** The exact-key columns (`tenant_key`, `slug`) are declared separately and are binary NO PAD precisely because + the database default is not; putting a binary collation here would make every new table binary, break the + uniform-collation check (`check-collations`, `collation_check.expected_collation`), change how ordinary text (names, + titles) compares, and leave the exact-key columns indistinguishable from the rest. With the setting, + `doctrine:schema:update --dump-sql`, `doctrine:migrations:diff` and `nowo:workflow:sync-schema` emit the + `DEFAULT CHARACTER SET … COLLATE` clause on their own, for this table and every other one. Without it those routes + create the table with the server's default. + + **What the setting buys:** every new table follows the database's declared uniform collation, so the uniformity + check passes, behaviour is predictable, and two ordinary text columns can no longer end up on different collations + (MySQL error 1267 between them) depending on how each table was created. + + **What it does not buy:** it does not stop a new column from folding case and accents (a uniform collation is + case- and accent-insensitive, exactly like the server default), and it does not prevent error 1267 when such a column + is joined against `tenant_key` or `slug`. The only protection against folding is to declare the column as an exact + key with the binary NO PAD collation, which is what REQ-SEC-006 asks for and what the exact-key check verifies per + column. With the setting there is a single possible reason for that 1267, and it is informative: an ordinary column + was joined against an exact key and should probably have been declared as one. Without the setting the same error + also appears because tables disagree with each other, and the two causes cannot be told apart. - **Why the statement above carries the clause anyway.** A host that has not configured `default_table_options`, or that runs the `CREATE TABLE` by hand, needs it written out (with its own uniform collation in place of `utf8mb4_unicode_ci`); keeping it does no harm to a host that has configured it.