Versioning and stability

Reference · Versioning

AskDB publishes two sets of packages. The 1.0 set shares one version and follows semantic versioning. The 0.x set keeps room to change. This page lists which package is in which set, what a version bump means for each, and which npm dist-tag to install from.

Packages and version lines

Set	Packages	Version now	Shares one version
1.0 set	`askdb`, `@askdb/ai`, `@askdb/client`, `@askdb/config`, `@askdb/core`, `@askdb/http-api`, `@askdb/introspect`, `@askdb/mysql`, `@askdb/postgres`, `@askdb/prisma`, `@askdb/sqlite`, `@askdb/sqlserver`	`1.0.0-rc.N`	Yes. Every release publishes all 12 at the same version, even a package that didn’t change.
0.x set	`@askdb/studio`, `@askdb/enrich`, `@askdb/rag`	`0.2.0-rc.N`	No. Each package moves on its own.

Keep every AskDB package in your app on the same release, and upgrade them in one step. Upgrade AskDB shows the command.

What a version bump means

Change	1.0 set	0.x set
Breaking change	Major, for all 12 (`2.0.0`)	Minor (`0.3.0`)
New feature	Minor, for all 12	Minor
Fix	Patch, for all 12	Patch

A breaking change is any of these:

An export is removed or renamed, or a package’s exports map closes a path that worked.
The Node floor (engines.node, >=22.23.4 today) goes up.
An accepted input or a default changes, so code that worked before fails or behaves differently.
The schema artifact format changes incompatibly. From 1.0.0 on, that ships as a new format version, such as Schema v3. Until then, Schema v2 can still change in a release candidate (see Release candidates).

Experimental surfaces in the 1.0 set

A minor release of the package that owns one can change it (ADR 0030).

Package	Experimental surface
`@askdb/config`	The `studio` and `rag` blocks of `defineConfig()`, with the types and environment variables that feed them
`askdb`	The `askdb studio`, `askdb enrich`, `askdb bundle` and `askdb rag` commands
`askdb`	The `--rag-store`, `--pgvector-env` and `--studio-execute` flags of `askdb init`, and the `rag` and `studio` sections it writes
`@askdb/config`	The `@askdb/config/scaffold` entry point: the scaffold planner and the package-manager helpers that `askdb init` and Studio’s setup wizard share
`@askdb/client`	The `@askdb/client/charts` entry point: `classifyResult()`, `planChart()` and `validateChartSpec()`, which plan a chart from a query’s question, masked SQL and column kinds, never its rows

Release candidates

1.0.0-rc.1 freezes the public API of the 1.0 set. Later release candidates fix bugs.
The schema artifact format is the exception. Schema v2 can still change before 1.0.0 stable. Such a change ships in a release candidate with an upgrade note.
A fix that asks something of your app gets its own section in Upgrade notes by release.
1.0.0 follows the last release candidate. The 0.x set becomes 0.2.0 at the same time.

npm dist-tags

Dist-tag	Points at
`latest`	The newest release. Until `1.0.0`, that is the newest release candidate.
`beta`, `rc`	Not published. The stale `beta` tag was removed.

From 1.0.0 on, a prerelease publishes under its own tag (such as beta), and latest stays on the newest stable release.