{"id":45905821,"url":"https://github.com/mk3008/rawsql-ts","last_synced_at":"2026-05-22T16:00:57.487Z","repository":{"id":282239477,"uuid":"946650796","full_name":"mk3008/rawsql-ts","owner":"mk3008","description":"SQL-first lifecycle toolkit for testing, inspecting, and evolving database applications.","archived":false,"fork":false,"pushed_at":"2026-04-01T10:06:49.000Z","size":13903,"stargazers_count":29,"open_issues_count":25,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-01T11:42:03.720Z","etag":null,"topics":["ast","code-generation","database-tooling","raw-sql","schema-evolution","sql","sql-first","sql-parser","testing","typescript"],"latest_commit_sha":null,"homepage":"https://mk3008.github.io/rawsql-ts/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mk3008.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["mk3008"]}},"created_at":"2025-03-11T13:20:24.000Z","updated_at":"2026-04-01T10:06:52.000Z","dependencies_parsed_at":"2025-04-15T12:44:42.990Z","dependency_job_id":"e6019027-4aed-4f41-8021-15ee18144641","html_url":"https://github.com/mk3008/rawsql-ts","commit_stats":null,"previous_names":["mk3008/ts-sample","mk3008/carbunqlex-ts","mk3008/rawsql-ts"],"tags_count":101,"template":false,"template_full_name":null,"purl":"pkg:github/mk3008/rawsql-ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk3008%2Frawsql-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk3008%2Frawsql-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk3008%2Frawsql-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk3008%2Frawsql-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mk3008","download_url":"https://codeload.github.com/mk3008/rawsql-ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk3008%2Frawsql-ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292110,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ast","code-generation","database-tooling","raw-sql","schema-evolution","sql","sql-first","sql-parser","testing","typescript"],"created_at":"2026-02-28T02:43:34.645Z","updated_at":"2026-05-22T16:00:57.467Z","avatar_url":"https://github.com/mk3008.png","language":"TypeScript","funding_links":["https://github.com/sponsors/mk3008"],"categories":[],"sub_categories":[],"readme":"# rawsql-ts\n\n![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)\n\nA 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.\n\nBy 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.\n\nThe `ztd init` scaffold now starts from a feature-first layout under `src/features/\u003cfeature\u003e/` and includes `src/features/smoke/` as the removable teaching feature.\nShared feature seams live under `src/features/_shared/`, driver-neutral runtime contracts under `src/libraries/`, driver or sink bindings under `src/adapters/\u003ctech\u003e/`, shared verification seams under `tests/support/`, and tool-managed assets under `.ztd/`.\n`src/catalog` may still exist as internal support, but it is no longer the user-facing standard location.\n\n\u003e [!Note]\n\u003e This project is currently in beta. APIs may change until the v1.0 release.\n\n## Capability Index\n\nUse 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.\n\n### Packaged Capabilities\n\n| Capability | Primary surface | Start here |\n|------------|-----------------|------------|\n| SQL parsing and AST rewriting | `rawsql-ts` | [packages/core](./packages/core) |\n| SQL impact analysis / grep | `@rawsql-ts/sql-grep-core` | [packages/sql-grep-core](./packages/sql-grep-core) |\n| Execution helpers | `@rawsql-ts/executor` | [packages/executor](./packages/executor) |\n| Production SQL driver adapter primitives | `@rawsql-ts/driver-adapter-core` | [packages/drivers/driver-adapter-core](./packages/drivers/driver-adapter-core) |\n| ZTD fixture rewriting and testkits | `@rawsql-ts/testkit-*` | [packages/testkit-core](./packages/testkit-core) |\n| Test evidence storage and rendering | `@rawsql-ts/test-evidence-*` | [packages/test-evidence-core](./packages/test-evidence-core) |\n| Schema documentation generation | `@rawsql-ts/ddl-docs-*` | [packages/ddl-docs-cli](./packages/ddl-docs-cli) |\n| ZTD project scaffolding and SQL lifecycle tooling | `@rawsql-ts/ztd-cli` | [packages/ztd-cli/README.md](./packages/ztd-cli/README.md) |\n\n### Workflow Surfaces\n\nThese capabilities are important at the repo level even though they are mostly exposed through `ztd-cli` commands rather than standalone packages.\n\n| Workflow | Entry point | Why it matters |\n|----------|-------------|----------------|\n| SQL pipeline planning and dry-run optimization analysis | `ztd query plan`, `ztd perf run --dry-run` | Explains how SQL may be decomposed into stages before execution. |\n| SQL impact analysis before schema changes | `ztd query uses` | Supports rename/type-change investigations using AST-based usage analysis. |\n| SQL-first optional filter authoring | `ztd query sssql scaffold`, `ztd query sssql refresh` | Keeps optional filters visible in SQL while runtime pruning stays explicit. Runtime no longer injects new filter predicates. |\n| SQL debug and recovery for long CTE queries | `ztd query outline`, `ztd query lint`, `ztd query slice`, `ztd query patch apply` | Helps isolate and repair problematic query shapes; `ztd query lint --rules join-direction` adds a FK-aware JOIN readability guard. |\n| Explicit-target schema inspection and migration-prep workflow | `ztd ddl diff`, `ztd ddl pull` | Supports safe inspection against explicit target databases and generation of diff / patch SQL artifacts. Applying generated SQL is intentionally out of scope. |\n| Machine-readable CLI automation and telemetry | `ztd --output json`, `ztd describe`, telemetry export modes | Supports AI/tooling integration and timing investigation. |\n\n## Packages\n\n### Core\n\n| Package | Version | Description |\n|---------|---------|-------------|\n| [rawsql-ts](./packages/core) | ![npm](https://img.shields.io/npm/v/rawsql-ts) | SQL parser and AST transformer. Zero dependencies, browser-ready. |\n| [@rawsql-ts/sql-grep-core](./packages/sql-grep-core) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/sql-grep-core) | Low-dependency SQL usage analysis engine for AST-based schema impact checks. |\n\n### Production Driver Adapters\n\n| Package | Version | Description |\n|---------|---------|-------------|\n| [@rawsql-ts/driver-adapter-core](./packages/drivers/driver-adapter-core) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/driver-adapter-core) | Driver-neutral SQL client contract and named-parameter compilation helpers. |\n\n### Execution\n\n| Package | Version | Description |\n|---------|---------|-------------|\n| [@rawsql-ts/executor](./packages/executor) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/executor) | Optional helper for connection lifecycle and transaction scope when you want less boilerplate while keeping execution ownership in the caller. |\n\n### Testing\n\n| Package | Version | Description |\n|---------|---------|-------------|\n| [@rawsql-ts/testkit-core](./packages/testkit-core) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/testkit-core) | Fixture-backed CTE rewriting and schema validation engine. Driver-agnostic ZTD foundation. |\n| [@rawsql-ts/testkit-postgres](./packages/testkit-postgres) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/testkit-postgres) | Postgres-specific CTE rewriting and fixture validation. Works with any executor. |\n| [@rawsql-ts/adapter-node-pg](./packages/adapters/adapter-node-pg) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/adapter-node-pg) | Testkit adapter connecting `pg` (node-postgres) to `@rawsql-ts/testkit-postgres`; retained under its legacy name until a non-breaking `testkit-adapter-*` alias exists. |\n| [@rawsql-ts/testkit-sqlite](./packages/testkit-sqlite) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/testkit-sqlite) | SQLite-specific CTE rewriting and fixture validation. In-memory testing with `better-sqlite3`. |\n\n### Adapter Package Spaces\n\n`driver-adapter-*` packages are production runtime driver adapters.\nThey handle driver mechanics such as named-parameter compilation, placeholder conversion, and row-result normalization without owning ORM behavior or fixture rewriting.\n\n`testkit-adapter-*` packages are test-only adapters that connect concrete drivers to ZTD/testkit fixture rewriting.\n`@rawsql-ts/adapter-node-pg` currently belongs to that testkit adapter role despite its legacy name.\nThe planned rename path is to add a non-breaking alias such as `@rawsql-ts/testkit-adapter-node-postgres`, then document `@rawsql-ts/adapter-node-pg` as the legacy compatibility surface.\n\n### Evidence\n\n| Package | Version | Description |\n|---------|---------|-------------|\n| [@rawsql-ts/test-evidence-core](./packages/test-evidence-core) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/test-evidence-core) | Core schema and storage model for deterministic test evidence. |\n| [@rawsql-ts/test-evidence-renderer-md](./packages/test-evidence-renderer-md) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/test-evidence-renderer-md) | Markdown renderer for saved test evidence reports. |\n\n### Documentation\n\n| Package | Version | Description |\n|---------|---------|-------------|\n| [@rawsql-ts/ddl-docs-cli](./packages/ddl-docs-cli) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/ddl-docs-cli) | CLI that generates Markdown table definition docs from DDL files. |\n| [@rawsql-ts/ddl-docs-vitepress](./packages/ddl-docs-vitepress) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/ddl-docs-vitepress) | Scaffold generator for VitePress-based database schema documentation sites. |\n\n### CLI\n\n| Package | Version | Description |\n|---------|---------|-------------|\n| [@rawsql-ts/ztd-cli](./packages/ztd-cli) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/ztd-cli) | SQL-first CLI for ZTD workflows, schema inspection, and migration SQL artifact generation. |\n\nFor the machine-readable CLI surface, see [ztd-cli Agent Interface](./docs/guide/ztd-cli-agent-interface.md) and [ztd-cli Describe Schema](./docs/guide/ztd-cli-describe-schema.md).\n\n## Architecture\n\n```text\nrawsql-ts (core)\n├─ @rawsql-ts/sql-grep-core\n├─ @rawsql-ts/executor\n├─ @rawsql-ts/driver-adapter-core\n├─ @rawsql-ts/testkit-core\n│  ├─ @rawsql-ts/testkit-postgres\n│  │  └─ @rawsql-ts/adapter-node-pg\n│  └─ @rawsql-ts/testkit-sqlite\n├─ @rawsql-ts/ddl-docs-cli\n│  └─ @rawsql-ts/ddl-docs-vitepress\n└─ @rawsql-ts/ztd-cli\n   └─ uses @rawsql-ts/sql-grep-core for `query uses`\n```\n\n## Quick Start\n\n```bash\nnpm install rawsql-ts\n```\n\nSee the [Core Package Documentation](./packages/core/README.md) for usage examples and API reference. For reusable AST-based impact analysis, see [@rawsql-ts/sql-grep-core](./packages/sql-grep-core). For repo-level SQL lifecycle workflows, inspection commands, and ZTD project guidance, see [@rawsql-ts/ztd-cli](./packages/ztd-cli/README.md). Deterministic dogfooding spec: [docs/dogfooding/DOGFOODING.md](./docs/dogfooding/DOGFOODING.md).\n\n## Tutorials\n\n- [SQL-first End-to-End Tutorial](./docs/guide/sql-first-end-to-end-tutorial.md) - Walk from DDL to `ztd-config`, `model-gen`, repository wiring, and the first passing smoke test in one focused path.\n- [Migration Repair Loop](./docs/dogfooding/ztd-migration-lifecycle.md) - Repair DDL, SQL, DTO, and migration artifacts with AI after the starter flow is green.\n\n## Intent and Procedure\n\nTreat each query as one unit: 1 SQL file / 1 QuerySpec / 1 repository entrypoint / 1 DTO.\n\nKeep handwritten SQL assets close to each feature in `src/features/\u003cfeature\u003e/queries/\u003cquery\u003e/` so the SQL, boundary contract, and query-local tests stay in one place.\n\nUse this repo by treating DDL and SQL as source assets, and generated specs, repositories, and tests as downstream artifacts that must stay in sync.\n\nProcedure: `DDL -\u003e SQL -\u003e generate -\u003e wire -\u003e test`.\n\nFor a step-by-step example, see the SQL-first tutorial above.\n\n## Getting Started with AI\n\nIf 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.\n\nOptional Docker helper:\n\nIf you want a local PostgreSQL 18 instance for ZTD tests, use a tiny compose file like this:\n\n```yaml\nservices:\n  postgres:\n    image: postgres:18\n    environment:\n      POSTGRES_USER: ztd\n      POSTGRES_PASSWORD: ztd\n      POSTGRES_DB: ztd\n    ports:\n      - \"5432:5432\"\n    volumes:\n      - ztd-postgres-data:/var/lib/postgresql/data\n\nvolumes:\n  ztd-postgres-data:\n```\n\nThen run `docker compose up -d` and point `ZTD_DB_URL` at that database for the fixture-backed rewrite path.\n\n## CLI Tool Routing Happy Paths\n\n- SQL pipeline / debug → `ztd query plan \u003csql-file\u003e`\n- Impact analysis → `ztd query uses \u003ctarget\u003e`\n- SQL-first optional filters → `ztd query sssql scaffold \u003csql-file\u003e` / `ztd query sssql refresh \u003csql-file\u003e`\n- Schema inspection → `ztd ddl diff --url \u003ctarget\u003e`\n\nFor the full routing guide and decision table, see [SQL Tool Happy Paths](./docs/guide/sql-tool-happy-paths.md).\n\n## Database Boundary at a Glance\n\nFor repo-level workflows, keep this boundary in mind:\n\n* `.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`\n* `DATABASE_URL` is typically an application/runtime/deployment concern and is not read automatically by `ztd-cli`\n* any non-ZTD database target must be supplied explicitly via `--url` or `--db-*`\n* migration SQL artifacts may be generated by `ztd-cli`, but apply / deployment execution remains outside its ownership\n\nThis 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.\n\n## Online Demo\n\n[Try rawsql-ts in your browser](https://mk3008.github.io/rawsql-ts/)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmk3008%2Frawsql-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmk3008%2Frawsql-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmk3008%2Frawsql-ts/lists"}