typed-sql

Write SQL. Read TypeScript.

typed-sql checks SQL against a snapshot of your database and infers result rows and parameter types. Keep your SQL, database driver, connections and migrations.

import { sql } from "@typed-sql/postgres";

export const accountById = (accountId: bigint) => sql`
  SELECT account.id, account.email, account.status
  FROM users AS account
  WHERE account.id = ${accountId}
`;

With the corresponding schema, the compiler proves:

Query<
  { id: bigint; email: string; status: "active" | "suspended" },
  readonly [bigint]
>

Interpolated values become driver parameters. Unsupported or ambiguous SQL receives a diagnostic or unknown; typed-sql does not guess a safe-looking type.

Try your first query

The SQLite quickstart creates a local database and takes a query through checking and execution without a server. Existing applications can start with the PostgreSQL or MySQL quickstart.

The development loop is:

pnpm exec typed-sql generate
pnpm exec typed-sql check --project tsconfig.json --show-types

The project check follows query types across imports and checks their application consumers. It uses the application's supported TypeScript 7 compiler and keeps source files unchanged. Use it as the project's typechecking step before your transpiler or bundler.

Exact editor hovers use the optional experimental language server. Ordinary TypeScript declarations remain conservative and can show Query<unknown> without analysis. See compiler and editor workflow.

Keep your database stack

• SQL stays SQL. Use supported joins, CTEs, aggregates, window functions, DML and dialect syntax.
• Types follow the query. Infer result rows, nullability and ordered parameter tuples from schema evidence.
• Connections stay yours. Reuse an existing pool or choose an explicit execution adapter.
• Composition is explicit. Use sql.fragment, sql.empty and sql.ident for structure; ordinary values remain parameters.

Compose conditional and repeated SQL, inspect database type mappings, or explore the runnable applications.

Editor setup

Install typed-sql for VS Code and follow the editor setup guide for the native SDK and language server. Zed and other LSP clients use the same optional server.

The stable compiler path uses TypeScript 7.0.2. The experimental editor backend owns its isolated TypeScript 7.1 beta; applications do not replace their compiler to enable editor hovers. Supported runtimes, databases and exact versions.

Go further

Documentation · Query API · JSON and portable adapters · Build and test integrations · SQL files · Inference and safety

Add production controls when needed: drift detection, manifests, live verification, optimizer-plan review, migration compatibility and observability are independent of the first-query setup.

For contributions and maintainer procedures, read CONTRIBUTING.md.

MIT © typed-sql contributors