> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.ttr.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrations

> Database migration guide

## Overview

Zeus uses SQLx CLI for database migrations. Migrations are version-controlled and applied in order.

## Creating Migrations

```bash theme={null}
# Create new migration
cargo sqlx migrate add <name>

# Example
cargo sqlx migrate add create_users_table
```

This creates:

```
migrations/
└── 20240115120000_create_users_table.sql
```

## Migration File Format

```sql theme={null}
-- Up migration (apply)
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) NOT NULL UNIQUE,
    name VARCHAR(100) NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Down migration (revert)
-- (in separate file: 20240115120000_create_users_table.down.sql)
DROP TABLE users;
```

## Running Migrations

### Apply All

```bash theme={null}
cargo sqlx migrate run
```

### Check Status

```bash theme={null}
cargo sqlx migrate info
```

Output:

```
20240115120000_create_users_table  Applied
20240115130000_create_wallets_table  Applied
20240115140000_create_transactions_table  Pending
```

### Revert Last

```bash theme={null}
cargo sqlx migrate revert
```

## Migration Best Practices

1. **Never modify existing migrations** - Create new ones instead
2. **Make migrations reversible** - Always provide down.sql
3. **Test migrations** - Run on a copy of production data
4. **Keep migrations small** - One logical change per file
5. **Use transactions** - Wrap in BEGIN/COMMIT for safety

## Example Migration

Adding a new column:

```sql theme={null}
-- migrations/20240115150000_add_wallet_icon.sql
BEGIN;

ALTER TABLE wallets
ADD COLUMN icon VARCHAR(50);

COMMIT;
```

```sql theme={null}
-- migrations/20240115150000_add_wallet_icon.down.sql
BEGIN;

ALTER TABLE wallets
DROP COLUMN icon;

COMMIT;
```

## Migration Checklist

* [ ] Test on development database
* [ ] Ensure down migration works
* [ ] Check for data loss
* [ ] Update application code
* [ ] Document changes
* [ ] Backup production database