quackatos

library1.8.0jsnpmunverified

Quackatos is an extremely well-typed query builder for Postgres, built on top of Zapatos (v6.0.1+). Current stable version is 1.8.0, with active development. It prioritizes type safety: query results are fully typed based on the database schema generated by Zapatos, and any code without type errors should generate a valid SQL query. Unlike Knex (weakly typed, multi-dialect) or Prisma (strongly typed, ORM-heavy), Quackatos stays close to SQL and is Postgres-only. It provides intuitive methods like select, where, join, limit, etc., and returns typed tuples or objects. Release cadence is sparse but maintained.

database

npm install quackatos

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · QUACKATOS

quackatos

databasejavascriptv1.8.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (q)

✓ import q from 'quackatos'

✗ const q = require('quackatos')

Quackatos is ESM-only; CommonJS require is not supported. The default export is a function that takes a table name and returns a query builder.

QueryBuilder

✓ import { QueryBuilder } from 'quackatos'

Optional to import the class; typical usage uses the default 'q' function which returns an instance.

RunResult

✓ import type { RunResult } from 'quackatos'

✗ import { RunResult } from 'quackatos'

RunResult is a TypeScript type for the result of .run(). Since v1.0, types should be imported with 'import type'.

Demonstrates a typed query with left joins, select, where, limit, and execution with pg Pool.

import q from 'quackatos'; import { Pool } from 'pg'; const pool = new Pool({ connectionString: process.env.DATABASE_URL ?? '' }); async function main() { const filmAndActor = await q('film') .leftJoin('film_actor', 'film.film_id', 'film_actor.film_id') .leftJoin('actor', 'actor.actor_id', 'film_actor.actor_id') .select('actor.first_name', 'film.*') .where('film.title', '$ilike', '%hello%') .limit(1) .run(pool); console.log(filmAndActor); } main().catch(console.error);

Debug

Known issues

deprecatedThe 'order' method is deprecated in favor of 'orderBy' since v1.5. It will be removed in v2.0.

fix

Replace .order('column', 'ASC') with .orderBy('column', 'ASC').

affects: >=1.5.0 <2.0.0

breakingIn v1.0, the default export was changed from a named function to a default export. Import with 'import q from "quackatos"' instead of 'import { q } from "quackatos"'.

fix

Use default import: import q from 'quackatos'.

affects: >=1.0.0

gotchaQuackatos requires Zapatos types to be generated first. Without a properly generated schema, queries will not type-check.

fix

Run 'npx zapatos' to generate types before using Quackatos. See Zapatos docs for setup.

affects: >=0.1.0

gotchaThe .run() method returns an array of tuples under the hood, but typed as a union of objects. This can lead to unexpected behavior when trying to spread results.

fix

Access properties directly on the result rows; avoid destructuring unknown columns. Use .select() to specify exact columns.

affects: >=1.0.0

deprecatedSupport for Node.js 14 and 16 has been dropped since v1.7.0.

fix

Upgrade to Node.js 18+ (LTS).

affects: >=1.7.0

Errors

Common errors & fixes

Cannot find module 'quackatos' or its corresponding type declarations.

Quackatos is ESM-only and requires 'type': 'module' in package.json, or using .mjs extension. Also TypeScript may need esModuleInterop.

fix

Add '"type": "module"' to your package.json and ensure tsconfig.json has 'esModuleInterop': true.

Property 'run' does not exist on type 'QueryBuilder<...>'.

You forgot to call .run()? Or you are using an older version (<1.0) where run was named execute.

fix

Ensure you call .run(pool) at the end. If using v0.x, use .execute(pool) instead. Upgrade to v1+.

Cannot find name 'zapatos' or Module '"quackatos"' has no exported member 'QueryBuilder'.

Zapatos types are not generated or not imported correctly.

fix

Run 'npx zapatos' to generate types. Then import Zapatos types in your project. Quackatos exports QueryBuilder but it's rarely needed; use default import instead.

Upgrade

Version history

1.8.0latest on npm

Audit

Dependencies

zapatosrequiredQuackatos relies on Zapatos for type generation and database schema types

pgrequiredpg Pool (or client) is required to execute queries

Agent activity

10 hits · last 30 days

node

Resources

githubssh://git@github.com/seamapi/quackatos ↗

packagequackatos ↗

homepagehttps://github.com/seamapi/quackatos#readme ↗