From 57bee98cf9e673a9b3e63d2fb09b4817b3d520eb Mon Sep 17 00:00:00 2001 From: Sergio Arroutbi Date: Wed, 20 May 2026 13:02:27 +0200 Subject: [PATCH] Document SQLite database usage in README.md and CLAUDE.md Add SQLite Database sections to both files explaining the DATABASE_URL environment variable, in-memory vs file-based modes, auto-created schema, mock data seeding, and linking to the full guide in docs/TESTING_WITH_SQLITE.md. Update the CLAUDE.md tech stack to distinguish production (TimescaleDB) from dev/test (SQLite) database usage. Co-Authored-By: Claude Opus 4.6 Signed-off-by: Sergio Arroutbi --- CLAUDE.md | 17 ++++++++++++++++- README.md | 18 ++++++++++++++++++ 2 files changed, 34 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 222f755..adb8279 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,7 +13,8 @@ The full SRS (69 FRs, 23 NFRs, 29 SRs with Gherkin acceptance criteria) lives in - **Language:** Rust with `#![forbid(unsafe_code)]` (SR-023) - **Framework:** Axum (async HTTP/WebSocket) - **Runtime:** Tokio -- **Database:** TimescaleDB (time-series attestation history/metrics) +- **Database (production):** TimescaleDB (time-series attestation history/metrics) +- **Database (dev/test):** SQLite via `DATABASE_URL` env var (`sqlite::memory:` or `sqlite://./file.db`); auto-creates schema on startup, optional mock seeding - **Cache:** Redis with tiered TTLs (agent list 10s, detail 30s, policies 60s, certs 300s) - **Keylime comms:** mTLS via rustls, private keys in HSM/Vault (never cleartext on disk) - **Auth:** OIDC/SAML + short-lived JWT (15 min) with refresh rotation @@ -51,6 +52,20 @@ The mock fleet has 3 agents: healthy (GET_QUOTE), failed (FAILED), and push-mode Alternatively, open `test-data/verifier.json` and `test-data/registrar.json` in the Mockoon desktop app, start both environments, then run the tests from a terminal. The GUI shows live request logs for debugging. +## SQLite Database + +For development and testing, the backend supports SQLite as a lightweight database alternative to TimescaleDB. It is controlled entirely by the `DATABASE_URL` environment variable: + +```bash +DATABASE_URL=sqlite::memory: cargo run # in-memory (ephemeral) +DATABASE_URL=sqlite://./keylime-dev.db cargo run # file-based (persistent) +cargo run # no database (in-memory repositories) +``` + +The schema (alerts, policies, policy_changes, audit_entries, attestation_results, correlated_incidents) is auto-created on startup. When `seed_mock_data = true` is set in the settings file, the alerts table is seeded with sample data on first run. + +See [docs/TESTING_WITH_SQLITE.md](docs/TESTING_WITH_SQLITE.md) for the full guide. + ## Architecture ### System Layers diff --git a/README.md b/README.md index c40d03c..59e8c05 100644 --- a/README.md +++ b/README.md @@ -250,6 +250,24 @@ curl -X POST http://localhost:8080/api/auth/logout | jq The backend reads `KEYLIME_VERIFIER_URL` and `KEYLIME_REGISTRAR_URL` environment variables (defaulting to `http://localhost:3000` and `http://localhost:3001`). +## SQLite Database + +The backend supports SQLite as a lightweight database for development and testing, controlled by the `DATABASE_URL` environment variable. When unset, in-memory repositories are used (no database). + +```bash +# In-memory (ephemeral, data lost on restart) +DATABASE_URL=sqlite::memory: cargo run + +# File-based (persists across restarts, auto-created) +DATABASE_URL=sqlite://./keylime-dev.db cargo run +``` + +SQLite stores alerts, policies, policy changes, audit entries, attestation results, and correlated incidents. The schema is auto-created on startup (`CREATE TABLE IF NOT EXISTS`). + +When mock data seeding is enabled via the settings file (`seed_mock_data = true`), the alerts table is populated with sample data on first run. + +For a complete guide including schema details, type conventions, inspection commands, and limitations vs production Postgres, see [docs/TESTING_WITH_SQLITE.md](docs/TESTING_WITH_SQLITE.md). + ### Mock fleet The mock data defines a fleet of 7 agents in different states: