foxhunt/SQLX_OFFLINE_SETUP.md

SQLx Offline Mode Setup - PostgreSQL Authentication Fix

Problem Solved

This document explains the resolution of PostgreSQL authentication errors that occurred during compilation of the Foxhunt HFT trading system.

Original Error

password authentication failed for user "postgres"

Root Cause

• SQLx query! macros require compile-time SQL verification
• This verification requires a live PostgreSQL database connection via DATABASE_URL
• The system was trying to connect with default "postgres" user during compilation
• No DATABASE_URL environment variable was configured for development builds

Affected Files

• market-data/src/indicators.rs - Contains multiple sqlx::query! macros
• tests/e2e/src/clients.rs - Contains sqlx::query! macros for configuration management

Solution Implemented

1. Enabled SQLX_OFFLINE Mode

Added to .cargo/config.toml:

[env]
# Fix PostgreSQL authentication errors during compilation
# Uses offline sqlx query checking instead of live database connection
SQLX_OFFLINE = "true"

2. How It Works

• Offline Mode: SQLx uses pre-generated sqlx-data.json files for compile-time verification
• No Database Required: Compilation no longer requires a live PostgreSQL connection
• Query Safety Preserved: Compile-time type checking still enforced using cached schema data

3. Existing Infrastructure

The system already had the necessary files:

• /home/jgrusewski/Work/foxhunt/market-data/sqlx-data.json - Contains schema data for market-data queries
• /home/jgrusewski/Work/foxhunt/sqlx-data.json - Root-level schema data

Verification

Compilation Test Results

1. Market Data Package: ✅ Compiles successfully

   SQLX_OFFLINE=true cargo check --package market-data
   

2. E2E Tests Package: ✅ Compiles successfully

   SQLX_OFFLINE=true cargo check --package e2e_tests
   

3. Full Workspace: ✅ No PostgreSQL authentication errors

   SQLX_OFFLINE=true cargo check --workspace
   

Developer Guidelines

When to Update sqlx-data.json

If you modify SQL queries in the codebase, you need to regenerate the schema cache:

# 1. Ensure PostgreSQL is running with proper credentials
export DATABASE_URL="postgresql://foxhunt:${DB_PASSWORD}@localhost:5432/foxhunt"

# 2. Regenerate schema data
cargo sqlx prepare --workspace --check -- --all-targets --features database

# 3. Commit the updated sqlx-data.json files
git add market-data/sqlx-data.json sqlx-data.json
git commit -m "Update SQLx schema cache after query modifications"

CI/CD Considerations

For CI environments, consider adding a verification step:

- name: Check SQLx data is up-to-date
  env:
    DATABASE_URL: ${{ secrets.CI_DATABASE_URL }}
  run: |
    cargo sqlx prepare --check --workspace -- --all-targets --features database

Alternative Solutions (Not Implemented)

1. Set DATABASE_URL: Would require running PostgreSQL during every compilation
2. Use query_unchecked!: Would lose compile-time type safety
3. Switch to query_as!: Would require extensive code changes

Production Environment

In production, the system uses the proper database configuration:

• Username: foxhunt (not postgres)
• Connection via environment variables in config/environments/production.env
• Hot-reload capabilities through PostgreSQL NOTIFY/LISTEN

Files Modified

1. .cargo/config.toml - Added SQLX_OFFLINE environment variable
2. This documentation - Created to explain the solution

Architecture Compliance

This solution maintains the architectural principles:

• ✅ Config crate remains the only vault accessor
• ✅ TLI remains a pure client
• ✅ No backward compatibility layers introduced
• ✅ Service architecture unchanged

---

Solution implemented: 2025-09-27 Status: PostgreSQL authentication errors resolved for all affected packages