perf(test): activate schema-dump fast path (WS-6)

mysql-client is now installed on the dev host (brew install
mysql-client + PATH=/opt/homebrew/opt/mysql-client/bin), which
unblocks the fast path that session 2.7 prepared but couldn't
activate.

Changes:
- api/database/schema/mysql-schema.sql committed (current state, 122 KB,
  1749 lines, all 155 migration records).
- api/database/schema/.gitignore removed: the dump is no longer opt-in,
  it's the default code path (active in dev + CI).
- Makefile schema-dump target simplified: drops the docker exec mysqldump
  workaround in favour of plain `php artisan schema:dump`. Now also runs
  migrate to head first so the dump always reflects the latest migration
  set without manual prep.
- CLAUDE.md "Schema dumps" rewritten: "opt-in fast path" → "CI fast
  path", reflects that the dump is committed by default and contributors
  regenerate via `make schema-dump` after adding migrations.

Backfill test wall-time, 4 classes combined:
- Session 2.7 baseline: 127.90s
- This session:          27.55s (78% reduction)

Per class (PHPUnit Duration):
- FormFieldBindingMigrationTest:        4.59s  (2 tests)
- ConditionalLogicBackfillTest:         5.45s  (4 tests)
- FormFieldOptionsBackfillTest:        12.25s  (9 tests)
- FormFieldValidationRuleBackfillTest: 10.75s  (6 tests)

Full suite knock-on: 209.95s → 89.16s (-57%) — every RefreshDatabase
test pays the up-front migrate cost, which `schema:dump` collapses
from ~6s × N to a single ~1s SQL load.

Refs: WS-6 session 2.7 deviation #3 cleanup, Q1 closure

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-04-28 15:12:43 +02:00
parent a24fa18982
commit 6dec619e5b
4 changed files with 1790 additions and 43 deletions

View File

@@ -108,33 +108,41 @@ Other database rules:
- Create migrations in dependency order: foundation first, then dependent tables
- Always add composite indexes as documented in the design document (section 3.5)
### Schema dumps (opt-in fast path)
### Schema dumps (CI fast path)
Laravel supports `database/schema/{driver}-schema.sql` as a fast-path
baseline that `migrate:fresh` loads in one statement instead of replaying
every migration. For Crewli's backfill / migration tests (which call
`migrate:fresh` per test), this can yield a meaningful speedup —
**when the host has the `mysql` and `mysqldump` CLI tools available.**
Laravel uses `database/schema/{driver}-schema.sql` as a fast-path
baseline that `migrate:fresh` loads in one statement (~1s) instead of
replaying every migration (~6s × N migrations). For Crewli's backfill
/ migration tests that call `migrate:fresh` per test, this drops the
4 backfill-test classes from ~128s to ~28s combined (78% reduction).
Workflow:
The dump is **committed** at `api/database/schema/mysql-schema.sql`
and is the default code path. CI loads it automatically via
`migrate:fresh`.
1. Install MySQL client tools on host (one-time):
```bash
brew install mysql-client
echo 'export PATH="/opt/homebrew/opt/mysql-client/bin:$PATH"' >> ~/.zshrc
```
2. Bring `crewli_test` to head: `DB_DATABASE=crewli_test php artisan migrate --force`
3. Generate the dump: `make schema-dump`
4. Commit `api/database/schema/mysql-schema.sql` alongside any new migrations.
**One-time host setup** (required for both generating and loading
the dump):
The schema dump is **NOT committed by default** because Laravel's
auto-load path shells out to the `mysql` CLI; on hosts without it,
the presence of the dump file actively breaks `migrate` / `migrate:fresh`
(load fails, exit 127). Treat the dump as opt-in per dev environment.
```bash
brew install mysql-client
echo 'export PATH="/opt/homebrew/opt/mysql-client/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
`make schema-dump` runs `mysqldump` inside the `bm_mysql` Docker
container, so contributors don't need `mysqldump` on the host to
**generate** the dump — only to **load** it via Laravel's auto-detection.
Verify with `which mysql && which mysqldump`. Both must resolve to a
real binary; Laravel's `schema:dump` and `migrate:fresh` schema-load
both shell out to these.
**After adding a new migration:**
```bash
make schema-dump
git add api/database/schema/mysql-schema.sql
```
`make schema-dump` brings `crewli_test` to head and runs
`php artisan schema:dump`. Commit the regenerated file in the same
PR as the migration.
`--prune` is NOT used: individual migration files stay readable in
`api/database/migrations/` for audit / rollback purposes.