gantry: Skill for Claude Code

Database & Service Layer — Gantry Server

The database module

Single file: server/src/services/database.ts. Everything else imports from it — there is no ORM, no query builder, no separate migration runner.

• getDb() — returns the raw bun:sqlite Database instance. Throws 'Database not initialized — call createDatabase() first' if called before createDatabase(). Import path from a service module: from "./database.js"; from a route: from "../../services/database.js".
• createDatabase(dbPath?: string) — opens the DB, sets pragmas, runs the full inline schema (CREATE TABLE IF NOT EXISTS ... for every table) plus a short list of ALTER TABLE ... ADD COLUMN column-upgrade shims (wrapped in try/catch to ignore "duplicate column" on existing DBs). Call with no args in production; call with ':memory:' (or a temp file path) in tests.
• getDbIfInitialized() — like getDb() but returns null instead of throwing; used by code paths that need to no-op gracefully before startup completes.
• closeDb() — clears the prepared-statement cache and closes the connection. Always call in test afterEach.
• Typed query helpers — prefer these over raw db.prepare() for simple queries, they cache prepared statements by SQL string and give you a typed return instead of as any:
  • queryOne<T>(sql, ...params): T | null
  • queryAll<T>(sql, ...params): T[]
  • queryInsert(sql, ...params): number — returns lastInsertRowid
  • queryRun(sql, ...params): number — returns changes count
  • All four log a warning and return a safe empty value (null/[]/0) if called before createDatabase() — they do not throw.
• For multi-statement transactions or when you need the raw Statement object (e.g. turn-ingestor.ts building an insert once and reusing .run() in a loop), call getDb() and use db.prepare(sql) / db.transaction(fn)() directly — see the transaction pattern below.

Where fleet.db lives

join(FLEET_DIR, 'data', 'fleet.db') — resolved inside createDatabase() when called with no dbPath argument. FLEET_DIR itself is resolved in server/src/config/env.ts (resolveFleetDir()): explicit FLEET_DIR env var first, then a documented fallback search — read env.ts's top comment block if you need the exact fallback order, don't assume. Never point a local dev run or a test at the real fleet.db — use GANTRY_MOCK=1 for a running server (see build-and-dev skill) or createDatabase(':memory:') for tests.