Spaces:
Paused
Paused
|
Download src/lib/db/AGENTS.md from igorkurgin/omniroute: direct link, hf CLI and curl.
- Browser
- Download file 7.01 kB
-
https://huggingface.co/spaces/igorkurgin/omniroute/resolve/main/src/lib/db/AGENTS.md
- Command line
-
hf download hf://spaces/igorkurgin/omniroute/src/lib/db/AGENTS.md
-
curl -L -o AGENTS.md https://huggingface.co/spaces/igorkurgin/omniroute/resolve/main/src/lib/db/AGENTS.md
7.01 kB
| # src/lib/db/ — SQLite Persistence Layer | |
| **Purpose**: Domain-driven SQLite persistence. Each module owns a specific table set. Schema migrations are versioned and idempotent. No raw SQL in routes — all ops go through `src/lib/db/` modules. | |
| --- | |
| ## Key Modules | |
| ### Core Infrastructure | |
| - **`core.ts`** — `getDbInstance()` returns singleton `better-sqlite3` with WAL journaling. Exports `rowToCamel()` (snake_case → camelCase), `encryptConnectionFields()` for provider credentials at rest. `SCHEMA_SQL` defines 15 base tables. | |
| - **`migrationRunner.ts`** — Applies versioned SQL files from `db/migrations/` inside transactions. Tracks applied migrations in `_omniroute_migrations`. Runs at startup; each migration is idempotent. | |
| - **`db/migrations/`** — 21 SQL files (`001_initial_schema.sql` → `021_combo_call_log_targets.sql`). Each migration has single responsibility, runs in a transaction, never fails partially. | |
| - **`localDb.ts`** — Re-export layer only. Never add logic here. Consumers import domain modules from this file for convenience. | |
| ### Domain Modules (22 total) | |
| Each module owns specific tables + CRUD operations: | |
| | Module | Tables | Responsibility | | |
| | ----------------------- | ------------------------- | ------------------------------------------------------- | | |
| | `providers.ts` | `provider_connections` | OAuth/API key provider registration and credentials | | |
| | `models.ts` | `models` | Model definitions, capabilities, pricing | | |
| | `combos.ts` | `combos`, `combo_targets` | Combo routing configs, target ordering | | |
| | `apiKeys.ts` | `api_keys` | API key lifecycle, scopes, quota tracking | | |
| | `settings.ts` | `settings` | KV store for system configuration | | |
| | `backup.ts` | Backup export/import ops | Serialize/deserialize entire DB state | | |
| | `proxies.ts` | `proxies` | MITM proxy configs and routing rules | | |
| | `prompts.ts` | `prompts` | Reusable prompt templates, versioning | | |
| | `webhooks.ts` | `webhooks` | Event-driven webhook subscriptions and logs | | |
| | `detailedLogs.ts` | `detailed_logs` | Per-request audit logging (optional, high volume) | | |
| | `domainState.ts` | `domain_state` | Transient runtime state (not persisted across restarts) | | |
| | `registeredKeys.ts` | `registered_keys` | Whitelisted API keys for MCP/A2A access | | |
| | `quotaSnapshots.ts` | `quota_snapshots` | Historical quota usage for analytics | | |
| | `modelComboMappings.ts` | `model_combo_mappings` | Map models to combo defaults | | |
| | `cliToolState.ts` | `cli_tool_state` | CLI-specific persistent state | | |
| | `encryption.ts` | — | Helpers for encrypting/decrypting sensitive fields | | |
| | `readCache.ts` | — | In-memory cache for read-heavy ops (models, providers) | | |
| | `secrets.ts` | `secrets` | Encrypted secret storage (API keys at rest) | | |
| | `stateReset.ts` | — | Wipe/reset DB state for testing or recovery | | |
| | `contextHandoffs.ts` | `context_handoffs` | Store/retrieve session context for agent handoff | | |
| | `migrations/` | — | Versioned SQL schema evolution | | |
| | `core.ts` | — | Singleton DB instance, helpers, schema definition | | |
| ### Encryption & Security | |
| - **Sensitive fields** (API keys, OAuth tokens, connection strings) encrypted at rest using `src/lib/encryption/` utilities | |
| - **`encryptConnectionFields()`** in `core.ts` — Automatic encryption when storing provider credentials | |
| - **`secrets.ts`** — Dedicated encrypted store for long-term secret handling | |
| - **Never log** SQLite encryption keys or raw secrets; always use redacted values in logs | |
| ### Testing Strategy | |
| For authoritative coverage requirements and test execution guidelines, see [`CONTRIBUTING.md#running-tests`](../../CONTRIBUTING.md#running-tests) (lines 136–162). | |
| - **Unit tests** mock `getDbInstance()` to return isolated sqlite in-memory instance | |
| - **Integration tests** use real SQLite with migrations applied, data cleaned up after each test | |
| - **No fixture interdependencies** — each test runs migrations fresh | |
| - Test files: `tests/unit/db/*.test.mjs`, `tests/integration/db/*.test.mjs` | |
| ### Anti-Patterns | |
| - ❌ Raw SQL in routes — always use domain module functions | |
| - ❌ Direct `prepare()` statements outside `db/` modules — breaks modularity | |
| - ❌ Mixing encryption logic in domain modules — use `encryption.ts` helpers only | |
| - ❌ Accessing `provider_connections` table from `combos.ts` — each module owns its tables | |
| - ❌ Skipping migrations for schema changes — all changes go through `db/migrations/` | |
| ### Adding a New Domain Module | |
| 1. Create `src/lib/db/[module].ts` with CRUD functions (create, read, update, delete, list) | |
| 2. Export from `src/lib/db/localDb.ts` (add re-export) | |
| 3. If new tables required: create migration in `db/migrations/NNN_[description].sql` | |
| 4. Run migration via `migrationRunner.ts` at startup (automatic) | |
| 5. Add unit tests in `tests/unit/db/[module].test.mjs` | |
| 6. Ensure tests meet the coverage requirements in [`CONTRIBUTING.md#running-tests`](../../CONTRIBUTING.md#running-tests) | |
| ### Performance Notes | |
| - **Read cache** (`readCache.ts`) — Pre-loads frequently accessed data (models, providers) at startup; invalidated on write | |
| - **WAL journaling** (`core.ts`) — Enables concurrent reads during writes | |
| - **Batch operations** — Use prepared statements with parameter binding to avoid SQL injection | |
| - **Connection pooling** — Singleton pattern prevents per-request connection overhead | |
| --- | |
| ## Key Decisions | |
| - **SQLite over PostgreSQL**: Simpler deployment, no separate database server, encryption at application layer | |
| - **Versioned migrations**: Each schema change is tracked, reproducible, reversible with effort | |
| - **Domain modules**: Enforces single responsibility, prevents cross-module table access | |
| - **Re-export layer**: Convenience for consumers; `localDb.ts` is re-export-only to prevent circular dependencies | |
| --- | |
| ## Review Focus | |
| - DB module changes must preserve domain boundaries (one module = one table set) | |
| - New migrations must be idempotent and run inside transactions | |
| - Encryption helpers used for all sensitive fields | |
| - Test coverage and PR requirements: see [`CONTRIBUTING.md#running-tests`](../../CONTRIBUTING.md#running-tests) (lines 136–162) | |
| - No raw SQL in routes or non-db modules | |