This is a complete rewrite to better support all the features that I was trying to get into v2. There are a few breaking changes from v2 beta, which some (myself included) was using in production, so I'm skipping a stable v2 release and going straight to v3.
Here are some of the new things available, but check the updated docs.
- Dynamic query builder based on raw sql
- Realtime subscribe to db changes through logical replication
- Multi-host support for High Availability setups
- Postgres input parameter types from
ParameterDescription - Deno support
- Cursors as async iterators
.describe()to only get query input types and column definitions- Support for Large Objects
max_lifetimefor connections- Cancellation of requests
- Converted to ESM (with CJS support)
- Typescript support (Credit @Minigugus)
Breaking changes from v2 -> v3
- Cursors are always called with
Resultarrays (previously cursor 1 would return a row object, where > 1 would return an array of rows) .writable()and.readable()is now async (returns a Promise that resolves to the stream)- Queries now returns a lazy promise instead of being executed immediately. This means the query won't be sent until awaited (.then, .catch, .finally is called) or until
.execute()is manually called. .stream()is renamed to.forEach- Returned results are now it's own
Resultclass extendingArrayinstead of an Array with extra properties (actually shouldn't be breaking unless you're doing something funny) - Parameters are now cast using the types returned from Postgres ParameterDescription with a fallback to the previously inferred types
- Only tested with node v12 and up
- Implicit array value to multiple parameter expansion removed (use sql([...]) instead)
Breaking changes from v1 -> v2 (v2 never moved on from beta)
- All identifiers from
sql()in queries are now always quoted - Undefined parameters are no longer allowed
- Rename timeout option to
idle_timeout - Default to 10 connections instead of number of CPUs
- Numbers that cannot be safely cast to JS Number are returned as string. This happens for eg,
select count(*)becausecount()returns a 64 bit integer (int8), so if you know yourcount()won't be too big for a js number just cast in your query to int4 likeselect count(*)::int