Natural language → schema-grounded SQL. A layered monorepo of reusable contracts, database integrations, and first-party surfaces.
AskDB returns SQL for review. The host application owns approval, execution, database roles, tenant policy, network controls, and audit logging. @askdb/core never executes generated SQL.
ask() orchestration, Schema v2 loading/parsing, enrichment suggestions, operating modes, Pino structured logging, and retrieval input. Central contract for all other packages.Connector<TInput> contract, introspection orchestrator, and Schema v2 renderer. Defines the intermediate SQL IR (SqlSchema, SqlTable, SqlColumn, SqlForeignKey, …) that every connector produces.Embedder / VectorStore / Retriever interfaces, and built-in adapters: in-memory, file-backed, pgvector. All stores (createMemoryStore, createFileStore, createPgvectorStore) and the embedder (createAiSdkEmbedder) are exported from the root barrel — no sub-path imports required. Also ships a setup-store CLI command for pgvector schema provisioning.loadWorkspace(), table draft builders, saveTable(), concepts editing, markdown preservation with frontmatter, suggestion context builders, and bundleSchemaDirectory(). Shared logic for TUI and Studio.postgresDialect), createPostgresConnector() with live and from-export modes, catalog SQL templates (POSTGRES_TEMPLATE_BUNDLE), and optional pg-backed catalog runner.pg is optional peer — only for live introspection. Generated SQL still executes outside AskDB.schema.prisma or a directory of .prisma files via @prisma/internals and renders Schema v2 physical metadata. Auto-discovers the Prisma project root.MYSQL_DIALECT, MARIADB_DIALECT, createMysqlConnector(), and a mysql2-backed catalog runner. NL→SQL prompt and validator live in @askdb/core.SQLITE_DIALECT, createSqliteConnector(), and a better-sqlite3-backed catalog runner for reading SQLite database files.SQLSERVER_DIALECT, createSqlServerConnector(), and an mssql-backed catalog runner.askdb binary. Commands: ask (NL→SQL), introspect (schema discovery — engine and connection URL now resolved from askdb.config.ts without flags), enrich (launch TUI), studio (launch browser UI), init (bootstrap config), bundle (pack schema directory). Composed from all reusable packages.@askdb/core. Exposes POST /ask → SQL, GET /health. Accepts inline schemaJson or resolves from host.schemaPath in askdb.config.ts. Supports x-correlation-id header, request-body mode, and explain./api/workspace, /api/tables/:id, /api/suggest, /api/rag/status, /api/rag/index, /api/rag/query, /api/ask. Integrates enrichment, RAG exploration, and sample NL→SQL with token usage tracking. RAG vector store is configurable via askdb.config.ts rag.store field: memory, file (default), or pgvector (auto-provisions schema via ensureSchema()). Default schema directory resolved from config without requiring a CLI flag.OPENAI_API_KEY is set), and schema bundling. Operates on Schema v2 files only.import dependencies. Dashed = app-layer dependencies. Arrows point from consumer to provider. All roads lead to @askdb/core.| Package | Direct Dependencies | Optional Peer Dependencies |
|---|---|---|
@askdb/core |
ai, pino, zod, gray-matter |
— |
@askdb/ai |
ai |
Optional peers: AI SDK provider packages (e.g. @ai-sdk/openai), loaded lazily by the built-in providers |
@askdb/introspect |
— | — |
@askdb/postgres |
@askdb/core, @askdb/introspect |
pg (live introspection only) |
@askdb/prisma |
@askdb/introspect, @prisma/internals |
— |
@askdb/mysql |
@askdb/core, @askdb/introspect |
mysql2 |
@askdb/sqlite |
@askdb/core, @askdb/introspect |
better-sqlite3 |
@askdb/sqlserver |
@askdb/core, @askdb/introspect |
mssql |
@askdb/enrich |
@askdb/core |
— |
@askdb/rag |
@askdb/core |
pg (pgvector adapter), AI SDK embedder packages |
@askdb/tui |
@askdb/core, @askdb/enrich, ink, react |
OPENAI_API_KEY for suggestions |
@askdb/studio |
@askdb/core, @askdb/enrich, @askdb/rag, @askdb/postgres, react, vite |
AI SDK provider packages for RAG embeddings |
askdb CLI |
@askdb/core, @askdb/introspect, @askdb/postgres, @askdb/prisma (optional peer), @askdb/studio (dynamic) |
pg, model provider packages |
@askdb/http-api |
@askdb/core |
Model provider packages |
ask())ask(). RAG is an optional pre-step that replaces the full DDL with focused chunks.@askdb/enrich.ask() for large schemas, improving prompt quality and reducing token usage.my-app.schema/
schema.json # physical layer
tables/
users.md # describable layer
orders.md
order_items.md
concepts.md # optional vocabulary
schema.lock.json # RAG content hashes
schema.embeddings.json # RAG vectors (JSON)
schema.embeddings.bin # RAG vectors (binary)
{
"version": 2,
"schemaId": "my-app",
"provider": "postgres", // optional
"tables": [{
"id": "table:public.users",
"name": "users",
"schema": "public",
"columns": [{
"id": "table:public.users#email",
"name": "email",
"type": "text",
"nullable": false,
"sensitive": true // PII flag
}]
}]
}
| Extension Point | Interface | Defined In | When to Implement |
|---|---|---|---|
| SQL Dialect | AskDialect or DialectSpec |
@askdb/core |
Add a database dialect or custom SQL generation policy. Built-in IDs: postgres, mysql, mariadb, sqlite, sqlserver, cockroachdb |
| Introspection Connector | Connector<TInput> |
@askdb/introspect |
Add a new schema metadata source (new DB engine, export format, schema file type) |
| Catalog Runner | CatalogQueryRunner |
@askdb/introspect |
Use a different live database client while keeping the connector unchanged |
| RAG Embedder | Embedder = (texts: string[]) => Promise<number[][]> |
@askdb/rag |
Use a different embedding provider. Built-in helpers: AI SDK, OpenAI |
| Vector Store | VectorStore (upsert/query/delete) |
@askdb/rag |
Use a different vector database. Built-in: in-memory, file-backed, pgvector |
| Retriever | Retriever = (params) => Promise<QueryResult[]> |
@askdb/rag / @askdb/core |
Custom retrieval policy, hybrid search, or filtering logic |
| Enrichment UI | Workspace, draft builders, save helpers |
@askdb/enrich |
Build a custom authoring UI without depending on TUI or Studio |
| Product Surface | Compose packages into a workflow | App packages or consumer app | CLI, HTTP server, MCP server, browser SDK, Slack bot — host owns auth, policy, execution |
askdb.config.ts keys and bootstrapKeys in askdb.config.ts. Bind any value to an environment variable of your choosing with env("NAME"); the CLI loads .env first. AskDB reads one variable of its own from the environment, ASKDB_DEBUG.
| Config key | Purpose |
|---|---|
| ai.provider | openai | azure | foundry | google | anthropic | gateway |
| ai.providerConfig.<provider>.apiKey | API key for NL→SQL and enrichment suggestions (e.g. env("OPENAI_API_KEY")) |
| ai.language.model | Model ID (OpenAI default: gpt-4o-mini) |
| modes.askdbMode | schema_only | bounded_results |
| modes.omitSensitiveFromPrompt | Omit sensitive column/table names from DDL |
| logging.level | Pino log level: trace|debug|info|warn|error|fatal|silent |
| logging.correlationId | Override correlation ID for log lines |
| introspection.providerConfig.postgres.databaseUrl | Postgres URL for live introspection (e.g. env("DATABASE_URL")) |
| introspection.providerConfig.mysql.databaseUrl | MySQL connection URL for introspection |
| introspection.providerConfig.sqlserver.databaseUrl | SQL Server connection URL for introspection |
| introspection.providerConfig.sqlite.file | SQLite file path for introspection |
| host.schemaPath | Schema path for HTTP API server |
| host.schemaJson | Inline schema JSON for HTTP API |
| rag.embedder | mock | ai — selects RAG embedder backend |
| ai.embedding.model | Embedding model for rag.embedder: "ai" |
| ai.embedding.dimensions | Embedding vector size to request |
| rag.storeConfig.pgvector.databaseUrl | Postgres connection string for pgvector RAG store |
| rag.storeConfig.pgvector.indexStrategy | ivfflat | hnsw | none — pgvector index type |
| dev.mockSql | Bypass live model in tests |
| Command | Description |
|---|---|
askdb init | Create askdb.config.ts and install @askdb/config |
askdb ask -s <schema> -q <question> | Generate SQL from schema + question |
askdb introspect --out my.schema | Introspect using engine + URL from askdb.config.ts (zero-flag mode) |
askdb introspect --url $DB_URL --out my.schema | Live Postgres introspection (explicit URL) |
askdb introspect --prisma --out my.schema | Prisma schema-file introspection |
askdb rag setup-store --pg-url $URL --dimensions <n> | Auto-provision pgvector extension, table, and indexes |
askdb enrich --schema my.schema | Launch terminal enrichment UI |
askdb studio --schema my.schema | Launch browser Studio UI |
askdb bundle <dir> --out bundle.json | Bundle schema directory to JSON |
| Endpoint | Description |
|---|---|
GET /health | Health check |
POST /ask | NL→SQL: { question, schemaJson?, mode?, explain? } → { ok, sql, explain?, correlationId } |
| Route | Purpose |
|---|---|
GET /api/workspace | Load workspace state |
POST /api/tables/:id | Save table draft |
POST /api/suggest | AI enrichment suggestions |
GET /api/rag/status | RAG index status |
POST /api/rag/index | Build / rebuild RAG index |
POST /api/rag/query | Query RAG chunks |
POST /api/ask | Sample NL→SQL with RAG option |
| Workflow | Install | Optional Peers | Notes |
|---|---|---|---|
| Minimal Postgres SQL generation | @askdb/core ai |
AI SDK provider package (e.g. @ai-sdk/openai), optionally with @askdb/ai for config-driven model selection |
Neither @askdb/postgres nor pg needed. Uses ask({ dialect: "postgres" }); the spec is core's (ADR 0029). |
| Live Postgres introspection | @askdb/introspect @askdb/postgres |
pg |
Or supply your own CatalogQueryRunner. |
| Air-gapped Postgres introspection | @askdb/introspect @askdb/postgres |
None | From-export bundles only. Templates from POSTGRES_TEMPLATE_BUNDLE. |
| Prisma schema-file introspection | @askdb/introspect @askdb/prisma |
None declared | Produces Schema v2 physical metadata. No dialect included. |
| Terminal enrichment (TUI) | @askdb/tui |
OpenAI key for suggestions; manual authoring works without it | Operates on Schema v2 files only. |
| Local browser Studio | @askdb/studio |
AI SDK provider for suggestions; pg for pgvector RAG |
Local authoring UI, sample SQL checks, RAG exploration. |
| RAG (in-memory or file) | @askdb/rag @askdb/core |
Embedder package | No pg needed. |
| RAG with pgvector | @askdb/rag @askdb/core |
pg + embedder package |
Use createPgvectorStore(); call store.ensureSchema() once to auto-provision extension, table, and indexes. Or run askdb rag setup-store --dimensions <n>. Studio auto-provisions on every request when rag.store = "pgvector". |
| Batteries-included CLI | askdb |
Model provider key (env) | Pulls first-party integrations automatically. |
| HTTP API server | @askdb/http-api |
Model provider key (env) | Set host.schemaPath in askdb.config.ts or accept inline schemaJson. |