Choose packages

Install one grammar for the database used by the application. Add the stable CLI as a development dependency, then select a database driver explicitly—grammar packages never install or own one.

Inspect a setup plan

typed-sql init prints a JSON setup plan without writing project files, importing configuration, installing dependencies, or connecting to a database:

pnpm exec typed-sql init --grammar postgres --dry-run
pnpm exec typed-sql init --cwd . --package apps/api --grammar mysql --editor vscode --json

Choose postgres, mysql, or sqlite explicitly. Workspace roots require --package to select an application. The planner detects package-manager declarations and lockfiles and refuses conflicting choices. Existing configuration and dependency ranges are preserved, not certified compatible. Proposed files, missing dependencies, scripts, and pending actions are separate fields.

An editor selection records prerequisites; it does not install an extension or claim the editor is ready. Supply a real schema snapshot before generation. init does not fabricate database metadata, execute lifecycle scripts, or grant workspace trust.

Prerequisites

typed-sql requires Node.js 22.11 or newer. The compiler uses an exact supported TypeScript version; check the current compatibility matrix before installing into an existing project.

PostgreSQL

pnpm add @typed-sql/core @typed-sql/postgres pg
pnpm add -D @typed-sql/cli typescript

Application code imports sql from @typed-sql/postgres. The optional runtime and introspection adapter is an explicit subpath at @typed-sql/postgres/pg and loads the application's pg package.

Continue with the PostgreSQL quickstart.

MySQL

pnpm add @typed-sql/core @typed-sql/mysql mysql2
pnpm add -D @typed-sql/cli typescript

Application code imports sql from @typed-sql/mysql. The adapter at @typed-sql/mysql/mysql2 loads the application's mysql2 package.

Continue with the MySQL quickstart.

SQLite

pnpm add @typed-sql/core @typed-sql/sqlite
pnpm add -D @typed-sql/cli typescript

Application code imports sql from @typed-sql/sqlite. The optional @typed-sql/sqlite/node-sqlite adapter uses the built-in node:sqlite module on supported Node versions, so there is no npm driver dependency.

Continue with the SQLite quickstart.

Optional packages

Add these only when their capability is used:

Package	Use it for	Stability
@typed-sql/opentelemetry and @opentelemetry/api	Translate neutral database observations into application-owned spans	Stable
pg-cursor	Cursor-backed PostgreSQL streams	Application dependency
@typed-sql/language-server	Exact hovers and SQL editor features	Experimental

The language server owns its isolated TypeScript preview internally. It is not required for generation, checking, or execution. See Compiler and editor workflow.

Dependency boundary

Keep driver packages in application dependencies even when a dialect happens to use their types. This makes the selected protocol, connection configuration, pool, codecs, and lifecycle visible to the application. Compare direct driver use and adapters.