UAT: Alembic migration file names do not reflect actual execution order — m4/m6/m7/m8 prefixes are misleading #3973

New issue

Open

opened 2026-04-06 08:06:16 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 08:06:16 +00:00

Owner

Metadata

Branch: fix/backlog-alembic-migration-naming-order
Commit Message: fix(db): rename alembic migration files to reflect actual execution order
Milestone: None (Backlog)
Parent Epic: #1020

Summary

The Alembic migration files in alembic/versions/ use version-prefixed names (m4_, m5_, m6_, m7_, m8_, m9_) that imply a chronological execution order, but the actual execution order (determined by down_revision chains) is significantly different. This creates serious developer confusion when reading the migration history.

Backlog note: This issue was discovered during autonomous operation
on milestone v3.6.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Current Behavior

The actual execution order (via down_revision chains) contradicts the file name prefixes:

m7 runs BETWEEN m6_003 and m6_004: m7_001_repo_indexing_tables has down_revision = "m6_003_async_jobs_table", and m6_004_resource_type_inherits has down_revision = "m7_001_repo_indexing_tables". So the actual order is: m6_003 → m7_001 → m6_004. A migration named "m7" runs before migrations named "m6_004" and "m6_005".
m4_003 depends on m6_005: m4_003_plan_env_columns has down_revision = "m6_005_profile_guards_json". So m4_003 runs AFTER m6_005. A migration named "m4" runs after migrations named "m6".
m6_006 depends on m8_002: m6_006_estimation_report_json has down_revision = "m8_002_merge_profile_rename_and_corrections". So m6_006 runs AFTER m8_002. A migration named "m6" runs after migrations named "m8".

The actual execution order for the tail of the chain is:

... → m6_003 → m7_001 → m6_004 → m6_005 → m4_003 → [m5_001, m8_001_align, m8_001_correction] → m8_002 → m6_006 → m9_001

This means:

m4_003 runs after m6_005 (m4 after m6)
m7_001 runs before m6_004 (m7 before m6)
m6_006 runs after m8_002 (m6 after m8)

Expected Behavior

Migration file names should reflect their actual execution order, or at minimum, the naming convention should be consistent and not misleading.

Code Locations

alembic/versions/m4_003_plan_env_columns.py: down_revision = "m6_005_profile_guards_json" (m4 depends on m6)
alembic/versions/m6_004_resource_type_inherits.py: down_revision = "m7_001_repo_indexing_tables" (m6 depends on m7)
alembic/versions/m6_006_estimation_report_json.py: down_revision = "m8_002_merge_profile_rename_and_corrections" (m6 depends on m8)

Impact

Developers reading the migration history will be confused about the actual schema evolution order.
When generating new migrations, developers may choose misleading names based on the prefix convention.
Code reviews become harder because the file names don't reflect the actual dependency chain.
The agents db history command output will show migrations in an order that doesn't match the file name prefixes.

Note: The migrations themselves are functionally correct — the down_revision chains are valid and Alembic will execute them in the correct order. This is a naming/documentation issue, not a runtime failure.

Proposed Fix

Option A (Preferred): Rename the migration files to use a sequential numbering scheme that matches their actual execution order (e.g., using timestamps or sequential integers). This requires updating the revision IDs within each file.

Option B: Add a comment at the top of each affected migration file explaining why the name doesn't match the execution order, and add a MIGRATION_ORDER.md document in the alembic/versions/ directory that shows the actual execution order.

Subtasks

Audit all down_revision chains in alembic/versions/ to produce the definitive execution order
Choose fix approach (Option A: rename files, or Option B: add documentation)
If Option A: rename all affected migration files and update revision/down_revision IDs within each file
If Option B: add MIGRATION_ORDER.md to alembic/versions/ and add clarifying comments to affected files
Verify alembic upgrade head still works correctly after changes
Update any developer documentation that references migration file names

Definition of Done

All down_revision chains audited and documented
Migration file names are no longer misleading (either renamed or documented)
alembic upgrade head and alembic downgrade base execute without errors
agents db history output is consistent with file names or clearly documented
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/backlog-alembic-migration-naming-order` - **Commit Message**: `fix(db): rename alembic migration files to reflect actual execution order` - **Milestone**: None (Backlog) - **Parent Epic**: #1020 ## Summary The Alembic migration files in `alembic/versions/` use version-prefixed names (`m4_`, `m5_`, `m6_`, `m7_`, `m8_`, `m9_`) that imply a chronological execution order, but the actual execution order (determined by `down_revision` chains) is significantly different. This creates serious developer confusion when reading the migration history. > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Current Behavior The actual execution order (via `down_revision` chains) contradicts the file name prefixes: 1. **m7 runs BETWEEN m6_003 and m6_004**: `m7_001_repo_indexing_tables` has `down_revision = "m6_003_async_jobs_table"`, and `m6_004_resource_type_inherits` has `down_revision = "m7_001_repo_indexing_tables"`. So the actual order is: `m6_003 → m7_001 → m6_004`. A migration named "m7" runs before migrations named "m6_004" and "m6_005". 2. **m4_003 depends on m6_005**: `m4_003_plan_env_columns` has `down_revision = "m6_005_profile_guards_json"`. So m4_003 runs AFTER m6_005. A migration named "m4" runs after migrations named "m6". 3. **m6_006 depends on m8_002**: `m6_006_estimation_report_json` has `down_revision = "m8_002_merge_profile_rename_and_corrections"`. So m6_006 runs AFTER m8_002. A migration named "m6" runs after migrations named "m8". The actual execution order for the tail of the chain is: ``` ... → m6_003 → m7_001 → m6_004 → m6_005 → m4_003 → [m5_001, m8_001_align, m8_001_correction] → m8_002 → m6_006 → m9_001 ``` This means: - `m4_003` runs after `m6_005` (m4 after m6) - `m7_001` runs before `m6_004` (m7 before m6) - `m6_006` runs after `m8_002` (m6 after m8) ## Expected Behavior Migration file names should reflect their actual execution order, or at minimum, the naming convention should be consistent and not misleading. ## Code Locations - `alembic/versions/m4_003_plan_env_columns.py`: `down_revision = "m6_005_profile_guards_json"` (m4 depends on m6) - `alembic/versions/m6_004_resource_type_inherits.py`: `down_revision = "m7_001_repo_indexing_tables"` (m6 depends on m7) - `alembic/versions/m6_006_estimation_report_json.py`: `down_revision = "m8_002_merge_profile_rename_and_corrections"` (m6 depends on m8) ## Impact 1. Developers reading the migration history will be confused about the actual schema evolution order. 2. When generating new migrations, developers may choose misleading names based on the prefix convention. 3. Code reviews become harder because the file names don't reflect the actual dependency chain. 4. The `agents db history` command output will show migrations in an order that doesn't match the file name prefixes. **Note**: The migrations themselves are functionally correct — the `down_revision` chains are valid and Alembic will execute them in the correct order. This is a naming/documentation issue, not a runtime failure. ## Proposed Fix **Option A (Preferred)**: Rename the migration files to use a sequential numbering scheme that matches their actual execution order (e.g., using timestamps or sequential integers). This requires updating the `revision` IDs within each file. **Option B**: Add a comment at the top of each affected migration file explaining why the name doesn't match the execution order, and add a `MIGRATION_ORDER.md` document in the `alembic/versions/` directory that shows the actual execution order. ## Subtasks - [ ] Audit all `down_revision` chains in `alembic/versions/` to produce the definitive execution order - [ ] Choose fix approach (Option A: rename files, or Option B: add documentation) - [ ] If Option A: rename all affected migration files and update `revision`/`down_revision` IDs within each file - [ ] If Option B: add `MIGRATION_ORDER.md` to `alembic/versions/` and add clarifying comments to affected files - [ ] Verify `alembic upgrade head` still works correctly after changes - [ ] Update any developer documentation that references migration file names ## Definition of Done - [ ] All `down_revision` chains audited and documented - [ ] Migration file names are no longer misleading (either renamed or documented) - [ ] `alembic upgrade head` and `alembic downgrade base` execute without errors - [ ] `agents db history` output is consistent with file names or clearly documented - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 08:06:45 +00:00

#1020 [Epic] Database resource hierarchy restructuring

freemo referenced this issue

2026-04-06 08:10:36 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 08:33:59 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775