sojorn/migrations

Database Migrations & SQL Scripts

This directory contains all SQL scripts organized by purpose and category.

📁 Directory Structure

🗄️ database/

Core database schema changes and migration scripts that modify the database structure.

Files:

• create_verification_tokens.sql - Creates email verification tokens table
• fix_constraint.sql - Fixes database constraint syntax errors
• update_user_status.sql - Updates user status enum with new moderation states

Usage:

# Apply database migrations
psql -d postgres -f migrations/database/create_verification_tokens.sql

---

🧪 tests/

Test scripts, verification queries, and diagnostic SQL used for testing and debugging.

Files:

• check_*.sql - Various database inspection queries
• test_*.sql - Test scripts for features
• count_*.sql - Count queries for verification
• verify_*.sql - Verification scripts
• final_*.sql - Final system tests

Usage:

# Run verification tests
psql -d postgres -f migrations/tests/check_tables.sql
psql -d postgres -f migrations/tests/test_moderation_integration.sql

---

🎨 directus/

Directus CMS configuration, collections, permissions, and UI setup scripts.

Files:

• add_directus_*.sql - Directus collections and fields
• fix_directus_*.sql - Directus configuration fixes
• use_existing_policy.sql - Directus policy setup
• fix_permissions_correct.sql - Permission fixes

Usage:

# Setup Directus collections
psql -d postgres -f migrations/directus/add_directus_collections.sql

---

🔧 fixes/

Database fixes, patches, and repair scripts for specific issues.

Files:

• fix_collections_complete.sql - Complete Directus collections fix
• grant_permissions.sql - Database permission grants

Usage:

# Apply database fixes
psql -d postgres -f migrations/fixes/fix_collections_complete.sql

---

📦 archive/

Historical scripts, temporary queries, and deprecated SQL files.

Files:

• All historical migration scripts
• Temporary diagnostic queries
• Deprecated or one-time scripts
• Original migrations_archive content

Usage:

# Archive scripts - for reference only
# Generally should not be run on production

---

🚀 Official Migrations

The official Go backend migrations are located in:

go-backend/internal/database/migrations/

These are timestamped migrations that are automatically applied by the Go application.

Current Official Migrations:

• 20260205000002_user_appeal_system_fixed.up.sql - User appeal system
• 20260205000003_add_email_preferences.up.sql - Email preferences

📋 Usage Guidelines

🔴 Production

• Only use scripts from database/ and official Go migrations
• Test thoroughly in staging first
• Always backup before applying

🟡 Staging

• Can use tests/ and directus/ scripts
• Verify functionality before production

🟢 Development

• All scripts available for testing
• Use archive/ for reference and experimentation

⚠️ Important Notes

• Always review scripts before running
• Check for dependencies between scripts
• Some scripts may be one-time use only
• Archive scripts may be outdated

---

🔄 Migration Order

For new deployments, follow this order:

1. Database Schema (database/)
2. Directus Setup (directus/)
3. Apply Fixes (fixes/)
4. Run Tests (tests/)
5. Official Go Migrations (auto-applied)

---

📝 Adding New Scripts

When adding new SQL scripts:

1. Choose appropriate folder based on purpose
2. Use descriptive naming with date/prefix
3. Add comments explaining purpose
4. Test thoroughly before committing
5. Update this README if adding new categories

Naming Convention:

• YYYY-MM-DD_description.sql for migrations
• check_feature.sql for verification scripts
• test_feature.sql for test scripts
• fix_issue.sql for fix scripts

---

🛠️ Maintenance

• Review archive quarterly - remove outdated scripts
• Update documentation - keep README current
• Test migrations - ensure they work with current schema
• Backup before changes - always backup production data

Last Updated: 2026-02-05 Maintainer: Development Team