Zapatos is a 'zero-abstraction' database library specifically designed for TypeScript and Postgres. It provides strong type safety by generating a detailed TypeScript schema directly from your existing Postgres database, reducing the boilerplate and common pitfalls associated with traditional ORMs. The library facilitates writing arbitrary SQL queries using tagged templates, offers shortcut functions for everyday CRUD operations, and supports complex data structures like nested JSON via LATERAL JOINs, all while maintaining full type inference. Unlike many ORMs, Zapatos does not manage connection pools, explicitly relying on the underlying `pg` module, and does not aim to be database-agnostic or provide a 'code-first' approach. Currently at version 6.6.1, Zapatos maintains an active development status, with a focus on integrating seamlessly with Postgres's native capabilities and TypeScript's type system.
npm install zapatosVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates basic Zapatos operations: connecting to a PostgreSQL database via `pg`, inserting a new record, selecting all records, updating a record, and executing operations within a transaction, all using generated TypeScript types for safety.
Set `"customJSONParsingForLargeNumbers": true` in your `zapatosconfig.json` file. This changes the TypeScript types for these columns in `JSONSelectable` to `number | `${number}``.Always use `import type` for Zapatos schema imports to ensure they are treated purely as type definitions and not bundled at runtime.
Manually set up and manage your `pg.Pool` instance and pass it to Zapatos's `.run()` methods for queries and transactions.
Understand that Zapatos's design is opinionated towards PostgreSQL and an existing database schema. If you require a database-agnostic ORM or code-first migrations, Zapatos may not be the right fit.
Review the data being inserted or updated and compare it against the `CHECK` constraints defined in your PostgreSQL schema. Zapatos propagates these database errors directly, ensuring you are aware of underlying data integrity rules.
Verify that `someProperty` exists in your PostgreSQL table `TableName`. If the database schema has recently changed, run `npx zapatos` to regenerate your TypeScript schema definitions (`zapatos/schema.d.ts`) to reflect the latest database structure.