# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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