# Mission AskDB turns natural language into **checked, schema-grounded SQL** so teams can ask questions about their own data without becoming SQL experts. The library, the CLI and the HTTP API return the SQL and never execute it: the host application runs it under its own database controls. The one exception is Studio's optional Playground **Execute**, a local development tool that is off by default (see [`SECURITY.md`](../SECURITY.md#studio-execute)). Reports and result summaries come after 1.0 (see [`roadmap.md`](roadmap.md), Phase 12, and [ADR 0030](adrs/0030-1-0-promises-checked-sql-only.md)). ## Target audience - **Primary — builders and integrators** — Software engineers and platform teams who **embed or wire up** AskDB (library, CLI, HTTP API, Studio; MCP after 1.0; a future SDK and embeddable UI). They own schema supply, API keys, execution boundaries, and how “modes” and tenant rules are enforced in their stack. - **Agents** — Autonomous or LLM-driven agents (coding assistants, workflow bots, internal tools) that invoke AskDB through **headless, machine-friendly surfaces**—at 1.0, the **CLI** and the **HTTP API**, with stable inputs/outputs—so they can generate checked SQL under the same contracts as human integrators. A first-party **MCP** server comes after 1.0 (roadmap Phase 14). **Accountability and policy** (what may execute, on which data, with which keys) remain with the team that deployed the agent. - **Secondary — askers inside the product** — Analysts, product managers, operators, and similar roles who **ask questions in natural language** **through an app or dashboard** that already integrated AskDB. They benefit from plain-language questions without living in SQL; governance and data access remain defined by the integrating team. ## North star We optimize for two things at once: 1. **Trust-first analytics** — Answers are anchored in the customer’s database schema. AskDB returns checked SQL and, outside Studio's local Playground, never executes it; the host runs it under its own database controls ([ADR 0012](adrs/0012-sql-checks-are-defense-in-depth.md)). Row-level data is treated as sensitive by default: at 1.0 the model reasons over schema only, and the NL→SQL call carries no row payloads. When data must touch the model, it should be **explicit, bounded, and user-controlled**, aligned with the product’s “modes”: a `bounded_results` mode that summarizes a bounded subset of the host’s own results comes after 1.0 (roadmap Phase 12). Until then `bounded_results` is reserved and behaves exactly like `schema_only` ([`modes-v1.md`](contracts/modes-v1.md)). 2. **Developer-first embed** — AskDB is built to be **plugged into projects** as **installable npm packages**: bring-your-own API keys, bring-your-own database connectivity, bring-your-own embedding provider, and bring-your-own vector store. The headless core (`@askdb/core`), the config-driven facade (`@askdb/client`) and companion packages (the `askdb` CLI, `@askdb/http-api`, the engine packages, `@askdb/studio`, `@askdb/rag`), plus a future SDK + embeddable UI (similar in spirit to Clerk or OpenRouter), let teams ship “ask your data” inside their own apps without rebuilding the pipeline. ## What success looks like - A developer can install AskDB from npm, point it at their schema metadata and an LLM key, ask questions in plain language, and get **checked SQL** that their own runtime executes under its own database controls. Reporting on top of results comes after 1.0 (roadmap Phase 12). - **Schema intelligence** — Raw technical schema (columns, types, keys) is not enough for great answers; AskDB turns it into a **describable schema** enriched with **business context** (what tables and fields *mean*), **aliases / synonyms** (how users *say* it), and an optional **concept dictionary** (shared domain terms). Authoring happens through **Studio**, a local browser UI that AI-suggests descriptions and aliases and lets a human confirm; the artifact stays hand-editable markdown, so no UI is a prerequisite. - **RAG-friendly format** — The describable schema is stored in a format **designed for chunking and retrieval**: stable IDs per table/column/concept, structured metadata in YAML front-matter, prose (descriptions, “common query language”, example questions) in markdown body. This is the same artifact `@askdb/rag` chunks and embeds, and that NL→SQL prompt assembly grounds against — there is no separate “knowledge base”. - **RAG is part of the package** — `@askdb/rag` ships **bring-your-own embedder** and **bring-your-own vector store** adapters with sensible defaults (in-memory, then file-backed, then pgvector); sensitive-field rules from the schema artifact propagate into chunking so flagged content is excluded from embeddings by default. - **Flexible connectivity** — The AskDB application **does not always need a live connection** to the customer’s database instance. Teams can **import** schema artifacts (files or exported metadata) and work schema-first; a **direct DB attachment** remains optional when live introspection is desired (see `platform.md`). - **Schema introspection is first-class** — Generating a Schema v2 artifact from a real database is a supported capability, not an afterthought. For Postgres, AskDB ships **two equally-supported paths** that produce the **same** artifact: a **live** connection (catalog-runner-backed reads, BYO connection details) and an **air-gapped** path (run documented SQL in `psql`/CI/IDE, hand the export bundle to AskDB). MySQL, MariaDB, SQLite and SQL Server introspect over a live connection, and Prisma schemas introspect from the schema file. Every path lands in the same describable schema that Studio, RAG, and prompt assembly already read. - **Multi-tenant** setups get **tenant-scoped generation** when the schema declares a tenant policy: AskDB requires a tenant scope on every request, instructs the model to filter by it, binds the tenant IDs, and rejects (in `strict` mode) or flags SQL without a tenant predicate that filters (the tenant column compared with the tenant placeholder, ANDed into the filter). That check is a lint, not proof of isolation: the database (row-level security, a least-privilege role) enforces tenant isolation when the host executes the SQL. See [ADR 0012](adrs/0012-sql-checks-are-defense-in-depth.md). - Operators can mark **sensitive fields** so they are excluded from indexing/RAG and from prompts where applicable. - **Five engine families at 1.0** — AskDB supports PostgreSQL, MySQL, MariaDB, SQLite and SQL Server, not only Postgres. Each engine was added deliberately (dialect, driver, validation) so quality stays high, and the consumer lab covers every one, including its tenant suite (see `roadmap.md`). ## Non-goals (for now) - Owning the customer’s database or credentials centrally. - Executing generated SQL in an application's runtime. AskDB returns SQL; the host decides whether and how to run it ([ADR 0012](adrs/0012-sql-checks-are-defense-in-depth.md)). Studio's optional Playground **Execute** is a local development tool, not an execution path for applications. - Training proprietary models on customer data. - Guaranteeing domain-specific business correctness without human review of critical queries—users remain accountable for production queries and access control. ## Principles - **Schema is the contract** — Ingest, normalize, and search schema descriptions so generation stays grounded. - **Enrichment beats bare DDL** — Prefer an explicit pipeline from **pure schema structure** → **describable, context-rich schema** (AI-assisted gap detection + human confirmation through Studio, web UI, or prompts). - **Headless-first, then UI** — Every authoring and querying capability is reachable from a headless surface (library, CLI) before a graphical surface depends on it. UIs are alternatives, not prerequisites. - **BYO everything that touches secrets** — API keys (chat + embeddings), database connectivity, and vector store choice all stay on the customer side. The package ships adapters and defaults; the integrator owns the keys and the data path. - **Pluggable adapters at every external seam** — LLM provider, introspection connector, embedding provider, and vector store are interchangeable behind small interfaces. Swapping any one of them does not require forking AskDB. - **Installable contract** — `@askdb/core` is published to npm with a documented, semver-stable surface. Wrappers (CLI, Studio, RAG, HTTP API; MCP after 1.0; a future SDK) depend on it as consumers, not co-located private code. See [`docs/integration/installable-package.md`](integration/installable-package.md) for BYO model + SQL-generation and introspection recipes. - **Progressive disclosure** — Start with one schema format and **Postgres as the reference engine**; add **other databases one at a time** (adapters, dialect-aware SQL, validation) once the Postgres path is proven. Roadmap Phase 11 added MySQL, MariaDB, SQLite and SQL Server this way. - **Same core, many surfaces** — The library, CLI, Studio, and HTTP API share one engine so behavior stays consistent; MCP joins them after 1.0.