# Kysely PostgreSQL Agent Skill
A production-oriented skill for writing type-aware Kysely queries and PostgreSQL migrations in Node.js/TypeScript projects.
## Compatibility
- **Kysely:** `0.29.5`
- **TypeScript:** `>= 5.4`
- **Module format:** ESM (`es2023` target)
- **Primary dialect:** `PostgresDialect`, commonly with `pg`
The skill's examples target this version. Check the host project's installed Kysely version before copying a version-sensitive API such as controlled transactions, savepoints, cancellation, or migrations.
## What the Skill Provides
- A required workflow for finding the existing DB boundary, runtime type contract, migration runner, and local query conventions.
- Clear separation of Kysely compile-time safety from runtime input validation and driver result parsing.
- PostgreSQL guidance for JSONB, arrays, schemas, CTEs, transactions, migrations, cancellation, and diagnostics.
- Focused reference snippets for common query patterns.
## Structure
```text
kysely-postgres/
├── SKILL.md # Policy-first operational guidance
├── references/
│ ├── runtime-types-and-bootstrap.ts
│ ├── select-where.ts
│ ├── joins.ts
│ ├── aggregations.ts
│ ├── orderby-pagination.ts
│ ├── ctes.ts
│ ├── json-arrays.ts
│ ├── relations.ts
│ ├── mutations.ts
│ ├── expressions.ts
│ ├── schemas.ts
│ └── operations.ts
```
Start with [`SKILL.md`](SKILL.md). It links to the relevant reference file instead of requiring every example to be read for every task.
## Important Boundaries
- Kysely checks TypeScript query relationships; it does **not** validate HTTP/job/event input or convert runtime values from the database driver.
- `DB` types must match the installed driver's configured parsers. This is especially important for `int8`, `numeric`, `date`, timestamps, JSON/JSONB, and arrays.
- Reference files are illustrative snippets. They intentionally import a project-local `./db` and `./db.d`; they are not a standalone TypeScript package or a test suite.
- Use the host project's migration runner. `kysely-ctl` is an optional integration, not Kysely core.
## Updating Kysely Support
1. List releases with `gh` and select a stable target tag.
2. Verify version-sensitive APIs against source/docs pinned to that tag.
3. Use `site/docs` on `master` for general patterns, clearly distinguishing them from tag-pinned facts.
4. Update `SKILL.md`, affected references, and this README together.
5. Run `git diff --check` and any available snippet typecheck. Do not claim standalone compilation until a fixture and validation command exist.
## Primary Sources
- [Kysely documentation](https://kysely.dev/)
- [Kysely GitHub repository](https://github.com/kysely-org/kysely)
- [Kysely 0.29.5 release](https://github.com/kysely-org/kysely/releases/tag/v0.29.5)
## License
MIT — see [LICENSE](LICENSE).