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)

# .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)

# 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:

   cp .env .env.backup
   

2. Run the migration script:

   chmod +x scripts/migrate-db-vars.sh
   ./scripts/migrate-db-vars.sh
   

   Or manually update your .env file:

   # 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:

   docker-compose down
   docker-compose up -d
   

For New Installations

Simply copy .env.example to .env and fill in your values:

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:

// 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_*:

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:

   grep "^DB_" .env
   

2. Verify docker-compose can read the variables:

   docker-compose config
   

3. Check container logs:

   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:

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