# SQLX Offline Mode - Quick Reference Card

**Status**: ✅ **READY** (58 cache files committed)
**Last Updated**: 2025-10-18

---

## Quick Commands

### ✅ Build Production Services (Offline)
```bash
SQLX_OFFLINE=true cargo build --workspace --lib --release
# Time: ~90 seconds, no database required
```

### ✅ Check Single Service (Offline)
```bash
SQLX_OFFLINE=true cargo check -p trading_service --lib
```

### ⚠️ Run Tests (Database Required)
```bash
export DATABASE_URL="postgresql://foxhunt:foxhunt_dev_password@localhost:5432/foxhunt"
cargo test --workspace
```

### 🔄 Regenerate Cache (After Schema Changes)
```bash
unset SQLX_OFFLINE
export DATABASE_URL="postgresql://foxhunt:foxhunt_dev_password@localhost:5432/foxhunt"
cargo sqlx prepare --workspace
git add .sqlx/
git commit -m "chore: Update SQLX cache after schema changes"
```

---

## Cache Status

| Service | Files | Location |
|---------|-------|----------|
| Trading Service | 30 | `services/trading_service/.sqlx/` |
| API Gateway | 11 | `services/api_gateway/.sqlx/` |
| Trading Agent Service | 11 | `services/trading_agent_service/.sqlx/` |
| Common Library | 6 | `common/.sqlx/` |
| **Total** | **58** | All committed to git ✅ |

---

## When to Use Offline Mode

### ✅ Use Offline Mode For:
- **CI/CD builds** (library compilation)
- **Docker multi-stage builds**
- **Offline development** (production code)
- **Fast iteration** on non-database code

### ❌ Don't Use Offline Mode For:
- **Running tests** (126 test queries need database)
- **Schema changes** (must regenerate cache)
- **New SQLX queries** (cache must be updated)

---

## Common Issues

### Issue: "SQLX query not found in cache"
**Solution**: Set `SQLX_OFFLINE=true` and verify cache files exist.

### Issue: "DATABASE_URL must be set to compile tests"
**Solution**: This is expected. Tests need database:
```bash
export DATABASE_URL="postgresql://foxhunt:foxhunt_dev_password@localhost:5432/foxhunt"
```

### Issue: Cache out of sync after migration
**Solution**: Regenerate cache:
```bash
unset SQLX_OFFLINE
cargo sqlx prepare --workspace
git add .sqlx/ && git commit -m "chore: Update SQLX cache"
```

---

## CI/CD Template

```yaml
# Production build (offline)
- name: Build services
  run: |
    export SQLX_OFFLINE=true
    cargo build --workspace --lib --release

# Tests (database required)
- name: Run tests
  run: |
    export DATABASE_URL="postgresql://..."
    cargo test --workspace
```

---

## Performance

| Operation | Time | No Database? |
|-----------|------|--------------|
| Workspace library build | ~90s | ✅ |
| trading_service check | ~1m 46s | ✅ |
| api_gateway check | ~10s | ✅ |
| Tests execution | varies | ❌ |

---

## Test Query Limitation

**Known**: 126 test queries are **not cached** by SQLX design.

**Why**: Tests execute against live database at runtime, caching would bloat production artifacts.

**Impact**: Tests require `DATABASE_URL` during compilation and execution.

**Workaround**: This is expected behavior, no action needed.

---

## Full Documentation

See: [`AGENT_F23_SQLX_OFFLINE_CACHE_REPORT.md`](/home/jgrusewski/Work/foxhunt/AGENT_F23_SQLX_OFFLINE_CACHE_REPORT.md)

---

**Quick Reference v1.0** | Agent F23 | 2025-10-18