crypto_trader/docs/architecture/database_schema.md

Database Schema

This document describes the database schema for Crypto Trader.

Database Options

• SQLite: Default, bundled, zero configuration
• PostgreSQL: Optional, for advanced users with large datasets

Core Tables

Exchanges

Stores exchange configuration and credentials.

CREATE TABLE exchanges (
    id INTEGER PRIMARY KEY,
    name TEXT UNIQUE NOT NULL,
    api_key TEXT,  -- Encrypted
    secret_key TEXT,  -- Encrypted
    password TEXT,  -- Encrypted (for some exchanges)
    api_permissions TEXT DEFAULT 'read_only',
    is_enabled BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP
);

Strategies

Stores trading strategy configuration.

CREATE TABLE strategies (
    id INTEGER PRIMARY KEY,
    name TEXT UNIQUE NOT NULL,
    description TEXT,
    strategy_type TEXT NOT NULL,
    parameters TEXT,  -- JSON
    is_enabled BOOLEAN DEFAULT FALSE,
    is_paper_trading BOOLEAN DEFAULT TRUE,
    exchange_id INTEGER REFERENCES exchanges(id),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP
);

Trades

Stores executed trades.

CREATE TABLE trades (
    id INTEGER PRIMARY KEY,
    order_id TEXT UNIQUE NOT NULL,
    symbol TEXT NOT NULL,
    side TEXT NOT NULL,  -- 'buy' or 'sell'
    type TEXT NOT NULL,  -- 'market', 'limit', etc.
    price REAL,
    amount REAL,
    cost REAL,
    fee REAL DEFAULT 0.0,
    status TEXT DEFAULT 'open',
    is_paper_trade BOOLEAN DEFAULT TRUE,
    executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    exchange_id INTEGER REFERENCES exchanges(id),
    strategy_id INTEGER REFERENCES strategies(id)
);

Positions

Stores open and closed positions.

CREATE TABLE positions (
    id INTEGER PRIMARY KEY,
    symbol TEXT NOT NULL,
    exchange_id INTEGER REFERENCES exchanges(id),
    quantity REAL NOT NULL,
    entry_price REAL NOT NULL,
    current_price REAL,
    unrealized_pnl REAL,
    realized_pnl REAL,
    is_open BOOLEAN DEFAULT TRUE,
    position_type TEXT DEFAULT 'spot',  -- 'spot', 'futures', 'margin'
    leverage REAL DEFAULT 1.0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP,
    UNIQUE(symbol, exchange_id, position_type)
);

Orders

Stores order history and status.

CREATE TABLE orders (
    id INTEGER PRIMARY KEY,
    exchange_order_id TEXT UNIQUE NOT NULL,
    client_order_id TEXT,
    symbol TEXT NOT NULL,
    side TEXT NOT NULL,
    type TEXT NOT NULL,
    price REAL,
    amount REAL,
    filled_amount REAL DEFAULT 0.0,
    remaining_amount REAL DEFAULT 0.0,
    cost REAL DEFAULT 0.0,
    status TEXT DEFAULT 'pending',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP,
    exchange_id INTEGER REFERENCES exchanges(id),
    strategy_id INTEGER REFERENCES strategies(id),
    is_paper_trade BOOLEAN DEFAULT TRUE
);

Market Data

Stores historical OHLCV data.

CREATE TABLE market_data (
    id INTEGER PRIMARY KEY,
    symbol TEXT NOT NULL,
    timeframe TEXT NOT NULL,
    timestamp TIMESTAMP NOT NULL,
    open REAL NOT NULL,
    high REAL NOT NULL,
    low REAL NOT NULL,
    close REAL NOT NULL,
    volume REAL NOT NULL,
    exchange_id INTEGER REFERENCES exchanges(id),
    UNIQUE(symbol, timeframe, timestamp)
);

Portfolio Snapshots

Stores portfolio snapshots over time.

CREATE TABLE portfolio_snapshots (
    id INTEGER PRIMARY KEY,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    total_value REAL NOT NULL,
    cash_balance REAL NOT NULL,
    asset_holdings TEXT,  -- JSON
    exchange_id INTEGER REFERENCES exchanges(id)
);

Backtest Results

Stores backtesting results.

CREATE TABLE backtest_results (
    id INTEGER PRIMARY KEY,
    strategy_id INTEGER REFERENCES strategies(id),
    start_date TIMESTAMP NOT NULL,
    end_date TIMESTAMP NOT NULL,
    initial_capital REAL NOT NULL,
    final_capital REAL NOT NULL,
    total_return REAL NOT NULL,
    sharpe_ratio REAL,
    sortino_ratio REAL,
    max_drawdown REAL,
    win_rate REAL,
    other_metrics TEXT,  -- JSON
    run_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Risk Limits

Stores risk management limits.

CREATE TABLE risk_limits (
    id INTEGER PRIMARY KEY,
    strategy_id INTEGER REFERENCES strategies(id),
    exchange_id INTEGER REFERENCES exchanges(id),
    limit_type TEXT NOT NULL,
    value REAL NOT NULL,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP
);

Alerts

Stores alert configurations.

CREATE TABLE alerts (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    alert_type TEXT NOT NULL,
    condition TEXT NOT NULL,
    is_active BOOLEAN DEFAULT TRUE,
    triggered_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Rebalancing Events

Stores portfolio rebalancing history.

CREATE TABLE rebalancing_events (
    id INTEGER PRIMARY KEY,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    exchange_id INTEGER REFERENCES exchanges(id),
    old_allocations TEXT,  -- JSON
    new_allocations TEXT,  -- JSON
    executed_trades TEXT,  -- JSON
    status TEXT DEFAULT 'completed'
);

App State

Stores application state for recovery.

CREATE TABLE app_state (
    id INTEGER PRIMARY KEY,
    key TEXT UNIQUE NOT NULL,
    value TEXT,  -- JSON
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Audit Log

Stores security audit events.

CREATE TABLE audit_log (
    id INTEGER PRIMARY KEY,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    event_type TEXT NOT NULL,
    user_id TEXT,
    details TEXT  -- JSON
);

Indexes

Key indexes for performance:

• market_data(symbol, timeframe, timestamp) - Unique index
• trades(symbol, executed_at) - For trade queries
• positions(symbol, exchange_id, is_open) - For position lookups
• orders(status, created_at) - For order management
• strategies(is_enabled) - For active strategy queries

Relationships

• Exchanges → Strategies (one-to-many)
• Exchanges → Trades (one-to-many)
• Strategies → Trades (one-to-many)
• Strategies → Backtest Results (one-to-many)
• Exchanges → Positions (one-to-many)
• Exchanges → Market Data (one-to-many)

Data Retention

Configurable retention policies:

• Market Data: Configurable (default: 1 year)
• Trades: Permanent
• Orders: Permanent
• Portfolio Snapshots: Configurable (default: 1 year)
• Logs: Configurable (default: 30 days)

Backup and Recovery

• Automatic Backups: Before critical operations
• Manual Backups: Via export functionality
• Recovery: From backup files or database dumps