Skip to content

🔄 Rename 'migrations' package to 'db' for better semantic clarity

Summary

The current packages/migrations directory name doesn't accurately reflect its broader purpose. It contains not just migrations, but comprehensive database tooling, tests, scripts, and utilities. Renaming to packages/db would better represent its role as the complete database management package.

Current Structure

packages/migrations/
├── afterReset.sql              # Post-reset seeding
├── dumps/                      # Schema dumps for CI validation  
├── migrations/                 # Graphile migrate files
├── scripts/                    # Database utility scripts
│   ├── tests/                 # Comprehensive test suites
│   ├── dump.sh                # Schema export utilities
│   ├── migrate.sh             # Migration helpers
│   ├── reset.sh               # Database reset
│   ├── seed.sh                # Data seeding
│   └── validate-schema.sh     # Schema validation
└── seeds/                     # Demo and development data

Proposed Structure

packages/db/
├── afterReset.sql
├── dumps/
├── migrations/
├── scripts/
│   └── tests/
└── seeds/

Required Changes

📁 File System Changes

  • Rename packages/migrations/ → packages/db/
  • Update all internal script references to new paths
  • Update relative paths in shell scripts

🔧 Configuration Updates

  • Update package.json workspace references
  • Update npm script paths in root package.json
  • Update Docker Compose volume mounts if any
  • Update .gitignore patterns if specific to migrations directory

🚀 CI/CD Pipeline Updates

  • Update .gitlab-ci.yml job paths:
    • test_schema job working directory
    • test_migrations job working directory
    • File change detection patterns
  • Update environment variables if hardcoded paths exist
  • Update artifact paths in CI jobs

📚 Documentation Updates

  • Update CLAUDE.md references
  • Update README.md if it references migrations path
  • Update any architecture documentation
  • Update setup instructions

🏗️ Build System Updates

  • Update any build scripts that reference the old path
  • Update dune files if they reference migrations directory
  • Update development setup documentation

🧪 Testing Updates

  • Update test scripts with new paths
  • Update CI test job configurations
  • Verify all test runners work with new structure
  • Update any hardcoded paths in SQL test files

Backward Compatibility Considerations

Breaking Changes

  • Any scripts that hardcode packages/migrations path will break
  • CI pipelines may need updates on other branches
  • Developer setup instructions will need updates

Migration Strategy

  1. Preparation: Update all references in a single commit
  2. Rename: Perform the actual directory rename
  3. Validation: Run full CI suite to ensure everything works
  4. Communication: Update setup documentation

Benefits

🎯 Semantic Clarity

  • db better describes the package's comprehensive database responsibilities
  • Reduces confusion about what the package contains
  • Aligns with common patterns (many projects have db/ directories)

🔧 Developer Experience

  • More intuitive directory name for new developers
  • Better reflects the package's role in the architecture
  • Cleaner conceptual model

📈 Future Scalability

  • Room for additional database tooling beyond just migrations
  • Better organization for database-related utilities
  • Clearer separation of concerns

Success Criteria

  • All CI pipelines pass after rename
  • All npm scripts work correctly
  • Database operations (migrate, reset, seed) function normally
  • Test suites pass without modification
  • Documentation accurately reflects new structure
  • No broken references in any scripts or configuration

Priority: Medium

This is primarily a developer experience improvement and doesn't affect functionality. Can be completed in a dedicated sprint focused on technical debt reduction.

Estimated Effort: 2-4 hours

  • 1 hour: Planning and identifying all references
  • 1 hour: Making the changes
  • 1-2 hours: Testing and validation
  • 30 minutes: Documentation updates

🤖 Generated with Claude Code