ts-postgres

library2.0.4jsnpmunverified

Non-blocking PostgreSQL client for Node.js written in TypeScript, currently at v2.0.4. Supports both ESM and CommonJS modules. Key differentiators include built-in types, pipeline queries, extensible value model, and hybrid query result objects (iterable both synchronously and asynchronously). Has no runtime dependencies, but requires Node >=18 and @types/node peer dependency. Actively maintained on GitHub with regular releases. Compared to alternatives like `pg`, it offers TypeScript-first design and binary result data format.

database

npm install ts-postgres

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TS-POSTGRES

ts-postgres

databasejavascriptv2.0.4

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.

connect

✓ import { connect } from 'ts-postgres'

✗ const { connect } = require('ts-postgres')

Default import not available; must use named import. CJS require also works, but ESM is preferred.

Client

✓ import { Client } from 'ts-postgres'

Client class can be instantiated directly, but most examples use connect() factory. No default export.

Configuration

✓ import type { Configuration } from 'ts-postgres'

✗ import { Configuration } from 'ts-postgres'

Configuration is a TypeScript interface, not a runtime value. Use 'import type' to avoid bundling issues.

Connects to PostgreSQL using environment variables or defaults, executes a parameterized query, and streams results asynchronously.

import { connect } from 'ts-postgres'; async function main() { const client = await connect({ host: process.env.PGHOST ?? 'localhost', port: parseInt(process.env.PGPORT ?? '5432'), user: process.env.PGUSER ?? 'postgres', database: process.env.PGDATABASE ?? 'postgres', password: process.env.PGPASSWORD ?? '', }); try { const result = client.query<{ message: string }>( "SELECT 'Hello, ' || $1 || '!' AS message", ['world'], ); for await (const row of result) { console.log(row.message); // 'Hello, world!' } } finally { await client.end(); } } main().catch(console.error);

Debug

Known issues

breakingVersion 2.x drops support for Node < 18.0.0 and requires Node >=18 for the `performance` module and other APIs.

fix

Upgrade Node.js to version 18 or later.

affects: >=2.0.0

breakingIn ts-postgres 1.x, `client.query()` returned a Promise of QueryResult. In 2.x it returns a QueryResult directly (async iterable). Use `await client.query(...).execute()` or await the result iterator for similar behavior.

fix

Either iterate using `for await (const row of client.query(...))` or use `const result = await client.query(...); // To get full result`

affects: >=2.0.0

deprecatedThe `QueryResult` methods `rows()` and `columns()` are deprecated in favor of direct iteration and accessing `result.columns` property.

fix

Use `for await (const row of result)` and `result.columns` instead.

affects: >=2.0.0

gotchaEnvironment variables from libpq (e.g., PGHOST, PGPORT) are not automatically read by default; you must manually populate the Configuration object from env vars.

fix

Explicitly read environment variables or use a configuration helper to map them to the config object.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: ts_postgres_1.connect is not a function

Using default import instead of named import (e.g., `import connect from 'ts-postgres'`)

fix

Use named import: `import { connect } from 'ts-postgres'`

Error: getaddrinfo EAI_AGAIN

DNS resolution failure when connecting to PostgreSQL host (often due to network issues or incorrect hostname)

fix

Verify the hostname in configuration is correct and network is reachable. Increase connection timeout if needed.

SyntaxError: Cannot use import statement outside a module

Using ESM import syntax in a CommonJS project without setting `"type": "module"` in package.json

fix

Add `"type": "module"` to package.json or use CommonJS require syntax: `const { connect } = require('ts-postgres')`

Upgrade

Version history

2.0.4latest on npm

Audit

Dependencies

@types/nodeoptionalPeer dependency for TypeScript node type definitions

Agent activity

22 hits · last 30 days

node