bun
Incredibly fast JavaScript runtime, bundler, test runner, and package manager – all in one
- 97k
- Rust
- 4 h ago
Pure-TypeScript Postgres wire-protocol driver. Zero native dependencies. Runs on Perry, Node.js, and Bun.
Repo PerryTS/postgres, read from GitHub 1 min ago. PerryTS has not joined Take My Repo.
PerryTS/postgres is a public repo on GitHub by PerryTS. Pure-TypeScript Postgres wire-protocol driver. Zero native dependencies. Runs on Perry, Node.js, and Bun. It declares the MIT license on GitHub. It is written mainly in TypeScript, has 8 stars and last changed on 2026-05-08. Nobody has reviewed it on Take My Repo yet, which says nothing about its quality. Read from GitHub on 2026-11-22.
In the maintainer's words. Shown from GitHub; Take My Repo does not keep a copy.
A pure-TypeScript Postgres driver that speaks the wire protocol directly —
no libpq, no native addons, no runtime FFI. It runs unchanged on
Node.js, Bun, and Perry,
where the same TypeScript source is ahead-of-time compiled to a native
binary via LLVM — giving you a real standalone executable that talks to
Postgres with no JS runtime attached.
Perry is a TypeScript-to-native compiler: it lowers a strict subset of TS through LLVM into a statically-linked binary.
@perryts/postgresis the reference driver used by Tusk (the Perry-native Postgres GUI), and the showcase for Perry's systems capabilities — every socket read, TLS handshake, and crypto op goes through perry-stdlib rather than a Rust or C shim.
bun add @perryts/postgres npm install @perryts/postgres pnpm add @perryts/postgres
import { connect, sql } from '@perryts/postgres'; const conn = await connect('postgres://alice:secret@db.example.com:5432/myapp'); const { rows } = await conn.query<{ id: number; name: string }>( sql`SELECT id, name FROM users WHERE active = ${true}` ); for (const user of rows) console.log(user.id, user.name); await conn.close();
Most Node drivers wrap libpq or ship a platform-specific .node addon.
That's a non-starter for two use cases we care about:
Compiling to a native binary with Perry. Perry produces a
statically-linked executable via LLVM; there is no Node runtime at
execution time, so any driver that assumes V8 / N-API / require('pg-native')
is unusable. @perryts/postgres uses only APIs that exist on both
Perry's stdlib and Node core (Buffer, net.Socket, crypto.*,
tls.connect), so the same TypeScript source runs on a JS runtime
and compiles to a native binary.
Driving a GUI (Tusk). ORMs lose column metadata and coerce
types for ergonomics. A database client has to render numeric(30,8)
exactly, surface attnum / tableOid so users can edit-in-place, and
expose NOTICE, ParameterStatus, backend PIDs, and structured
ErrorResponse fields. This driver returns raw rows plus full
column descriptors, and never silently coerces.
sslmode=disable | require | verify-ca | verify-full, mid-stream
upgrade handled transparently on both Perry and Node.Query, Parse / Bind / Execute / Sync,
portals, Describe.numeric (precision-preserving
Decimal), booleans, text family, bytea, uuid, json, jsonb,
the full date/time family with microsecond precision, and 1-d arrays of
any of the above — both text and binary formats.PgError — every documented ErrorResponse field:
SQLSTATE, position, detail, hint, schema/table/column/constraint.NOTICE, ParameterStatus, LISTEN / NOTIFY.sql tagged-template helper.PG* env vars — DATABASE_URL, PGHOST, PGPORT,
PGUSER, PGPASSWORD, PGDATABASE, PGSSLMODE, PGAPPNAME,
PGCONNECT_TIMEOUT all work out of the box.Buffer, node:net,
node:tls, and node:crypto. Nothing to rebuild per platform.numeric coercion. Values land in a Decimal wrapper that
round-trips exact string form — none of the 9999999999.99 → 9999999999.989999
drift common to float-backed drivers.| Runtime | Status | Notes |
|---|---|---|
| Perry (AOT → native) ≥ 0.5.24 | supported | Same source, compiled via LLVM. TLS upgrade uses socket.upgradeToTLS from perry-stdlib. No JS runtime at execution time. Every built-in codec round-trips correctly (verified end-to-end against real Postgres via examples/perry-smoke-codecs.ts). |
| Node.js ≥ 22 | supported | Uses node:net, node:tls, node:crypto, Buffer. |
| Bun ≥ 1.3 | supported | Fully works except a known Bun bug in tls.connect({socket}) for in-place upgrade; the corresponding tests run on Node via npm run test:tls:node. |
The only API divergence across these runtimes is the mid-stream TLS upgrade.
It's isolated in src/transport/upgrade-tls.ts
— a ~15-line feature-detect. Nothing else in the driver knows or cares
which runtime it's on.
import { connect } from '@perryts/postgres'; // 1. libpq-format URL. const conn = await connect('postgres://user:pw@host:5432/db?sslmode=verify-full'); // 2. Explicit options. const conn = await connect({ host: 'localhost', port: 5432, user: 'alice', database: 'myapp', password: 'secret', ssl: { mode: 'verify-full' }, applicationName: 'tusk', connectTimeoutMs: 10_000, }); // 3. URL with targeted overrides. const conn = await connect({ url: process.env.DATABASE_URL!, password: process.env.DB_PASSWORD, // overrides the URL's password }); // 4. Bare options + env vars. // PGHOST / PGPORT / PGUSER / PGPASSWORD / PGDATABASE / // PGSSLMODE / PGAPPNAME / PGCONNECT_TIMEOUT fill in missing fields. const conn = await connect({ user: 'alice' });
// Simple query — any DDL / SET / multi-statement text. await conn.query('CREATE TEMP TABLE t(id int, name text)'); // Parameterized — extended protocol. const r = await conn.query<{ id: number; name: string | null }>( 'SELECT id, name FROM users WHERE id = $1', [42] ); // Tagged template — the typical app pattern. import { sql } from '@perryts/postgres'; const id = 42; const r = await conn.query(sql` SELECT id, name FROM users WHERE id = ${id} `); // Composable fragments. const where = active ? sql`WHERE active` : sql``; const r = await conn.query(sql`SELECT * FROM users ${where} LIMIT ${10}`); // Dynamic identifiers. ONLY for caller-controlled values — never user input. import { raw } from '@perryts/postgres'; await conn.query(sql`SELECT * FROM ${raw(tableName)} WHERE id = ${id}`);
const r = await conn.query('SELECT id, name FROM users'); r.rows; // [{ id: 1, name: 'alice' }, ...] ← decoded objects r.rowsArray; // [[1, 'alice'], ...] ← decoded positional r.rowsRaw; // [[<Buffer>, <Buffer>], ...] ← raw wire bytes (GUI-grade) r.fields; // [{ name, typeOid, formatCode, tableOid, attnum, typmod, ... }] r.command; // 'SELECT 2' r.rowCount; // 2
r.rows is the obvious shape for application code. r.rowsRaw is what
Tusk's grid uses when it wants to render bytes byte-for-byte without a
round-trip through Buffer.
| Postgres type | TypeScript value |
|---|---|
int2, int4 |
number |
int8 |
bigint — always. int8 exceeds Number.MAX_SAFE_INTEGER. |
float4, float8 |
number — NaN, Infinity, -Infinity all round-trip. |
numeric |
Decimal — string-backed; .toString(), .toNumber(). Exact. |
bool |
boolean |
text, varchar, bpchar, name |
string |
bytea |
Buffer — both hex and legacy octal text formats decoded. |
uuid |
canonical lowercase string with dashes |
json, jsonb |
parsed JS value |
date, time, timetz, timestamp, timestamptz, interval |
typed objects with .toString(), .toDate(), microsecond fields |
| 1-d arrays of any of the above | Array<T> with null for SQL NULLs |
Perry-native caveat: wrapper types (Decimal, PgDate, PgTime,
PgTimestamp, PgInterval) decode correctly but String(value) /
value.toString() currently doesn't dispatch to the wrapper's
overridden method on Perry. Read the underlying field directly
(v.value for PgDate, v.raw on PgTime / PgTimestamp /
PgInterval, v._s for Decimal) — that's what
examples/perry-smoke-codecs.ts does. On Node and Bun, toString()
works as expected.
import { Decimal } from '@perryts/postgres'; const r = await conn.query('SELECT $1::numeric', ['99999999999999.99']); r.rows[0]['?column?'] instanceof Decimal; // true String(r.rows[0]['?column?']); // '99999999999999.99' — exact
const orderId = await conn.transaction(async (tx) => { await tx.query(sql`INSERT INTO orders (user_id) VALUES (${userId})`); const r = await tx.query(sql`SELECT currval('orders_id_seq') AS id`); return r.rows[0].id; }); // COMMIT on resolve, ROLLBACK on throw.
import { createPool } from '@perryts/postgres'; const pool = createPool({ url: process.env.DATABASE_URL, max: 20, // default 10 idleTimeoutMs: 30_000, // close idle connections after 30s acquireTimeoutMs: 30_000, // wait at most 30s for a slot when full }); // Acquire + query + release in one call. const r = await pool.query(sql`SELECT now()`); // Multi-statement — borrow the connection yourself. await pool.withConnection(async (conn) => { await conn.query('SET search_path TO app'); return conn.query('SELECT * FROM widgets'); }); // Pooled transaction. await pool.transaction(async (tx) => { await tx.query(sql`UPDATE accounts SET balance = balance - ${amt} WHERE id = ${from}`); await tx.query(sql`UPDATE accounts SET balance = balance + ${amt} WHERE id = ${to}`); }); pool.size(); // { total, idle, waiting } await pool.end();
const long = conn.query('SELECT pg_sleep(60)'); setTimeout(() => conn.cancel(), 1000); try { await long; } catch (e) { // PgError with code '57014' (query_canceled). console.error(e.code, e.message); } // `conn` is reusable — ReadyForQuery restored.
import { PgError } from '@perryts/postgres'; try { await conn.query('SELECT * FROM nope'); } catch (e) { if (e instanceof PgError) { e.code; // '42P01' e.severity; // 'ERROR' e.message; // 'relation "nope" does not exist' e.position; // '15' e.hint; // ... e.detail; // ... e.schema; // table / column / constraint fields, etc. } }
conn.on('notice', (n) => console.warn(n.severity, n.message)); conn.on('parameter', (key, value) => console.log('PG set', key, '=', value)); await conn.query('LISTEN job_done'); conn.on('notification', (n) => { console.log('NOTIFY received on', n.channel, ':', n.payload); });
import { registerType } from '@perryts/postgres'; registerType<{ x: number; y: number }>(POINT_OID, { oid: POINT_OID, name: 'point', text: { decode(buf) { const [x, y] = buf.toString().slice(1, -1).split(',').map(Number); return { x: x, y: y }; }, encode(v) { return Buffer.from(`(${v.x},${v.y})`); }, }, });
src/
├── protocol/ wire framing + message writer/reader
├── auth/ SCRAM-SHA-256, MD5, cleartext
├── transport/ net.Socket wrapper + Perry-vs-Node TLS upgrade
├── types/ OID → codec registry, 20 built-in codecs
├── error.ts structured PgError
├── notice.ts NoticeResponse parsing
├── cancel.ts fresh-socket CancelRequest
├── url.ts libpq connection-string parser
├── env.ts PG* environment-variable resolver
├── sql.ts `sql` tagged template + `raw()` escape hatch
├── pool.ts Connection pool
├── register-defaults.ts registers every built-in codec; called once from connect()
├── connection.ts Connection: lifecycle, simple + extended query
└── index.ts public barrel exports
Every source file respects the subset Perry's compiler can lower to LLVM:
?. or ?? — use explicit if (x === undefined) branching.obj[variable] dynamic key access.for...of over arrays — use for (let i = 0; i < arr.length; i++).indexOf / char-code checks.{ key } shorthand — write { key: key }.this.method in closures — module-level Map<id, State>
holds connection state, with named module-level handlers.These read like quirks in a JS runtime, but they are what makes the same source compile to a single-binary native executable on Perry.
Short version: V8 and JSC beat Perry at per-query wall time on a long-running process. Perry wins everywhere else — cold start, memory footprint, deploy size, and the set of platforms you can ship to. This driver's job is to make that trade available; the numbers below are what it looks like.
bench/run-all.sh against a local Postgres 16, 50 timed iterations +
5 warmups per workload, p50 wall time. Lower is better:
| workload | @perryts/postgres node | @perryts/postgres bun | @perryts/postgres perry-native¹ | pg (node) | pg-native (node)² | postgres.js (node) | tokio-postgres (rust) |
|---|---|---|---|---|---|---|---|
SELECT 1 |
82µs | 87µs | 2.5 ms | 82µs | 77µs | 85µs | 80µs |
| param 1-row | 138µs | 63µs | 2.0 ms | 132µs | 77µs | 137µs | 80µs |
| 1000 × 20 | 3.6 ms | 3.4 ms | 11.0 ms | 2.5 ms | 4.1 ms | 3.0 ms | 2.8 ms |
| 10000 × 20 | 36.0 ms | 33.3 ms | 100 ms | 22.1 ms | 38.0 ms | 28.7 ms | 26.5 ms |
Perry-native is ~2.8× Node on bulk decode and ~30× on tiny queries.
That's the worst axis for AOT: V8 has had 20 years of trace-JIT
engineering specifically to optimise these tight loops, and Perry's
arena GC can't match a generational collector for short-lived row
objects. If your process runs a while (true) { query; } loop
forever, run Node or Bun.
The thing you gain by AOT-compiling isn't a faster hot path — it's a process that's ready before V8 is still loading, uses a fraction of the memory, and ships as one file:
| Node (+tsx) | Bun | Perry-native | |
|---|---|---|---|
Cold start of a console.log('hi') script |
150 ms | 10 ms | <10 ms (first run), ~1 ms after |
| Peak RSS for the same program | 37 MB | 7.8 MB | 1.8 MB |
Cold start of the driver's conn.query('SELECT 1') |
160–240 ms | 20–30 ms | (blocked on flakiness, see note¹) |
| Driver binary / artifact | node runtime + node_modules |
bun runtime + node_modules |
single 4.6 MB static binary |
node_modules size to run the driver |
~40 MB | ~40 MB | 0 |
| Deploys to iOS / Android / embedded | ❌ | ❌ | ✅ |
For a long-running server — a web app, a queue worker — Node/Bun's JIT wins the per-query game and amortises the startup cost. For a CLI tool, a short cron job, a serverless function that spins up and dies, a container that needs to boot fast, or any mobile / embedded deployment — Perry wins on the things the environment actually measures you on.
That's why this driver is pure TypeScript: the same source compiles three ways. You pick the target that matches what you're shipping.
| Scenario | Best choice | Why |
|---|---|---|
| Long-running web server with warm V8 | @perryts/postgres on Node / Bun, or pg if you want the absolute floor |
JIT beats AOT on tight per-query loops |
| CLI / one-shot tool that opens a connection, runs N queries, exits | @perryts/postgres on Perry-native |
5–20× faster startup, ~50 MB less RSS, single binary to distribute |
| Serverless function (cold start is the whole game) | @perryts/postgres on Perry-native, OR Bun if you can ship a Bun-ABI target |
Bun is 10ms-class on cold start too; Perry wins on RSS |
| iOS / Android / watchOS app that needs local Postgres | @perryts/postgres on Perry-native |
Node/Bun don't run there at all |
| Embedded / resource-constrained Linux | @perryts/postgres on Perry-native |
single static binary, no runtime deps |
| ETL / analytics pipeline that processes millions of rows | pg on Node, with parseTypes: 'minimal' on this driver if you want the same API |
pg's "strings by default" is the bulk-decode floor |
¹ Perry-native runs via perry compile src/…/bench-this.ts. The
2–3 ms per-call floor is the AOT runtime's Promise / async /
FFI overhead — Node and Bun amortise that into ~100µs per call
via V8's / JSC's deopt-free hot paths. Bulk decode converged to
within ~2.8× of Node after the v0.5.30 hidden-class IC work
(standalone 10k×20 dynamic-key object build actually beats
Node at 3.3 ms vs 8.5 ms; the Postgres-path gap is all
protocol-frame decoding + per-cell wrapper allocation, not
object-shape cost).
Requires Perry ≥ 0.5.87. Prior fix chain: #32 / #33 / #34 / #35 / #36 / #37 / #68 / #70 / #71 / #72 / #73.
² pg-native is the libpq N-API binding. Only runs on Node in
practice: Perry-native can't load dynamically-linked C addons (this
driver exists precisely because that's a dead end for AOT targets),
and Bun requires a from-source rebuild against its own ABI v137
which isn't in the standard install flow.
Counter-intuitively, pg-native is ~1.8× slower than pg (pure
JS) on bulk decode (37 ms vs 21 ms on 10k × 20). The N-API
boundary-crossing per row + per-cell marshalling into V8 objects
costs more than pg's stay-in-V8 text-format parser. C-speed inner
loops don't help when every parsed value still has to become a JS
heap object.
The Perry-native column changed dramatically across 0.5.29 → 0.5.87:
| workload | 0.5.29 | 0.5.87 | change |
|---|---|---|---|
SELECT 1 |
3.0 ms | 2.5 ms | -17% |
| param 1-row | 3.0 ms | 2.0 ms | -33% |
| 1000 × 20 | 42 ms | 11 ms | -74% |
| 10000 × 20 | 764 ms | 100 ms | -87% |
The big wins came from:
obj[name] = value writes (v0.5.30
closed #37 which I filed
during this work). The linear-scan property set was O(N²) per row; the
IC transition-cache made it O(N). Alone closes most of the gap.Notes:
pg is fastest by a meaningful margin because it returns int8
/ numeric / date / time / timestamp as raw strings unless
the caller opts into a parser — no bigint, no Decimal, no
PgDate per cell. Most of our remaining gap is the wrapper-allocation
cost on those types. We chose to wrap by default because the GUI use
case (Tusk) needs them typed; if you don't, those wrappers are pure
overhead — pass parseTypes: 'minimal' to connect() to opt out
and get the same string-as-default shape pg uses (~5% off our
default on mixed workloads, ~20% off on result sets dominated by
int8 / numeric / date columns):
const conn = await connect({ host: 'db.example.com', user: 'app', database: 'myapp', parseTypes: 'minimal', // int8/numeric/date/time/timestamp/interval → string });
postgres.js sits between us and pg; same reason it's slower
than pg (some parsing) and same reason it's faster than us (less
parsing). We're within ~1.1–1.3× of it on bulk results — typically
faster on Bun, slightly slower on Node.
tokio-postgres (Rust release build with rust_decimal) is in
the same range as postgres.js on bulk results: 26.7 ms on
10000×20 vs our 34.9 ms (Node) / 32.5 ms (Bun). The bench reads
every cell into an owned i64 / String / Decimal / bool so
the lazy row.get<T> path doesn't make Rust look unfairly fast.
On tiny queries Rust wins by a wide margin (35µs vs ~60µs) because
there's no V8 JIT warm-up tax. Bulk decoding, where most consumers
live, is dominated by the codec choices — language matters less
than what you parse into.
Perry-native has a constant ~3 ms per query overhead vs ~100µs
on the JS hosts — that's the AOT runtime's promise / async / FFI
per-call cost rather than anything driver-level. Bulk decode is
currently ~10–20× slower than the JS hosts on bulk results (42 ms
vs 3.5 ms on 1000×20; 764 ms vs 36 ms on 10000×20) — every row
builds a wrapper-heavy object chain in Perry's arena GC and there's
real per-cell cost there the JS JITs optimise out. Correctness
landed first across PerryTS/perry #32 / #33 / #34 / #35 / #36
(module-level globals weren't registered as GC roots, so
CONN_STATES was getting swept mid-decode). Speed is landing in
increments — 0.5.29 shipped a ~14% cut on the 10k-row workload by
gating the shape-clone on a GC_FLAG_SHAPE_SHARED bit and moving
the accessor-descriptor String allocation to a lazy path.
Requires Perry ≥ 0.5.29.
Reproduce: see bench/README.md for the full
setup (local Postgres, npm install, optional Rust toolchain) and
per-runner invocations. Short version:
cd bench && npm install && cd - PGHOST=127.0.0.1 PGPORT=55432 PGUSER=$(whoami) PGDATABASE=bench \ bench/run-all.sh
Every file under examples/ is a standalone program
that compiles under Perry AND runs under Node / Bun unchanged — point
at any Postgres with the libpq environment variables and they work.
See examples/README.md for the full list.
Quick smokes if you just want to verify the driver works for you:
# Node / Bun: PGHOST=… node --import tsx examples/perry-smoke.ts PATH=~/.bun/bin:$PATH PGHOST=… bun examples/perry-smoke.ts # Perry-native: /path/to/perry compile examples/perry-smoke.ts -o /tmp/perry-smoke PGHOST=… /tmp/perry-smoke
perry-smoke.ts covers the entire public API surface — connect,
auth, simple + extended queries, type codecs, error handling,
transactions — in ~100 lines. It's the canonical "does this driver
work for me" smoke.
bun test # everything bun test tests/unit # pure unit tests (no DB) bun test tests/integration # docker-compose matrix npm run test:tls:node # TLS suite on Node (Bun has a known tls.connect bug)
v0.2.0 — pre-1.0. The public surface is stable but not frozen. The driver passes the in-process mock-server matrix end-to-end. A real-Postgres Docker matrix (13 / 14 / 15 / 16 / 17) is the next milestone.
MIT.
PerryTS/postgres is a public repo on GitHub by PerryTS. Pure-TypeScript Postgres wire-protocol driver. Zero native dependencies. Runs on Perry, Node.js, and Bun.
It declares the MIT license on GitHub.
Its maker tagged it for macOS, Windows and Linux, or as Docker or cross-platform. That is declared by the maker; Take My Repo has not tested it.
Open "Take it" on its page: Take My Repo writes an install plan for your machine and hands it to your AI agent (Claude Code, Codex or Cursor), which asks you before each step. Take My Repo has not tested it on any machine.
Its last change on GitHub was on 2026-05-08. GitHub counts 0 open issues and pull requests. Take My Repo does not judge from that whether it is maintained.
Nobody has reviewed it on Take My Repo yet, which says nothing about its quality.
Incredibly fast JavaScript runtime, bundler, test runner, and package manager – all in one
The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
BlackHole is a modern macOS audio loopback driver that allows applications to pass audio to other applications with zero additional latency.
Reverse engineer anything with agents, from app behavior down to native binaries.
Stop renting your intelligence. Own it with AnythingLLM. Everything you need for a powerful local-first agent experience

⌥ Coding agent with the IDE wired in. Built by Stencil Labs.

A native TypeScript/JavaScript compiler written in Rust. Compiles TypeScript/JavaScript directly to executables using SWC and LLVM.

A fast, native JSON viewer built with Perry — TypeScript compiled to native ARM64
Pure-TypeScript Redis / Valkey wire-protocol driver. Runs unchanged on Node.js + Bun, AOT-compiles to a native binary via Perry (LLVM).
React-compatible renderer for Perry native desktop apps — write React/JSX, compile to native
An ECMAScript regex engine designed for explicit host memory ownership.
Embeddable, cross-platform event-loop driver that the host turns: bounded turn(), completion-shaped I/O on epoll, kqueue, IOCP, WASI and the web.
This page is also available as structured data, with the same sources and dates.
/api/v1/resources/gh/PerryTS/postgresTake My Repo has not tested this on your machine. Requirements come from the project's own documentation.