rawsql-ts

A monorepo for rawsql-ts: a SQL-first toolkit for parsing, testing, inspecting, and evolving database applications while keeping raw SQL as a first-class asset.

By parsing SQL into abstract syntax trees, rawsql-ts enables type-safe query building, static validation, and transparent result mapping — all while preserving the expressiveness and control of handwritten SQL. AST-based rewriting also powers Zero Table Dependency (ZTD) testing, which transforms application queries to run against in-memory fixtures instead of physical tables, enabling deterministic unit tests without database setup overhead. The repo additionally covers AST-based impact analysis, deterministic test evidence, schema documentation, and ztd-cli workflows for inspection and SQL artifact generation.

The ztd init scaffold now starts from a feature-first layout under src/features/<feature>/ and includes src/features/smoke/ as the removable teaching feature. Shared feature seams live under src/features/_shared/, driver-neutral runtime contracts under src/libraries/, driver or sink bindings under src/adapters/<tech>/, shared verification seams under tests/support/, and tool-managed assets under .ztd/. src/catalog may still exist as internal support, but it is no longer the user-facing standard location.

Use this section as the shortest repo-level map. It is intentionally brief: package details live under each package README, while repo-level workflows point to the CLI or guide that owns them.

These capabilities are important at the repo level even though they are mostly exposed through ztd-cli commands rather than standalone packages.

Package	Version	Description
rawsql-ts		SQL parser and AST transformer. Zero dependencies, browser-ready.
@rawsql-ts/sql-grep-core		Low-dependency SQL usage analysis engine for AST-based schema impact checks.

Package	Version	Description
@rawsql-ts/sql-contract		Type-safe result mapping for raw SQL queries. Driver and validator agnostic.

Package	Version	Description
@rawsql-ts/executor		Optional helper for connection lifecycle and transaction scope when you want less boilerplate while keeping execution ownership in the caller.

Package	Version	Description
@rawsql-ts/testkit-core		Fixture-backed CTE rewriting and schema validation engine. Driver-agnostic ZTD foundation.
@rawsql-ts/testkit-postgres		Postgres-specific CTE rewriting and fixture validation. Works with any executor.
@rawsql-ts/adapter-node-pg		Adapter connecting pg (node-postgres) to testkit-postgres.
@rawsql-ts/testkit-sqlite		SQLite-specific CTE rewriting and fixture validation. In-memory testing with better-sqlite3.

Package	Version	Description
@rawsql-ts/test-evidence-core		Core schema and storage model for deterministic test evidence.
@rawsql-ts/test-evidence-renderer-md		Markdown renderer for saved test evidence reports.

Package	Version	Description
@rawsql-ts/ddl-docs-cli		CLI that generates Markdown table definition docs from DDL files.
@rawsql-ts/ddl-docs-vitepress		Scaffold generator for VitePress-based database schema documentation sites.

Package	Version	Description
@rawsql-ts/ztd-cli		SQL-first CLI for ZTD workflows, schema inspection, and migration SQL artifact generation.

For the machine-readable CLI surface, see ztd-cli Agent Interface and ztd-cli Describe Schema.

rawsql-ts (core)
├─ @rawsql-ts/sql-grep-core
├─ @rawsql-ts/sql-contract
├─ @rawsql-ts/executor
├─ @rawsql-ts/testkit-core
│  ├─ @rawsql-ts/testkit-postgres
│  │  └─ @rawsql-ts/adapter-node-pg
│  └─ @rawsql-ts/testkit-sqlite
├─ @rawsql-ts/ddl-docs-cli
│  └─ @rawsql-ts/ddl-docs-vitepress
└─ @rawsql-ts/ztd-cli
   └─ uses @rawsql-ts/sql-grep-core for `query uses`

npm install rawsql-ts

See the Core Package Documentation for usage examples and API reference. For reusable AST-based impact analysis, see @rawsql-ts/sql-grep-core. For repo-level SQL lifecycle workflows, inspection commands, and ZTD project guidance, see @rawsql-ts/ztd-cli. Deterministic dogfooding spec: docs/dogfooding/DOGFOODING.md.

• SQL-first End-to-End Tutorial - Walk from DDL to ztd-config, model-gen, repository wiring, and the first passing smoke test in one focused path.
• Migration Repair Loop - Repair DDL, SQL, DTO, and migration artifacts with AI after the starter flow is green.

Treat each query as one unit: 1 SQL file / 1 QuerySpec / 1 repository entrypoint / 1 DTO.

Keep handwritten SQL assets close to each feature in src/features/<feature>/queries/<query>/ so the SQL, boundary contract, and query-local tests stay in one place.

Use this repo by treating DDL and SQL as source assets, and generated specs, repositories, and tests as downstream artifacts that must stay in sync.

Procedure: DDL -> SQL -> generate -> wire -> test.

For a step-by-step example, see the SQL-first tutorial above.

If you are using an AI coding agent, start with a short prompt that sets only the minimum project shape and domain language. You do not need to explain package-manager setup in that prompt.

Optional Docker helper:

If you want a local PostgreSQL 18 instance for ZTD tests, use a tiny compose file like this:

services:
  postgres:
    image: postgres:18
    environment:
      POSTGRES_USER: ztd
      POSTGRES_PASSWORD: ztd
      POSTGRES_DB: ztd
    ports:
      - "5432:5432"
    volumes:
      - ztd-postgres-data:/var/lib/postgresql/data

volumes:
  ztd-postgres-data:

Then run docker compose up -d and point ZTD_DB_URL at that database for the fixture-backed rewrite path.

• SQL pipeline / debug → ztd query plan <sql-file>
• Impact analysis → ztd query uses <target>
• SQL-first optional filters → ztd query sssql scaffold <sql-file> / ztd query sssql refresh <sql-file>
• Schema inspection → ztd ddl diff --url <target>

For the full routing guide and decision table, see SQL Tool Happy Paths.

For repo-level workflows, keep this boundary in mind:

• .env is the source of truth for the fixture-backed ZTD runtime inputs, and ZTD_DB_URL is the implicit database input used by ztd-cli
• DATABASE_URL is typically an application/runtime/deployment concern and is not read automatically by ztd-cli
• any non-ZTD database target must be supplied explicitly via --url or --db-*
• migration SQL artifacts may be generated by ztd-cli, but apply / deployment execution remains outside its ownership

This boundary exists for both AI-driven and human-driven workflows. It keeps test, inspection, and deployment concerns from silently collapsing into a single default database model.

Try rawsql-ts in your browser

MIT