- architecture/: overview, technology stack, auth (OIDC + built-in IndieAuth), syndication (POSSE) rewritten; new database.md, deployment.md and indieweb-protocols.md; legacy stack marked historical - decisions/: reconstructed ADR-060 and ADR-063; 31 status corrections (superseded auth ADRs, proposed -> accepted); INDEX rebuilt - design/: reconstructed the v1.6.0 documents the webmention code cites; reports for 18 v2 releases without a design folder; INDEX rebuilt - projectplan/: BACKLOG rewritten (shipped items removed, open issues from the reviews added); RELEASE.md for v2.0.0-v2.10.1; INDEX - standards/: development setup (uv, tests, DEV_MODE), testing (CI test stage), git and release flow, versioning, coding standards, cookies - README, CLAUDE.md, .env.example (every setting the code reads, with defaults) brought up to date - 137 broken links repaired (old absolute paths, moved files); stale ADR references in code comments corrected (comments only) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.2 KiB
4.2 KiB
ADR-033: Database Migration System Redesign
Status
Accepted (implemented in v1.1.0; was: Proposed)
Context
The current migration system has a critical flaw: duplicate schema definitions exist between SCHEMA_SQL (used for fresh installs) and individual migration files. This violates the DRY principle and creates maintenance burden. When schema changes are made, developers must remember to update both locations, leading to potential inconsistencies.
Current problems:
- Duplicate schema definitions in SCHEMA_SQL and migration files
- Risk of schema drift between fresh installs and upgraded databases
- Maintenance overhead of keeping two schema sources in sync
- Confusion about which schema definition is authoritative
Decision
Implement an INITIAL_SCHEMA_SQL approach where:
- Single Source of Truth: The initial schema (v1.0.0 state) is defined once in INITIAL_SCHEMA_SQL
- Migration-Only Changes: All schema changes after v1.0.0 are defined only in migration files
- Fresh Install Path: New installations run INITIAL_SCHEMA_SQL + all migrations in sequence
- Upgrade Path: Existing installations only run new migrations from their current version
- Version Tracking: The migrations table continues to track applied migrations
- Lightweight System: Maintain custom migration system without heavyweight ORMs
Implementation approach:
# Conceptual flow (not actual code)
def initialize_database():
if is_fresh_install():
execute(INITIAL_SCHEMA_SQL) # v1.0.0 schema
mark_initial_version()
apply_pending_migrations() # Apply any migrations after v1.0.0
Rationale
This approach provides several benefits:
- DRY Compliance: Schema for any version is defined exactly once
- Clear History: Migration files form a clear changelog of schema evolution
- Reduced Errors: No risk of forgetting to update duplicate definitions
- Maintainability: Easier to understand what changed when
- Simplicity: Still lightweight, no heavy dependencies
- Compatibility: Works with existing migration infrastructure
Alternative approaches considered:
- SQLAlchemy/Alembic: Too heavyweight for a minimal CMS
- Django-style migrations: Requires ORM, adds complexity
- Status quo: Maintaining duplicate schemas is error-prone
- Single evolving schema file: Loses history of changes
Consequences
Positive
- Single source of truth for each schema state
- Clear separation between initial schema and evolution
- Easier onboarding for new developers
- Reduced maintenance burden
- Better documentation of schema evolution
Negative
- One-time migration to new system required
- Must carefully preserve v1.0.0 schema state in INITIAL_SCHEMA_SQL
- Fresh installs run more SQL statements (initial + migrations)
Implementation Requirements
- Extract current v1.0.0 schema to INITIAL_SCHEMA_SQL
- Remove schema definitions from existing migration files
- Update migration runner to handle initial schema
- Test both fresh install and upgrade paths thoroughly
- Document the new approach clearly
Alternatives Considered
Alternative 1: SQLAlchemy/Alembic
- Pros: Industry standard, automatic migration generation
- Cons: Heavy dependency, requires ORM adoption, against minimal philosophy
- Rejected because: Overkill for single-table schema
Alternative 2: Single Evolving Schema File
- Pros: Simple, one file to maintain
- Cons: No history, can't track changes, upgrade path unclear
- Rejected because: Loses important schema evolution history
Alternative 3: Status Quo (Duplicate Schemas)
- Pros: Already implemented, works currently
- Cons: DRY violation, error-prone, maintenance burden
- Rejected because: Technical debt will compound over time
Migration Plan
- Phase 1: Document exact v1.0.0 schema state
- Phase 2: Create INITIAL_SCHEMA_SQL from current state
- Phase 3: Refactor migration system to use new approach
- Phase 4: Test extensively with both paths
- Phase 5: Deploy in v1.1.0 with clear upgrade instructions
References
- ADR-032: Migration Requirements (parent decision)
- Issue: Database schema duplication
- Similar approach: Rails migrations with schema.rb