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 providers are built into @askdb/ai, which loads the matching AI SDK package (@ai-sdk/openai, @ai-sdk/azure, @ai-sdk/google, @ai-sdk/anthropic) on first use. @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 ai

pnpm add @askdb/core ai

yarn add @askdb/core ai

ai (the Vercel AI SDK) is a required peer dependency of @askdb/core, with the range ^6.0.0 || ^7.0.51 (AI SDK 6, or 7.0.51 and later). Your app owns its version: ask() receives a model your app constructs, so core uses your app’s ai instead of bundling its own — upgrading AskDB never forces an AI SDK upgrade on the rest of your app. Build the model with an AI SDK provider package (for example @ai-sdk/openai), or through the config-driven path (@askdb/ai and @askdb/client), which currently requires AI SDK 7.

Every package on this page that depends on @askdb/core also needs ai installed, even if you only introspect and never generate SQL. That covers @askdb/client, the engine adapters, @askdb/introspect, @askdb/prisma, @askdb/enrich and @askdb/rag. Core loads ai when it is imported. npm 7+ and pnpm install the missing peer for you. Yarn doesn’t, so the install commands on this page list ai explicitly.

Key exports

Symbol	Purpose
`ask(options)`	The main pipeline. Returns checked SQL. See full API reference.
`loadSchema(path)`	Load a schema artifact from a directory, bundle, or `schema.json`.
`validateTenantScope` / `resolveTenantSql`	Tenant-scope validation and placeholder binding.
`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.
`AskUsage`	Token usage type returned in `AskPipelineResult`.

See the @askdb/core API reference for the full option and return-type documentation.

`@askdb/client`

Config-aware facade over @askdb/core. createAskDb() resolves the schema, model, and dialect from your askdb.config.* (with every @askdb/ai built-in provider registered by default), 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/core @askdb/config ai @ai-sdk/openai

pnpm add @askdb/client @askdb/core @askdb/config ai @ai-sdk/openai

yarn add @askdb/client @askdb/core @askdb/config ai @ai-sdk/openai

Key exports

Symbol	Purpose
`createAskDb(options)`	Build a client bound to a config. Registers every built-in AI provider by default; `providers: ["openai"]` restricts the set, adapter objects add custom providers, or pass a prebuilt `registry`. Returns `{ ask, reload }`. Options include `unknownDialect: "throw" \| "fallback-postgres"` for artifacts recorded by an unrecognized provider.
`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.
`SchemaLoadError` / `SchemaNotConfiguredError` / `ModelNotConfiguredError` / `DialectNotSupportedError`	Typed errors for the resolution steps — catch these to map failures to your own error handling.

See the @askdb/client API reference for the full option documentation.

`@askdb/ai`

AI provider registry with built-in providers for OpenAI, Azure OpenAI / Microsoft Foundry, Google Gemini, Anthropic, and the Vercel AI Gateway. @askdb/client depends on it and builds the registry for you. Import it yourself to build a model object outside the client (createAiRegistry().createLanguageModelFromEnv(...)), to restrict or extend the provider set, or to share one registry across several clients.

npm install @askdb/ai ai

pnpm add @askdb/ai ai

yarn add @askdb/ai ai

Key exports

Symbol	Purpose
`createAiRegistry(providers?)`	Build a registry and create language or embedding models from it. No argument: every built-in provider. Or pass built-in names (`["openai"]`) and/or `AiProviderAdapter` objects.
`BUILTIN_AI_PROVIDERS`	Table of built-in providers: names, aliases, env vars, default models, and the SDK package each needs.
`openaiProvider`, `azureProvider`, `googleProvider`, `anthropicProvider`, `gatewayProvider`	The built-in adapters, if you want to pass them as objects.
`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 an embedding model so `dimensions`/`user` reach the provider; an optional mapper renames them to the provider’s own settings (e.g. Gemini’s `outputDimensionality`). Shared across adapters.
`aiKeyMissingMessage`	Shared human-readable missing-key guidance.

Provider SDKs

Each built-in provider loads its AI SDK package lazily. These packages are optional peer dependencies of @askdb/ai, so install the one for the provider your config selects. If it’s missing, model creation fails with Provider '<name>' requires the optional peer dependency @ai-sdk/<name>. Install it: npm i @ai-sdk/<name>. ai itself is a required peer of @askdb/ai: npm and pnpm install it automatically, but depend on ai directly when you want to pin the version. AskDB raises its ai floor only when it needs a newer version or a security fix, and that release’s changelog says which.

Any 4.x release of each @ai-sdk/* package works (the peer range is ^4.0.0), so AskDB doesn’t force a provider SDK upgrade. @askdb/client declares the same optional peers and passes them through to @askdb/ai, so with strict installs (Yarn Plug’n’Play) install the SDK in the package that depends on @askdb/client or @askdb/ai, as the install lines above do. Under Plug’n’Play the AI SDK also needs zod installed next to it (its own peer dependency). If you bundle your app, esbuild builds without the SDKs you didn’t install, and a missing one fails only when its provider first builds a model. webpack 5 stops with Module not found for each missing @ai-sdk/* package: install them, or list the ones you don’t use in externals (with ESM output, use externalsType: "module" and the bare package names):

// webpack.config.js: list the @ai-sdk/* packages you don't install.
module.exports = {
  // ...
  externals: {
    "@ai-sdk/anthropic": "commonjs @ai-sdk/anthropic",
    "@ai-sdk/azure": "commonjs @ai-sdk/azure",
    "@ai-sdk/google": "commonjs @ai-sdk/google",
  },
};

npm install @ai-sdk/openai

pnpm add @ai-sdk/openai

yarn add @ai-sdk/openai

npm install @ai-sdk/anthropic

pnpm add @ai-sdk/anthropic

yarn add @ai-sdk/anthropic

npm install @ai-sdk/google

pnpm add @ai-sdk/google

yarn add @ai-sdk/google

npm install @ai-sdk/azure

pnpm add @ai-sdk/azure

yarn add @ai-sdk/azure

Nothing extra: the gateway provider ships with ai.

The CLI, Studio, and the HTTP API already include all four SDKs. Unknown ai.provider values require a registered adapter. The built-ins are openai, azure (aliases azure-openai, foundry), google, anthropic, and gateway. For anything else, embed AskDB and pass your own AiProviderAdapter to createAiRegistry() or createAskDb({ providers }), or use an OpenAI-compatible endpoint via the openai provider and a custom base URL.

`@askdb/config`

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

npm install @askdb/config

pnpm add @askdb/config

yarn add @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.
`isAskDbDebugEnabled()`	`true` when the `ASKDB_DEBUG` shell variable is `1` or `true`; works without a loaded config.

For tools that write a new askdb.config.ts, the @askdb/config/scaffold entry point exports renderAskDbAiConfigScaffold(input). It renders the config’s ai block (the provider connection in ai.providerConfig, plus ai.language.model read from an env var when one is given) and lists the env vars that block reads. askdb init and Studio’s setup wizard use it. Your own askdb.config.ts never needs it.

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. Its connector provider adapter parses the engine’s connection strings into display-safe parts, so registry.connectionLabel() and the sourceLabel from registry.resolveConnection() turn postgres://app:S3cret@db:5432/app into postgres://db:5432/app, and a string the engine can’t parse cleanly into configured <engine> connection. The label never contains a user name, password, or query string. 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 ai

pnpm add @askdb/postgres ai

yarn add @askdb/postgres ai

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 ai

pnpm add @askdb/mysql ai

yarn add @askdb/mysql ai

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

`@askdb/sqlite`

npm install @askdb/sqlite ai

pnpm add @askdb/sqlite ai

yarn add @askdb/sqlite ai

SQLite dialect, connector, catalog SQL templates, and an optional better-sqlite3-based catalog query runner for live introspection. Works with embedded file-backed databases. Pass dialect: "sqlite" to ask().

`@askdb/sqlserver`

npm install @askdb/sqlserver ai

pnpm add @askdb/sqlserver ai

yarn add @askdb/sqlserver ai

SQL Server (T-SQL) dialect, connector, catalog SQL templates, and an optional mssql-based catalog query runner for live 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 ai

pnpm add @askdb/introspect ai

yarn add @askdb/introspect ai

To get the exact schema.json bytes without writing anything (a preview or a drift check), call renderSchemaV2Body(result.schema, { schemaId, provider: result.provider, existingArtifactDir }). Its options type is RenderBodyOptions (schemaId, optional provider and existingArtifactDir), and it returns a RenderBodyResult: { json, body, warnings }, the Schema v2 document, the exact file contents and the merge warnings. It applies the same merge introspect() does when writing (human-set sensitive flags carried over from an existing artifact), and backs askdb introspect --out, --print and --diff. isSchemaV2Json(value) is the check it applies to an existing schema.json before merging (the shape the merge reads: version, schema id, table and column ids, names and types, and boolean sensitive flags; not every field of Schema v2), for callers that need to decide up front.

It also exports the connector provider registry, which config-driven hosts use to pick an engine by id. Each engine package exports a ConnectorProviderAdapter (postgresConnectorProvider, mysqlConnectorProvider, sqliteConnectorProvider, sqlServerConnectorProvider, prismaConnectorProvider). Provider ids are open strings, so a third-party engine can register its own id.

Symbol	Purpose
`introspect(input, renderOptions, { connector })`	Run a connector and write the schema directory.
`createConnectorRegistry(adapters)`	Build a registry from provider adapters. Returns `{ hasProvider, providers, createConnector, getTemplates, resolveConnection, connectionLabel }`.
`registry.resolveConnection(provider, { explicit?, runtime, surface? })`	Let the engine’s adapter merge explicit values (for example `--url`) with AskDB runtime config (`getAskDbRuntimeConfig()`). Returns `{ ok, connection, sourceLabel }` or `{ ok: false, error }`. `sourceLabel` is `registry.connectionLabel(provider, connection)`, so it is safe to display for every adapter.
`registry.connectionLabel(provider, { url?, fromExport?, schemaPath? })`	A label that is safe to display or log, for any adapter: the registry builds it with `formatConnectionLabel` from the parts the adapter’s `connectionLabelParts` hook parses (host, port, database, or a file path). A connection that doesn’t parse cleanly, or an adapter without the hook, gets `configured <engine> connection`.
`ConnectorConnection`	The connection `connectionLabel` and an adapter’s `connectionLabelParts` read: `{ url?, fromExport?, schemaPath? }`.
`ConnectionLabelParts`, `formatConnectionLabel(engine, parts)`, `parseConnectionUrl(input, schemes)`	From `@askdb/introspect/kit`: what `connectionLabelParts` returns (`{ host?, port?, database? }`, or `{ file }`), the allowlisted label builder, and a strict standard-URL parser for engines whose driver has no parser to reuse. The built-in engines don’t use the parser: Postgres takes its parts from `pg-connection-string` and SQL Server’s ADO.NET strings from `@tediousjs/connection-string`, the parsers their drivers use; MySQL reads a `mysql://` URL with the mapping `mysql2` applies; SQL Server’s `mssql://` and Prisma-style `sqlserver://` URLs go through `@askdb/sqlserver`’s own connection parser; SQLite labels the file path.
`ConnectorProviderAdapter`	The adapter shape: `createConnector`, plus optional `resolveConnection`, `connectionLabelParts`, `getTemplates`.
`ConnectorProviderAdapters`	What `createConnectorRegistry` takes: an array of adapters, or an object keyed by provider id.
`ConnectorProviderId`, `BuiltInConnectorProvider`, `BUILT_IN_CONNECTOR_PROVIDERS`	A provider id is any string; `BuiltInConnectorProvider` is the union of the first-party ids, which `BUILT_IN_CONNECTOR_PROVIDERS` lists (`postgres`, `prisma`, `mysql`, `sqlite`, `sqlserver`).
`connectorProviderMissingMessage(provider)`	The error text for an unregistered provider: `Install @askdb/<id>` for a built-in id, otherwise the package that provides it.
`ConnectorConfig`, `ConnectorResult`	What `createConnector` takes (`provider`, the connection fields, `filters`, `schemaId`) and returns (`{ connector, input, mode }`).
`ConnectorConnectionRequest`, `ConnectorRuntimeConfig`	What `resolveConnection` takes: `{ explicit?, runtime, surface? }`, where `runtime` is `getAskDbRuntimeConfig()` (typed structurally: `introspection` and optional `structured`).
`ConnectorConnectionResult`, `ConnectorConnectionResolution`	What an adapter’s `resolveConnection` hook returns (`{ ok, connection }` or `{ ok: false, error }`), and what `registry.resolveConnection` returns (the same, plus `sourceLabel`).

The @askdb/introspect/kit subpath holds the shared helpers the engine packages are built on — optional-driver loading (createOptionalDriverLoader, isDriverInstalled, missingDriverMessage for the first-party engines’ install hint, and rethrowDriverImportError to chain on your driver’s import() so bundlers treat it as optional), the live-catalog adapter builder (defineLiveConnectorProvider, with LiveConnectorProviderSpec and LiveCatalogInput), runtimeIntrospectionString for reading an engine’s string from AskDB runtime config, table-glob filters (compileTableFilters, ambiguousFilterWarnings), Schema v2 ids (makeTableId, makeColumnId), catalog-row folding (rowsToRecords, groupBy, buildOrderedGroups, byName, sortedUnique, mapFkAction), and connection labels (formatConnectionLabel, parseConnectionUrl). Its types are OptionalDriverSpec (what createOptionalDriverLoader takes), OptionalDriverLoader (what it returns), DriverLoadOptions ({ resolveFrom? }), GlobMatcher (what compileTableFilters returns), RowsToRecordsOptions and ConnectionLabelParts. Import it when you write a connector for a new engine.

`@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 ai

pnpm add @askdb/prisma @askdb/introspect ai

yarn add @askdb/prisma @askdb/introspect ai

See the Prisma integration guide.

Authoring

`@askdb/studio`

Browser-based schema-authoring UI. The CLI’s askdb studio command lazy-imports this package. Schema browsing, enrichment, and SQL generation do not require a database driver. The Query Playground’s live execute feature supports Postgres, MySQL, SQLite, and SQL Server — each requires its own optional peer driver package.

npm install @askdb/studio

pnpm add @askdb/studio

yarn add @askdb/studio

Execute provider	Package
Postgres	`pg` (optional peer)
MySQL	`mysql2` (optional peer)
SQLite	`better-sqlite3` (optional peer)
SQL Server	`mssql` (optional peer)

Install only the package for your dialect. The execute provider is inferred from your active introspection provider unless overridden with studio.execute.provider.

@askdb/studio lists all four packages as dev dependencies for local package development and CI type-checking. This is not a requirement for your application — only install the driver you need at runtime.

See Studio — driver packages and Configuration reference — Studio execute for setup details.

`@askdb/enrich`

Headless schema-authoring helpers used by Studio. Use directly when building a custom authoring surface.

npm install @askdb/enrich ai

pnpm add @askdb/enrich ai

yarn add @askdb/enrich ai

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. Always install ai: @askdb/rag depends on @askdb/core, which loads ai when it is imported, even with a custom embedder or the in-memory or file store. Install @ai-sdk/openai and pg only if your embedder and vector store use them; they are optional peers. Their AI SDK 7 floors (ai ^7.0.51, @ai-sdk/openai ^4.0.29) move the same way as the adapters’ ai floor; the AI SDK 6 floors (^6.0.0, ^3.0.0) move only on purpose, with the AI SDK 6 install smoke’s pins.

npm install @askdb/rag ai

pnpm add @askdb/rag ai

yarn add @askdb/rag ai

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.
`detectEmbeddingDimensions(embedder)`	Learn an embedder’s vector width with one short embedding call, for a new pgvector table.
`aiSdkEmbedderId({ provider, model, dimensions })`	The `embedderId` Studio and `askdb rag` record for an `ai.embedding` model, so a host can share their indexes.
`loadChunkerSourcesFromDir(path)`	Load a schema directory into chunker format (includes markdown).

The command line for it is the askdb package’s askdb rag, with three commands — index, query, and setup-store (pgvector provisioning). The askdb-rag binary @askdb/rag used to run them only points there until 1.0. See RAG for large schemas.

See the @askdb/rag API reference for the full option and type documentation.

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

pnpm add @askdb/http-api

yarn add @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

pnpm add askdb

yarn add askdb

See the CLI reference.

Dependency direction

Package	Depends on
`@askdb/core`	AI SDK core package (`ai`, AI SDK 6 or 7) as a required peer
`@askdb/introspect`	`@askdb/core`
`@askdb/postgres`, `@askdb/mysql`, `@askdb/sqlite`, `@askdb/sqlserver`	`@askdb/core`, `@askdb/introspect`
`@askdb/prisma`	`@askdb/introspect`
`@askdb/ai`	AI SDK core package (`ai`); `@ai-sdk/*` provider packages as optional peers
`@askdb/enrich`, `@askdb/rag`	`@askdb/core`
`@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, 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/client + @askdb/core + @askdb/config + ai + an AI SDK provider package such as @ai-sdk/openai.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).

Removed packages

These packages were removed before 1.0 (#347). Their last versions stay on npm, so existing installs keep working, but they get no fixes. If your app still imports one, switch to its replacement.

Removed package	Last version	Use instead
`@askdb/ai-openai`	`1.0.0-beta.8`	`@askdb/ai` and `@ai-sdk/openai`
`@askdb/ai-azure`	`1.0.0-beta.8`	`@askdb/ai` and `@ai-sdk/azure`
`@askdb/ai-google`	`1.0.0-beta.8`	`@askdb/ai` and `@ai-sdk/google`
`@askdb/ai-anthropic`	`1.0.0-beta.6`	`@askdb/ai` and `@ai-sdk/anthropic`
`@askdb/connectors`	`0.1.0-beta.9`	`@askdb/introspect` for the connector registry and its types, and `@askdb/introspect/kit` for `formatConnectionLabel` and `parseConnectionUrl`

The @askdb/ai-* packages only re-exported @askdb/ai’s built-in providers. createAskDb({ config }) and createAiRegistry() register every built-in provider, so drop providers: [openaiProvider], or pass names such as providers: ["openai"] to restrict the set. openaiProvider, azureProvider, googleProvider and anthropicProvider are exported from @askdb/ai. From @askdb/connectors, CONNECTOR_PROVIDERS is now BUILT_IN_CONNECTOR_PROVIDERS, and ConnectorProvider is now ConnectorProviderId.

Package reference

Core

@askdb/core

@askdb/client

@askdb/ai

Provider SDKs

@askdb/config

Engine adapters

@askdb/postgres

@askdb/mysql

@askdb/sqlite

@askdb/sqlserver

Introspection

@askdb/introspect

@askdb/prisma

Authoring

@askdb/studio

@askdb/enrich

Retrieval

@askdb/rag

Service surfaces

@askdb/http-api

askdb (CLI)

Dependency direction

What to install — by use case

Removed packages

Read next

`@askdb/core`

`@askdb/client`

`@askdb/ai`

`@askdb/config`

`@askdb/postgres`

`@askdb/mysql`

`@askdb/sqlite`

`@askdb/sqlserver`

`@askdb/introspect`

`@askdb/prisma`

`@askdb/studio`

`@askdb/enrich`

`@askdb/rag`

`@askdb/http-api`

`askdb` (CLI)