Horton

libpq-oauth: a mid-beta naming check

Jacob Champion <jacob.champion@enterprisedb.com>

View thread
From: Jacob Champion <jacob.champion@enterprisedb.com>
To: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
Cc: Christoph Berg <myon@debian.org>, Jelte Fennema-Nio <postgres@jeltef.nl>, Peter Eisentraut <peter@eisentraut.org>, Andres Freund <andres@anarazel.de>, Tom Lane <tgl@sss.pgh.pa.us>, Bruce Momjian <bruce@momjian.us>, Thomas Munro <thomas.munro@gmail.com>, Nazir Bilal Yavuz <byavuz81@gmail.com>, Antonin Houska <ah@cybertec.at>, Wolfgang Walther <walther@technowledgy.de>, Devrim Gündüz <devrim@gunduz.org>, Daniel Gustafsson <daniel@yesql.se>
Date: 2025-08-04T23:20:29Z
Lists: pgsql-hackers

Commits

Same data as JSON: GET /api/v1/messages/:b64id/commits the thread's linked commits as JSON, with link sources. API reference →

  1. meson: Fix install-quiet after clean

  2. oauth: Run Autoconf tests with correct compiler flags

  3. Link libpq with libdl if the platform needs that.

  4. Doc: correct spelling of meson switch.

  5. oauth: Correct SSL dependency for libpq-oauth.a

  6. oauth: Fix Autoconf build on macOS

  7. oauth: Move the builtin flow into a separate module

  8. Remove a stray "pgrminclude" annotation

  9. oauth: Simplify copy of PGoauthBearerRequest

  10. oauth: Improve validator docs on interruptibility

  11. oauth: Disallow synchronous DNS in libcurl

  12. oauth: Fix postcondition for set_timer on macOS

  13. oauth: Use IPv4-only issuer in oauth_validator tests

  14. Work around OAuth/EVFILT_TIMER quirk on NetBSD.

  15. oauth: Fix incorrect const markers in struct

  16. Add missing entry to oauth_validator test .gitignore

  17. cirrus: Temporarily fix libcurl link error

  18. Add support for OAUTHBEARER SASL mechanism

  19. libpq: Handle asynchronous actions during SASL

  20. require_auth: prepare for multiple SASL mechanisms

  21. Move PG_MAX_AUTH_TOKEN_LENGTH to libpq/auth.h

  22. Make SASL max message length configurable

  23. jsonapi: fully initialize dummy lexer

  24. common/jsonapi: support libpq as a client

  25. Remove fe_memutils from libpgcommon_shlib

  26. Revert ECPG's use of pnstrdup()

  27. Explicitly require password for SCRAM exchange

  28. Refactor SASL exchange to return tri-state status

On Wed, Apr 30, 2025 at 10:59 AM Jacob Champion
<jacob.champion@enterprisedb.com> wrote:
>
> I still see the choice of naming (with its forced-ABI break
> every major version) as needing more scrutiny, and probably worth a
> Revisit entry.

It is now time to revisit.

= The Status Quo =

The libpq-oauth module is loaded on-demand, during the first use of
OAuth authentication, so users who don't want the behavior don't have
to install it. This module is named "libpq-oauth-18.so" for the PG18
release. So libpq v18 will always load the 18 OAuth behavior, libpq
v19 will load the 19 OAuth behavior, etc. Builds on HEAD have already
switched to -19, which is not yet any different from -18.

The internal API injects some libpq internals into the libpq-oauth
module. The ABI for this is assumed to break during each major version
release, so I don't have to watch the boundary like a hawk, and other
maintainers hopefully won't be saddled with breakage reports if I get
hit by a bus. (This is another advantage to using the -MAJOR naming
scheme.) And pg_conn in particular is given more protections: we can
still change its member offsets in minor versions without any ABI
breakage.

During major-version upgrades, if a packager doesn't provide a
side-by-side installation of the -18 and -19 modules, there is a
hazard: an already-loaded v18 libpq might find that the -18 module no
longer exists on disk, which would require a restart of the affected
application to pick up the v19 libpq. This is not really a consequence
of the -MAJOR naming scheme -- it's a consequence of delay-loaded
libraries that go through an ABI version bump -- but the naming scheme
makes the problem extremely visible.

The annoying part is that, if 19 doesn't change anything in the OAuth
flow compared to 18, I will basically have made busywork for our
packagers for no reason. But my goal for v19 is to replace the
internally coupled API with a public API, so that users can swap in
their own flows for use with our utilities. As far as I know, that
work necessarily includes designing a stable ABI and figuring out a
trusted place that users can put their plugins into. If we can do
both, I think we can get rid of the -MAJOR versioning scheme entirely,
because our use case will have been subsumed by the more general
framework.

So, as we approach Beta 3: can anyone think of a way that this plan will fail?

Thanks,
--Jacob