Skip to content
4 changes: 4 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 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

### Changed
Expand Down
71 changes: 66 additions & 5 deletions docs/UPGRADING.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,16 +123,77 @@ 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
`<prefix>definition_sequence`):
- **The table.** What to run, without a table prefix (with `nowo_workflow.table_prefix` the table is
`<prefix>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`)
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: 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 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
doctrine:
dbal:
default_table_options:
charset: utf8mb4
collation: utf8mb4_unicode_ci # the database's uniform collation, NOT the exact-key one
```

**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.
`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
WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'workflow_definition_sequence';
```

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_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.

- **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`):
Expand Down
Loading