# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

This is a database migration repository using Atlas for declarative schema management. The project manages MySQL database schema migrations using Atlas' declarative approach.

## Architecture

- **Declarative Schema Management**: Uses `schema.sql` as the single source of truth for database schema
- **Atlas**: Uses Atlas CLI for schema inspection and migration
- **Docker-based**: All operations run in Docker containers for consistency
- **Environment Configuration**: Supports both local development and production deployments

## Key Commands

### Local Development
```bash
# Export current database schema to schema.sql
./generate-migration.sh

# Run local testing (creates test database and applies migrations)
./test-local.sh
```

### Production Deployment
```bash
# Using Docker Compose (recommended)
cp .env.example .env
# Edit .env with production database credentials
docker-compose up db-migrate

# Using Docker directly
docker build -t db-migrate:latest .
docker run --rm -e DB_URL="mysql://user:password@host:3306/database" db-migrate:latest
```

## Configuration Files

- `atlas.hcl`: Atlas environment configuration (local and prod)
- `.env.local`: Local development settings (includes MySQL container name)
- `.env.example`: Production environment template
- `schema.sql`: Database schema definition (generated from local database)

## Environment Setup

The project uses two Atlas environments:
- **local**: Connects to local MySQL instance at `localhost:3306/kami`
- **prod**: Uses `DB_URL` environment variable for production database connection

Both environments use `atlas_dev` as the development database for Atlas operations.

## Migration Process

1. **Schema Development**: Make changes to local database
2. **Export Schema**: Run `./generate-migration.sh` to update `schema.sql`
3. **Local Testing**: Run `./test-local.sh` to verify migrations work
4. **Production Deployment**: Use Docker Compose or Docker run with production credentials

## Testing

The `test-local.sh` script performs a complete integration test:
1. Creates `atlas_dev` database for Atlas operations
2. Generates current schema from local database
3. Creates fresh `kami_test` database
4. Applies migrations to test database
5. Verifies migration results by listing tables

## Docker Configuration

- Base image: `arigaio/atlas:latest`
- Entry point: `/app/migrate.sh` (expects `DB_URL` environment variable)
- Built with Atlas CLI and migration scripts