pg@9.0 breaking changes ideas

[brianc]

I'd like to gather feedback on breaking changes to make for pg@9.0. I'd like to start working on getting pg@9.0 out sometime in March so there's plenty of time for ideas!

[brianc]

remove queryQueue

The "query queue" idea shipped w/ the original version of node-postgres some 15 years ago. It gums up the internals of the client a bit, isn't how most database drivers behave, and is just weird. Espesh w/ async/await I don't think its used much at all on purpose. So, my plan is to deprecate it very soon in the pg@8.x branch - if someone adds a query to the client's internal query queue while the client is already executing a query in flight, I'll log a 1 time deprecation warning to the terminal. In 9.x the behavior will change to throw an error if a query is sent while another query is in flight.

[brianc]

update pg-types

Because the version of pg-types I'm using is so many years behind the mainline branch I'm sure there are some breaking changes. I will not ever change the default "timezoneless date parsing" to be a different timezone, so either that needs to get reverted it pg-types 5.x or I'll have to patch over that part. Changing that would be a very subtle breaking change with no way to lint for it as it would be based on database types so I don't think its worth it...even though yeah if I had started out today I would try to align it w/ the way psql returned timezoneless dates. I think there might be 1 or 2 other breaking changes in pg-types. The tests should inform what needs to be reported.

[charmander]

Maybe this is too ambitious for pg 9, but: currently, every new pg-types parser is technically a breaking change. How about requiring fields with no type parser to be accessed another way, e.g. a row.rawFields object? This would make implementing binary mode safer, too.

[n-e]

I'm not sure what the "timezoneless date parsing" does, but if it's subtly incorrect, a solution that would make the change obvious could be to return the data as a string, like for the DATE type (a change I'm very happy about).

[brianc]

pool.end() does not render the pool unusable afterward.

2 things actually.

1. await pool.end() doesn't properly wait for the pool to end AFAIK, so that should be fixed.
2. I don't see a reason calling await pool.end() couldn't leave the pool in a usable state going forward. This would mostly be backwards compatible, but would make it easy in serverless environments to end the pool when the worker shuts down but still be able to keep a global pool reference which is a common pattern.

[cesco69]

I'd like to gather feedback on breaking changes to make for pg@9.0. I'd like to start working on getting pg@9.0 out sometime in March so there's plenty of time for ideas!

Just a suggestion: consider adding a link to this discussion in the README and creating a pinned issue. This way, the discussion would get more visibility.

[brianc]

remove pgpass

Its already deprecated. Make sure it's easy to use as an addon and keep tests for it...just make it a dev dependency for tests.

[brianc]

remove bring your own promise

It's 2026 now...probably high time we just use the built in promise library. It's already been deprecated, so its just the removal left.

[charmander]

add default no-op error listener to pool and client

Returning errors from all operations (which is already what happens after an error event) is probably enough as a default; no need to crash the process.

[brianc]

ah yeah that's a great idea. i love it.

[charmander]

require socket to be configured (and connected?) by socket creator

I’ll try to get around to expanding on this later, but in short:

• new config option socketOptions: {keepAlive, keepAliveInitialDelay [sic], …}
• default socket is new net.Socket({noDelay: true, ...socketOptions}).connect(…)
• if socket is passed, no further initialization

(see compatibility issues with Cloudflare sockets, for one; this single change might be enough to allow generic stream to be passed as socket?)

[brianc]

yah being able to pass in something that satisfies the very basics of a socket (if you do pass a socket) would probably simplify pg-cloudflare a bunch. I also think cloudflare node compatibility has improved. I'm interested to hear more about this!

[sirkostya009]

bundle TS type definitions

removes need in installing @types/pg

[brianc]

you think i should maintain the type definitions myself as well? Like pull them into the lib? or just install @types/pg as an optional dependency

[sant123]

Yes, you should maintain the type definitions by yourself 🙏🏼

[brianc]

yeah i could do that. i'd start by just copy/pasting them in from the definitely-typed library & take it from there. it's a good idea. I do want to eventually convert pg to typescript too so that's a good step on the path.

[sirkostya009]

move to a promise-only API

would make library code much, much simpler.

maybe also raise the required Node version and consequently the ECMA spec - possibly reducing code complexity and dependencies by using more native stuff.

[brianc]

maybe also raise the required Node version

yah this is definitely happening!

[brianc]

move to a promise-only API

Last time I mentioned doing this there were some vocal folks who were very much against it. I will consider it but can't promise it!

[tpetry]

I guess last time is a long time ago? I don't see any new packages (without legacy stuff) being built anymore in the old callback style

[tpetry]

Temporal support

Temporals are now shipped in Chrome v8 and will be enabled in nodejs soon. There are a ton of issues listed because of weird date, timezone etc behaviour. The default mode could still be to use Date but with the recommendation to use Temporal and mark using Date objects as legacy stuff. Still supported (for now) but its not the feature and maybe no more further development on that.

[tpetry]

AsyncDisposable

You always have to really really take care of ending connections or returning them to the pool. Don't know how many bugs I and others had in the past because some part was not working correctly. Or didn't work correctly in case of thrown exceptions that stuff was not cleaned up. But this has been solved now for so long.

await using connection = pool.connect();
await doMoreStuff();

With pools and connections supporting the disposable interface, we can be asolutely sure that the connection is released after more stuff executed - whether it succeeds correctly or something fails.

[tpetry]

Configurable Type Parsing

Currently you must set type parsing options. So if you want to e.g. convert 64bit integers to BigInt and not use strings, you must configure this globally on the pg.types object. So its opt-in for everything and can produce problems when some 3rd party code is expecting to run with default settings. It would be great to control the type parsing in the connections object. So every pool could have its own settings

[tpetry]

Automatic Prepared Statements

So node:sqlite added a nice fature called Tag Stores. The idea is that queries are automatically prepared before running them and reused later when the same query string is used. No effort for the user and everything is handled internally. Would be great to have something similar.