HeliosDB-Nano

Install HeliosDB-Nano via crates.io or build from source. Lists every cargo feature flag (code-graph, code-embed, mcp-endpoint, fips, ha-full, etc.), shows feature-matrix recipes, initializes a data directory, and verifies the install. Use this when the user has not yet run heliosdb-nano on this machine, or when adding a feature that requires a custom build.

Database branching in HeliosDB-Nano — ephemeral fork-test-discard sandboxes. Create a branch from main (or any other branch, with an optional `AS OF` historical anchor), make isolated changes, validate, then discard. The primary pattern for agent sandboxes, migration rehearsals, A/B experiments, and short-lived "what if" workspaces. MERGE back exists but its conflict detection is currently unreliable — prefer discarding and re-applying validated SQL to main. Use this when the user says "branch", "fork the database", or wants to try a destructive change without affecting production data.

Run HeliosDB-Nano as an MCP (Model Context Protocol) server so AI agents (Claude Code, Codex CLI, MCP-aware tools) can query, write, branch, time-travel, and search via JSON-RPC 2.0. Covers stdio, HTTP, and WebSocket transports; the 16-tool catalog (10 DB-backed + 6 in-process RAG); and wiring into Claude Code via `claude mcp add`. Use this when the user wants an LLM agent to operate the database directly through tool calls instead of writing SQL.

Top-level navigation for HeliosDB-Nano. Auto-loads when user mentions "heliosdb", "heliosdb-nano", or pastes its CLI/REPL output. Routes to one of 16 domain skills (install, connect, schema, query, transactions, branches, time-travel, backup, vector, code-graph, graph-rag, mcp, server, deploy, observability, migrate). Use this skill to find the right skill before going deep.

Query historical state in HeliosDB-Nano. Every read can be anchored to a past timestamp via `AS OF TIMESTAMP '…'`; the engine returns the snapshot as it was at that moment. Useful for audit/forensics, "what changed", reverting after a bad UPDATE, and comparing aggregates across time. Use this when the user says "what did this look like yesterday", "before that bug", "show me the state at 10am", or "diff against last week".

The pre-merge validation methodology used in this repo. Required before merging any non-trivial change — bug fixes, optimizer passes, storage tweaks, parser changes, anything user-visible. Eight phases: branch + implement, targeted unit tests, integration regression, targeted feature bench, cross-feature regression, head-to-head OLTP comparison vs main, validation report, release. Use this when the user says "merge this", "this is ready to ship", "before merging", or asks for a perf gate before a release.

Index a repository's source code as an AST symbol graph in HeliosDB-Nano. Covers grammar registration (Rust / Python / TypeScript / Go / Markdown / SQL), full-project indexing (`code_index`), LSP-shaped queries (`lsp_definition`, `lsp_references`, `lsp_call_hierarchy`, `lsp_hover`), the git-hook helper (`heliosdb-nano code-graph hook`), and the `_hdb_code_symbols` / `_hdb_code_symbol_refs` tables. Use this when the user wants AI-grade "where is this defined / used / called" queries across a codebase, or wants to wire a code-graph into a Claude Code / MCP workflow.

Migrate an existing app to HeliosDB-Nano with minimal source changes. Covers SQLite (Python `sqlite3` drop-in via the `heliosdb_sqlite` SDK), PostgreSQL (any PG-wire client works unchanged), and MySQL (`--mysql` listener for PHP/WordPress). Documents the dialect-autodetect parser, accepted SQLite-isms (`?` placeholders, `INSERT OR REPLACE/IGNORE`, `INTEGER PRIMARY KEY AUTOINCREMENT`, `sqlite_master`, `PRAGMA *`), and the gotchas that still require code changes. Use this when the user says "port this from sqlite", "switch from sqlite3 to Helios", or "drop-in replace Postgres / MySQL".

Define and inspect schema in HeliosDB-Nano. Covers CREATE/ALTER/DROP TABLE with PK/FK/UNIQUE/CHECK/DEFAULT constraints, regular and HNSW vector indexes, views, materialized views, triggers, PL/pgSQL functions, and introspection through Postgres (`pg_class`, `information_schema`), SQLite (`sqlite_master`, `PRAGMA table_info`), and Nano-specific (`\d`, `\dt`, `\dS`, `\dmv`) surfaces. Use this when the user asks "create a table", "add an index", "describe", or "what columns does X have".

Multi-tenant database isolation in HeliosDB-Nano. Create tenants with one of three isolation modes (SharedSchema with RLS, SchemaPerTenant, DatabasePerTenant), assign tiered plans (free / starter / pro / enterprise) with per-tenant resource limits (storage / connections / QPS), define row-level-security policies that auto-inject `current_tenant()` predicates, and switch the active tenant per session. Use this when the user mentions "multi-tenant", "tenancy", "tenant", "RLS", "row-level security", or wants to provision per-tenant isolation without standing up separate database instances.

Transactions, savepoints, isolation, and bulk-load patterns in HeliosDB-Nano. Covers BEGIN/COMMIT/ROLLBACK, nested SAVEPOINT … RELEASE/ROLLBACK TO, the embedded library's RAII Transaction handle, deadlock detection, and the fast path for inserting tens-of-thousands of rows in one transaction. Use this when the user wants atomicity, multi-statement units of work, or fast bulk inserts.

Backup and restore HeliosDB-Nano. Two surfaces — CLI (`heliosdb-nano dump` / `restore`) and library (`db.dump_full` / `db.restore_from_dump` / `db.restore_tables`). Compression options (zstd default, gzip, brotli, none). Append (incremental) backups. Periodic background dumps via `--dump-schedule "0 */6 * * *"`. Verification on restore. Use this for routine backups, partial table restores, in-memory persistence, and migrating a data dir between hosts.

Open a connection to HeliosDB-Nano. Covers all five connection modes — embedded library (Rust), PostgreSQL wire (psql / psycopg2 / sqlx / pg8000), MySQL wire (mysql / WordPress / PHP), REPL, and the Python sqlite3 drop-in SDK. Pick the right one for the workload, set auth and TLS, and verify the connection. Use this when the user says "connect to", "psql", "open a session", or wants to talk to a Nano server already running on a host.

Deploy HeliosDB-Nano in containers and managed-platform environments. Covers the in-repo Dockerfile (`Dockerfile.binary` and `deployment/docker/`), docker-compose, Fly.io (`deployment/flyio/fly.toml`), Railway (`deployment/railway/railway.toml`), Render (`deployment/render/render.yaml`), the bare-metal install script (`scripts/install-nano-pilot.sh`), and a documented systemd template. Use this when the user wants to ship Nano to a hosted environment or wrap it in a service.

Knowledge-graph + RAG pipeline in HeliosDB-Nano. Adds the `_hdb_graph_*` universal schema on top of `code-graph`, plus seed/expand/rerank traversal and domain-specific ingestors for documents (PDF, Office, Markdown), audio (transcribed), images (captioned), email, issues, and Q&A. Pair with HNSW vector search (`heliosdb-nano-vector`) for hybrid retrieval. Use this when the user wants a full RAG stack — indexing heterogeneous content into a typed graph that an agent can traverse, not just a flat vector store.

Tracing, slow-query logging, health checks, statistics, and metrics in HeliosDB-Nano. Covers `RUST_LOG` filters, the WARN-level slow-query log (1 s default threshold), the `GET /health` HTTP endpoint, REPL diagnostic commands (`\stats`, `\compression`, `\optimize`, `\indexes`), and Prometheus integration where wired. Use this when the user is debugging performance, asking "why is this slow", monitoring uptime, or wiring Nano into Grafana / their alerting stack.

DML and queries in HeliosDB-Nano. Covers INSERT (basic, OR REPLACE/IGNORE, ON CONFLICT, INSERT…SELECT, RETURNING), UPDATE/DELETE with RETURNING, parameter styles (`?`, `$1`, `:name`, `@name`), EXPLAIN/EXPLAIN ANALYZE, CTEs, window functions, set ops, and the result-cache. Use this when the user is writing SELECT/INSERT/UPDATE/DELETE/MERGE statements or asking why a query is slow.

Run HeliosDB-Nano as a server (daemon mode) with TLS, authentication, HA replication, and user management. Covers `heliosdb-nano start | stop | status`, TOML configuration sections, the four authentication modes (trust / password / md5 / scram-sha-256), TLS cert/key wiring, the four HA replication roles (standalone / primary / standby / observer), the three sync modes (async / semi-sync / sync), and per-user account creation. Use this when the user wants a long-running database process, multi-client access over the network, or any HA setup.

Vector search in HeliosDB-Nano. Covers HNSW index creation (`CREATE INDEX … USING HNSW`), the three distance operators (`<->` L2, `<#>` negative inner product, `<=>` cosine), bulk vector inserts via the library API (`insert_vectors` / `delete_vectors` / `delete_vector_store`), hybrid BM25 + vector search via the MCP tool, and tuning knobs in `[vector]` config (`hnsw_ef_construction`, `pq_codebook_bits`). Use this when the user wants similarity search, embedding lookups, or RAG retrieval (without the higher-level graph layer).