Skip to main content

​
Overview

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

​
Creating Migrations

# 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

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

cargo sqlx migrate run

​
Check Status

cargo sqlx migrate info
Output: 
20240115120000_create_users_table  Applied
20240115130000_create_wallets_table  Applied
20240115140000_create_transactions_table  Pending

​
Revert Last

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: 
-- migrations/20240115150000_add_wallet_icon.sql
BEGIN;

ALTER TABLE wallets
ADD COLUMN icon VARCHAR(50);

COMMIT;

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