postgres
4.1.1 · 11 Nov 2026Unlicense38.9M / weekRepositoryHomepagenpmAtom feed
Upgrading postgres From 3.0.4 to 4.1.1
27 releases in betweenevery note read
Reading releases, release notes and advisories…
- 1
- change to make
- 0
- advisories fixed
- 88
- new
- 110
- fixes
Before you upgrade
Tick each one off as you go- Breaking3.4.5
Security
- 4.0.0
A NUL character in a connection parameter can no longer add parameters (also in v3). A
database,userorconnectionvalue such as'db\0user\0postgres'was sent as further startup parameters, so an app that put untrusted input there, as with a database per tenant, could be made to log in as another user where that user needs no password, or withreplicationoroptionsset. A NUL in any protocol string, also in query text and identifiers, now rejects withNUL_CHARACTER. - 4.0.0
A column named
__proto__is an own property (also in v3). It became the prototype of the row, so a JSON value in it, for instance from a column alias built from user input, made the row inherit its properties (row.isAdmin), in query results and insql.subscriberows alike.
Release by release
- Fixed
A statement
sql.beginsends after its ownCOMMITorROLLBACKis rejected (#1320). A statement the callback did not await, sent between the transaction'sCOMMITorROLLBACKand the release of its connection, ran outside the transaction, and after a rollback its write was kept. It now rejects withUNSAFE_TRANSACTION, as a statement after the transaction has ended does. - Fixed
A command after a select in a multi-statement simple query has no columns (#1321). In
sql.unsafe('select …; rollback')theROLLBACKresult had the columns of theSELECTbefore it. - Fixed
A query queued behind one with an untyped string or boolean parameter resolves on Cloudflare Hyperdrive (#1319). Such a query is described first, and 4.1.0 sent its Bind, Execute and Sync together with the next query, which never resolved through Hyperdrive. On Cloudflare Workers the next query now waits until the described one is done, as in 3.4.9. Other runtimes still pipeline it.
- Fixed
.cursor()yields the rows ofSHOW,EXPLAINand other commands without a row count. Their last batch was only passed on when the command tag had a count, so a cursor over them yielded nothing.
- Fixed
- New
query_timeout(#1278). Seconds a query may take, waiting for a connection and running together, before it is canceled and rejects withQUERY_TIMEOUT. Off by default. Unlikestatement_timeoutit also ends a query whose server or network has gone silent, which TCP alone takes many minutes to notice. Transaction control queries andforEachare limited too; cursors, streams andsql.listenare not. - New
cancel_timeout, 5 seconds by default: how long a canceled query may take to end before its connection is closed. - New
sql.batch([queries])sends queries in one round trip with a single Sync: outside a transaction they commit or roll back together, and the batch rejects with the failing query's position inerror.index. - New
jsonon a transform (#1169). The built-in transforms rename the keys of JSON values in results but send JSON values as they are.json: falseleaves JSON values as they are both ways, andjson: truerenames their keys when sending too, with the transform'scolumn.to. Without it nothing changes.
- New
- Security
A NUL character in a connection parameter can no longer add parameters (also in v3). A
database,userorconnectionvalue such as'db\0user\0postgres'was sent as further startup parameters, so an app that put untrusted input there, as with a database per tenant, could be made to log in as another user where that user needs no password, or withreplicationoroptionsset. A NUL in any protocol string, also in query text and identifiers, now rejects withNUL_CHARACTER. - Security
A column named
__proto__is an own property (also in v3). It became the prototype of the row, so a JSON value in it, for instance from a column alias built from user input, made the row inherit its properties (row.isAdmin), in query results and insql.subscriberows alike. - New
Scheduling across connections: when every connection is busy, a query is pipelined on the connection where it should be done soonest, from how long each statement took before and how long what is in flight has run, and slow queries are kept together once the rest of the pool is needed for quick ones. In simulations of mixed workloads, the p99 of quick queries fell 2 to 100 times; on PostgreSQL, a 1 ms lookup no longer waits behind a report on a busy pool (p99.9 from 792 ms to 5 ms).
scheduler: falsepipelines on the busy connection with the fewest queries in flight instead; v3 went round-robin over the busy connections. Withmax: 1it is off, as there is only one connection. - New
queue_timeout: seconds a query, transaction or reserve may wait for a connection before it rejects withQUEUE_TIMEOUT, unsent (#1036, #824).
- Security
- New
Add support for sslnegotiation=direct - fixes #1104 7f80980
- Fixed
Prevent out of bound errors from commit-time failures de64f7a
- Fixed
Use lower max connections in Cloudflare Workers environment 94b7170
- Fixed
Fix PGAPPNAME env access by prioritizing connection.application_name 32feb25
- New
- Fixed
Fix reserved queries failing on connect e34826d
- Fixed
- New
Support env.PGAPPNAME and env.PGUSERNAME ef7afdb 9f38ea1
- Fixed
Fix failures in sql.reserve() connect shadowing real errors e8bb3b8
- Fixed
Fix stuck queries on non busy connections 76c13f2
- Fixed
Ensure non object errors thrown are handled properly a39dfef
- Fixed
Fixed typings for generic error code variants ad0ed44
- New
- Breaking
Remove "worker" export as we now have "workerd" for cloudflare cc688c6
- Fixed
Fix for deno 2 5fb70c1
- Fixed
Don't reassign to errors 4baef5e, f58cd4f
- Breaking
39 other lines we could not sort, mostly version bumps
- 4.0.0
The server decides the type of every parameter (
infer: falseby default) (#392). v3 typed aDateastimestamptz, a boolean, aBuffer, abigintand arrays of these from JavaScript; v4 sends them without a type and writes each value for the type the server asks for, as libpq does.timestamptzcolumns, values written to a column of their own type, strings, numbers and anything cast work as before. Outside UTC, aDatewritten to or compared with atimestampordatecolumn is taken as UTC instead of the session's local time, and atimestampis read as UTC, so it comes back as the instant that was written whatever the time zone. ADatewhere the query doesn't decide its type, such as indate_trunc('day', ${ date }), needs a cast (${ date }::timestamptz).infer: truekeeps v3's behaviour. - 4.0.0
Runtimes. Node.js 20 or later, Bun, and Cloudflare Workers; Deno through its Node.js compatibility. The CommonJS and Deno builds are gone: Postgres.js is an ES module, which
requirecan load on Node.js 20.19 and 22.12 and later (require('postgres').default). - 4.0.0
sql.array()is removed. Pass the array as it is, with a cast where the query doesn't decide its type:${ ids }::int. Callingsql.array()throwsARRAY_REMOVED. - 4.0.0
A transaction the server rolled back rejects. When the server answers COMMIT with ROLLBACK,
sql.beginrejects withTRANSACTION_ROLLED_BACK; v3 took it as a commit. - 4.0.0
A released connection stays released. A query on a reserved
sqlafterrelease(), or on a transaction'ssqlafter it has committed or rolled back, rejects; v3 ran it on whatever connection it then had. Releasing a reserved connection while its ownBEGINis still open closes it instead of returning an open transaction to the pool. - 4.0.0
An unsafe
beginoutsidesql.begin, a reserved connection ormax: 1rejects withUNSAFE_TRANSACTIONand is rolled back. A query that looks like it may open a transaction runs alone on its connection, so nothing else lands in it, and any query that leaves its connection in a transaction is rolled back and rejected. v3 rejectedBEGINbut left the transaction open. A script that opens and closes its own transaction in one query, such as a migration file withBEGINandCOMMIT, runs; v3 ran it and still rejected it. - 4.0.0
A query that cannot be built or serialized inside a transaction aborts the transaction, in
sql.begin(#1236, #1238) or one opened by hand on a reserved connection, just as a server error would: the queries after it fail with25P02and a laterCOMMITanswersROLLBACK. v3 skipped the query and let the rest commit. - 4.0.0
Domains that exist when the pool starts are read and written as their base type, so a domain over
intcomes back as an array of numbers; v3 returned the text. - 4.0.0
A connection refused for too many connections (
53300) is retried withbackoffuntilconnect_timeouthas passed, and the waiting queries reject with that error only then. Such a refusal is often momentary: connections opened at the same time against a connection limit can all be refused while the server counts them. v3 rejected the queries of the refused connection at once. - 4.0.0
No host matching
target_session_attrsrejects withCONNECTION_DESTROYEDinstead of retrying forever.
6 internal lines (docs, tests, tooling) left out.
A whole project to check? Paste its package.json in the dependency check: every deprecated, outdated or vulnerable dependency, with what to upgrade to. Free, no account.