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 (sql tagged template literal)
✓ import postgres from 'postgres-js';
const sql = postgres('postgres://username:password@localhost:5432/database');
✗ const postgres = require('postgres-js');
// or
import { sql } from 'postgres-js';
The package exports a default function that returns a sql template literal tag. CommonJS require works, but named imports like `{ sql }` are incorrect because no named export exists.
type definitions (TypeScript)
✓ import postgres, { Sql } from 'postgres-js';
✗ import { Postgres } from 'postgres-js';
TypeScript users should import the `Sql` type from the package for type annotations. The main import is the default function.
Connection options
✓ import postgres from 'postgres-js';
const sql = postgres({
host: 'localhost',
port: 5432,
database: 'test',
user: 'user',
password: 'pass'
});
✗ const sql = postgres('localhost', 5432, 'test', 'user', 'pass');
// OR
const sql = postgres({ url: 'postgres://...' });
Only connection string or options object is accepted; individual arguments are not supported. A `url` key is not valid; use the connection string directly.
Connects to a PostgreSQL database, creates a table, inserts a row, queries with a parameter, and cleans up.
import postgres from 'postgres-js';
const sql = postgres('postgres://localhost:5432/mydb');
async function main() {
// Create table
await sql`CREATE TABLE IF NOT EXISTS users (
id serial PRIMARY KEY,
name text,
age integer
)`;
// Insert
const [{ id }] = await sql`INSERT INTO users (name, age) VALUES ('Alice', 30) RETURNING id`;
console.log('Inserted user ID:', id);
// Query with parameters
const users = await sql`SELECT * FROM users WHERE age > ${20}`;
console.log('Users older than 20:', users);
// Cleanup
await sql`DROP TABLE users`;
await sql.end();
}
main().catch(console.error);
Errors
Common errors & fixes
TypeError: postgres is not a function
Default import used incorrectly; likely imported named export instead of default.
fixUse `import postgres from 'postgres-js';` (no braces).
Error: Connection terminated unexpectedly
Network issue, incorrect credentials, or server refused connection.
fixCheck database host, port, user, password, and ensure PostgreSQL is running.
Cannot find module 'postgres-js'
Package not installed or import path incorrect.
fixRun `npm install postgres-js` or ensure correct path in package.json.
Audit
Dependencies
postgres-arrayoptionalUsed internally for parsing PostgreSQL array types.
postgres-byteaoptionalUsed internally for bytea encoding/decoding.