voxblog/docs/DB_VARIABLE_MIGRATION.md

# Database Variable Migration Guide

## Overview

This project has been updated to use a **unified naming convention** for all database configuration variables. All database-related environment variables now use the `DB_*` prefix for consistency and simplicity.

## What Changed

### Before (Mixed Naming)
```bash
# .env file had:
MYSQL_ROOT_PASSWORD=...
MYSQL_PASSWORD=...

# docker-compose.yml used both:
MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
MYSQL_PASSWORD=${MYSQL_PASSWORD}
DATABASE_URL=mysql://voxblog:${MYSQL_PASSWORD}@mysql:3306/voxblog
DB_HOST=mysql
DB_PORT=3306
DB_USER=voxblog
DB_PASSWORD=${MYSQL_PASSWORD}
DB_NAME=voxblog
```

### After (Unified Naming)
```bash
# All variables use DB_* prefix:
DB_ROOT_PASSWORD=...
DB_PASSWORD=...
DB_USER=voxblog
DB_NAME=voxblog
DB_HOST=localhost  # or 'mysql' in docker
DB_PORT=3306
```

## Variable Reference

| Variable | Purpose | Default | Required |
|----------|---------|---------|----------|
| `DB_ROOT_PASSWORD` | MySQL root user password | - | Yes |
| `DB_PASSWORD` | Application database user password | - | Yes |
| `DB_USER` | Application database username | `voxblog` | No |
| `DB_NAME` | Application database name | `voxblog` | No |
| `DB_HOST` | Database host | `mysql` (docker) / `localhost` | No |
| `DB_PORT` | Database port | `3306` | No |

## Migration Steps

### For Existing Installations

1. **Backup your current `.env` file:**
   ```bash
   cp .env .env.backup
   ```

2. **Run the migration script:**
   ```bash
   chmod +x scripts/migrate-db-vars.sh
   ./scripts/migrate-db-vars.sh
   ```
   
   Or manually update your `.env` file:
   ```bash
   # Change these lines:
   MYSQL_ROOT_PASSWORD=your_password
   MYSQL_PASSWORD=your_password
   
   # To:
   DB_ROOT_PASSWORD=your_password
   DB_PASSWORD=your_password
   ```

3. **Restart your services:**
   ```bash
   docker-compose down
   docker-compose up -d
   ```

### For New Installations

Simply copy `.env.example` to `.env` and fill in your values:
```bash
cp .env.example .env
# Edit .env with your database passwords
```

## Benefits of Unified Naming

1. **Consistency**: All database variables follow the same `DB_*` pattern
2. **Clarity**: Clear separation between MySQL container config and application config
3. **Simplicity**: Easier to remember and less prone to typos
4. **Flexibility**: Default values allow for easier local development
5. **Maintainability**: Single source of truth for database configuration

## Code Usage

All application code uses the unified variables:

```typescript
// apps/api/src/db.ts
const host = process.env.DB_HOST || 'localhost';
const port = Number(process.env.DB_PORT || 3306);
const user = process.env.DB_USER || '';
const password = process.env.DB_PASSWORD || '';
const database = process.env.DB_NAME || '';
```

## Docker Compose Configuration

The MySQL container environment variables are mapped from `DB_*` to `MYSQL_*`:

```yaml
mysql:
  environment:
    MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    MYSQL_DATABASE: ${DB_NAME:-voxblog}
    MYSQL_USER: ${DB_USER:-voxblog}
    MYSQL_PASSWORD: ${DB_PASSWORD}
```

This maintains compatibility with the official MySQL Docker image while using our unified naming convention.

## Troubleshooting

### Services won't start after migration

1. Check that all required variables are set:
   ```bash
   grep "^DB_" .env
   ```

2. Verify docker-compose can read the variables:
   ```bash
   docker-compose config
   ```

3. Check container logs:
   ```bash
   docker-compose logs mysql
   docker-compose logs api
   ```

### Database connection errors

Ensure the `DB_PASSWORD` matches what was set when the MySQL container was first created. If you need to reset:

```bash
docker-compose down -v  # WARNING: This deletes your database!
docker-compose up -d
```

## CI/CD and Deployment

If you have CI/CD pipelines or deployment scripts, update them to use the new variable names:

- Replace `MYSQL_ROOT_PASSWORD` → `DB_ROOT_PASSWORD`
- Replace `MYSQL_PASSWORD` → `DB_PASSWORD`
- Remove `DATABASE_URL` (no longer needed)

## Questions?

If you encounter any issues during migration, please check:
1. All variables are correctly renamed in your `.env` file
2. No old `MYSQL_*` variables remain
3. Services have been restarted after the change