Skip to main content

🗄️ Database Operations

Hoox utilizes Cloudflare® D1—a fully serverless, highly optimized SQLite database engine distributed globally across Cloudflare’s edge network. This document serves as your operational runbook for executing database schemas, running schema migrations, querying transaction ledgers, and performing secure database backup and recovery.

🏗️ The Core Database Tables

The database schema defines five fundamental tables designed for trading operations, plus supporting indices for fast query performance:

Schema Details


⚡ Applying Schemas & Tables

When launching a new workspace, you must initialize the required tables. The Hoox CLI handles this via declarative migration scripts:

Migration Files Location

Migrations are stored in workers/d1-worker/src/drizzle/ and are automatically versioned:
Running hoox db apply compiles migrations and seeds the database locally. For production deployment, you must append the --remote flag to execute operations directly on your active Cloudflare D1 instance.

🔄 Managing Database Migrations

When new features are added that require changes to the database structure, you must run migrations:
The migration engine tracks history inside a special d1_migrations table, ensuring that migrations are never executed twice or applied in the wrong sequence.

Migration Best Practices

  1. Always write reversible migrations — include both UP and DOWN scripts.
  2. Never modify existing migrations — create new ones for schema changes.
  3. Test locally first — run hoox db apply without —remote to verify.
  4. Backup before migrating — export your production database first.

🔎 Querying Data from the CLI

The Hoox CLI features a built-in SQL interface allowing you to run arbitrary queries directly against your local or remote database:

Useful Query Templates


📥 Backup & Export Workflows

To secure your historical P&L records, transaction ledger, and bot performance telemetry, execute regular exports:

Export Output & Structure

The export command creates a timestamped SQL dump inside your workspace directory: backups/db-backup-2026-05-19-174000.sql This file contains standard DDL and DML commands:

Restoring from Backup


⚠️ Database Reset (Destructive Operations)

If you are running simulated paper trading and wish to wipe all ledger history to start fresh, you can reset the tables:
Wiping your production D1 database is an irreversible operation. It will permanently delete all trade logs, position records, and asset histories. Always execute hoox db export --remote before running a reset!

Soft Reset Alternative

If you want to clear data but preserve schema structure:

📋 D1 Free Tier Limits & Monitoring


🔗 Next Steps

Last modified on July 5, 2026