Package reference

Reference · Packages

AskDB is a workspace of focused packages. Install the ones your use case needs. This page is the index — purpose, install, and key exports for each.

AI provider adapters (@askdb/ai-openai, @askdb/ai-azure, @askdb/ai-google, @askdb/ai-anthropic) plug into the surfaces shown above via @askdb/ai. @askdb/client sits above @askdb/core + @askdb/ai as the config-driven entry point.

Core

@askdb/core

The dialect-agnostic NL-to-SQL pipeline. Schema loading, prompt construction, validation, and tenant-scope handling all live here.

npm install @askdb/core

Key exports

Symbol	Purpose
ask(options)	The main pipeline. Returns validated SQL.
loadSchema(path)	Load a schema artifact from a directory, bundle, or schema.json.
validateTenantScope / resolveTenantSql	Tenant-scope enforcement primitives.
createAskDbLogger	Structured logger that emits AskDB log events.
POSTGRES_DIALECT and built-in dialect IDs	Dialect inputs accepted by ask().
AskDbLanguageModel	AskDB’s public name for the AI SDK language model contract.

@askdb/client

Config-aware facade over @askdb/core. createAskDb() resolves the schema, model, and dialect from your askdb.config.* (and a provider registry you supply), so call sites pass only a question. Install it when you want the shortest config-driven path; skip it when you construct the model and load the schema yourself and call ask() directly.

npm install @askdb/client @askdb/ai @askdb/ai-openai @askdb/config

Key exports

Symbol	Purpose
createAskDb(options)	Build a client bound to a config + AI registry. Returns { ask, reload }.
client.ask(question, overrides?)	Resolve schema/model/dialect and run the pipeline. Overrides: schema, model, dialect, plus all ask() options.
AskDbClient / CreateAskDbOptions / AskOverrides	Types for the client, constructor options, and per-call overrides.

@askdb/ai

Optional AI provider registry and shared config helpers. Install this when you want AskDB to construct AI SDK language or embedding models from askdb.config.* / env maps. Pair it with a provider adapter package such as @askdb/ai-openai. Skip it when you already construct your own AI SDK model and pass it to ask().

npm install @askdb/ai

Key exports

Symbol	Purpose
createAiRegistry	Register provider adapters and build language or embedding models.
registry.resolveAiConfig(env) / registry.resolveEmbeddingConfig(env)	Resolve provider config from env without constructing a model. These are methods on the registry returned by createAiRegistry, not standalone exports.
resolveBaseConfig	Low-level helper — resolves a provider’s base config object from an env map. Used internally by adapters.
withEmbeddingProviderOptions	Wraps embedding provider options; shared across adapters.
aiKeyMissingMessage	Shared human-readable missing-key guidance.

Provider adapters

Provider adapters own concrete AI SDK provider dependencies. Each adapter declares ai and @askdb/ai as peer dependencies — npm/pnpm install them automatically, but your app should depend on ai directly when you want to pin the version.

npm install @askdb/ai-openai
npm install @askdb/ai-azure
npm install @askdb/ai-google
npm install @askdb/ai-anthropic

Any provider that has a Vercel AI SDK package can be added as an adapter. Unknown ai.provider values require a registered adapter — first-party apps register openai, azure, foundry, google, and anthropic; for anything else, embed AskDB and register your own adapter, or use an OpenAI-compatible endpoint via the openai provider and a custom base URL.

@askdb/connectors

Connector provider registry — mirrors the @askdb/ai pattern for introspection. Each engine adapter exports a ConnectorProviderAdapter constant; @askdb/connectors wires them into a unified registry used by the CLI and apps. Install directly only when you are building a custom introspection flow.

npm install @askdb/connectors

Key exports

Symbol	Purpose
createConnectorRegistry(adapters)	Build a registry from a set of provider adapters.
ConnectorRegistry	Registry type — createConnector(provider, config), getTemplates(provider).
ConnectorProviderAdapter	The adapter shape each engine package exports.

@askdb/config

Optional config bootstrap: .env and askdb.config.* discovery, type-safe defineConfig, and a runtime snapshot accessor.

npm install @askdb/config

Key exports

Symbol	Purpose
defineConfig(config)	Type-safe config builder.
bootstrapAskDbEnv(options)	Load .env + askdb.config.* and install the runtime snapshot.
getAskDbRuntimeConfig()	Read the runtime snapshot (preferred over process.env).
discoverAskDbConfigPath()	Programmatic config-file discovery.
env, requiredEnv	Typed env-var accessors.

Engine adapters

Each engine package ships the introspection connector for its engine, any catalog SQL templates, and a re-export of that engine’s dialect constant. The dialect specs themselves (SQL generation + validation rules) live in @askdb/core — ask() needs only the dialect id, no engine package.

@askdb/postgres

npm install @askdb/postgres

PostgreSQL dialect, connector, catalog SQL templates, and an optional pg-based catalog query runner for live introspection. Pass dialect: "postgres" to ask().

@askdb/mysql

npm install @askdb/mysql

MySQL dialect and introspection. Pass dialect: "mysql" to ask().

@askdb/sqlite

npm install @askdb/sqlite

SQLite dialect and introspection. Works with embedded file-backed databases. Pass dialect: "sqlite" to ask().

@askdb/sqlserver

npm install @askdb/sqlserver

SQL Server (T-SQL) dialect and introspection. Pass dialect: "sqlserver" to ask().

Introspection

@askdb/introspect

The engine-agnostic introspection contract and the schema-directory writer. Use directly only when you’re calling introspection from your own code — the CLI wraps this for you.

npm install @askdb/introspect

@askdb/prisma

File-only connector that reads .prisma schema files and produces AskDB physical metadata — no live database needed. Pair with an engine adapter for SQL generation at runtime.

npm install @askdb/prisma @askdb/introspect

See the Prisma integration guide.

Authoring

@askdb/studio

Browser-based schema-authoring UI. The CLI’s askdb studio command lazy-imports this package.

npm install @askdb/studio

@askdb/tui

Terminal-based schema-authoring UI. The CLI’s askdb enrich command lazy-imports this package.

npm install @askdb/tui

@askdb/enrich

Headless schema-authoring helpers shared by Studio and TUI. Use directly when building a custom authoring surface.

npm install @askdb/enrich

Retrieval

@askdb/rag

Chunks the schema artifact, indexes it in a vector store, and retrieves relevant chunks per question. Use with ask()’s retriever option for large schemas.

npm install @askdb/rag

Key exports

Symbol	Purpose
buildSchemaIndex({ schema, store, embedder, ... })	Chunk + embed + upsert a schema artifact; returns { retriever, stats, chunks }.
createAiSdkEmbedder({ model }) / createOpenAiEmbedder(...)	Wrap an AI SDK embedding model (or raw OpenAI) as the embedder.
createRetriever({ store, embedder })	Build the retriever passed to ask().
createPgvectorStore	The pgvector store factory.

Ships a small CLI binary askdb-rag (notably askdb-rag setup-store for pgvector provisioning). See RAG for large schemas.

Service surfaces

@askdb/http-api

Minimal HTTP server wrapping ask(). Two endpoints (/health, POST /ask), designed to sit behind your gateway.

npm install @askdb/http-api

Key exports

Symbol	Purpose
createAskDbHttpServer(options)	Build the server.
AskHttpRequest / AskHttpSuccessResponse / AskHttpErrorResponse	Request and response types.

See the HTTP API reference for endpoints and error codes.

askdb (CLI)

The askdb binary. Ships as a normal npm package — install for local development, demos, and CI.

npm install askdb

See the CLI reference.

Dependency direction

Package	Depends on
@askdb/postgres, @askdb/mysql, @askdb/sqlite, @askdb/sqlserver	@askdb/core, @askdb/connectors
@askdb/prisma	@askdb/introspect, @askdb/connectors
@askdb/connectors	@askdb/introspect
@askdb/ai	AI SDK core package (ai)
@askdb/ai-openai, @askdb/ai-azure, @askdb/ai-google, @askdb/ai-anthropic	@askdb/ai + the matching AI SDK provider package
@askdb/enrich, @askdb/rag	@askdb/core
@askdb/tui, @askdb/studio	@askdb/enrich (+ @askdb/rag when used)
@askdb/http-api	@askdb/core (+ engine adapter)
askdb (CLI)	All of the above (lazy-imported per command)

Reusable packages stay small and layered. First-party surfaces (CLI, Studio, TUI, HTTP API) compose them.

What to install — by use case

Just trying it outaskdb alone is enough to introspect, enrich, and ask from the CLI.Embedding in a Node service@askdb/core + one engine adapter + a model provider.Standing up an HTTP serviceAdd @askdb/http-api on top of the embedding install.Working with a large schemaAdd @askdb/rag and a vector store (pgvector recommended).

Read next

CLI referenceThe askdb binary in detail.HTTP API referenceEndpoints, request and response shapes.Configuration referencedefineConfig and the env-var matrix.