On 18.06.24 00:37, David E. Wheeler wrote:
ABI Policy
==========
The PostgreSQL core team maintains two application binary interface (ABI)
guarantees: one for major releases and one for minor releases.
Major Releases
--------------
Applications that use the PostgreSQL APIs
This is probably a bit confusing. This might as well mean client
application code against libpq. Better something like "server plugin
code that uses the PostgreSQL server APIs".
must be compiled for each major release supported by the application. The
inclusion of `PG_MODULE_MAGIC` ensures that code compiled for one major version
will rejected by other major versions.
ok so far
Furthermore, new releases may make API changes that require code changes. Use
the `PG_VERSION_NUM` constant to adjust code in a backwards compatible way:
``` c
#if PG_VERSION_NUM >= 160000
#include "varatt.h"
#endif
```
But now we're talking about API. That might be subject of another
document or another section in this one, but it seems confusing to mix
this with the ABI discussion.
PostgreSQL avoids unnecessary API changes in major releases, but usually ships
a few necessary API changes, including deprecation, renaming, and argument
variation.
Obviously, as a practical matter, there won't be random pointless
changes. But I wouldn't go as far as writing anything down about how
these APIs are developed.
In such cases the incompatible changes will be listed in the Release Notes.
I don't think anyone is signing up to do that.
Minor Releases
--------------
PostgreSQL makes an effort to avoid both API and ABI breaks in minor releases.
In general, an application compiled against any minor release will work with
any other minor release, past or future.
When a change *is* required, PostgreSQL will choose the least invasive way
possible, for example by squeezing a new field into padding space or appending
it to the end of a struct. This sort of change should not impact dependent
applications unless, they use `sizeof(the struct)` on a struct with an appended
field, or create their own instances of such structs --- patterns best avoided.
In rare cases, however, even such non-invasive changes may be impractical or
impossible. In such an event, the change will be documented in the Release
Notes, and details on the issue will also be posted to [TBD; mail list? Blog
post? News item?].
I think one major problem besides actively avoiding or managing such
minor-version ABI breaks is some automated detection. Otherwise, this
just means "we try, but who knows".
