From e54a42ac9d49ef9cd660d1bf55f09c88bb841ee9 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Wed, 31 Jul 2024 11:08:28 +0200 Subject: [PATCH] Add API and ABI stability guidance to the C language docs Includes guidance for major and minor version releases, and sets reasonable expectations for extension developers to follow. Author: David Wheeler, Peter Eisentraut Discussion: https://www.postgresql.org/message-id/flat/5DA9F9D2-B8B2-43DE-BD4D-53A4160F6E8D%40justatheory.com --- doc/src/sgml/xfunc.sgml | 136 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 5b584a4f144..bf76490cbc0 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -2704,6 +2704,142 @@ CREATE FUNCTION concat_text(text, text) RETURNS text &dfunc; + + Server API and ABI Stability Guidance + + + This section contains guidance to authors of extensions and other server + plugins about API and ABI stability in the + PostgreSQL server. + + + + General + + + The PostgreSQL server contains several + well-demarcated APIs for server plugins, such as the function manager + (fmgr, described in this chapter), + SPI (), and various hooks + specifically designed for extensions. These interfaces are carefully + managed for long-term stability and compatibility. However, the entire + set of global functions and variables in the server effectively + constitutes the publicly usable API, and most of it was not designed + with extensibility and long-term stability in mind. + + + + Therefore, while taking advantage of these interfaces is valid, the + further one strays from the well-trodden path, the likelier it will be + that one might encounter API or ABI compatibility issues at some point. + Extension authors are encouraged to provide feedback about their + requirements, so that over time, as new use patterns arise, certain + interfaces can be considered more stabilized or new, better-designed + interfaces can be added. + + + + + API Compatibility + + The API, or application programming interface, is the + interface used at compile time. + + + + Major Versions + + There is no promise of API compatibility between + PostgreSQL major versions. Extension code + therefore might require source code changes to work with multiple major + versions. These can usually be managed with preprocessor conditions + such as #if PG_VERSION_NUM >= 160000. + Sophisticated extensions that use interfaces beyond the well-demarcated + ones usually require a few such changes for each major server version. + + + + + Minor Versions + + PostgreSQL makes an effort to avoid server + API breaks in minor releases. In general, extension code that compiles + and works with a minor release should also compile and work with any + other minor release of the same major version, past or future. + + + + When a change is required, it will be carefully + managed, taking the requirements of extensions into account. Such + changes will be communicated in the release notes (). + + + + + + ABI Compatibility + + The ABI, or application binary interface, is the + interface used at run time. + + + + Major Versions + + Servers of different major versions have intentionally incompatible + ABIs. Extensions that use server APIs must therefore be re-compiled for + each major release. The inclusion of PG_MODULE_MAGIC + (see ) ensures that code compiled for + one major version will be rejected by other major versions. + + + + + Minor Versions + + PostgreSQL makes an effort to avoid server + ABI breaks in minor releases. In general, an extension compiled against + any minor release should work with any other minor release of the same + major version, past or future. + + + + When a change is required, + PostgreSQL will choose the least invasive + change possible, for example by squeezing a new field into padding + space or appending it to the end of a struct. These sorts of changes + should not impact extensions unless they use very unusual code + patterns. + + + + In rare cases, however, even such non-invasive changes may be + impractical or impossible. In such an event, the change will be + carefully managed, taking the requirements of extensions into account. + Such changes will also be documented in the release notes (). + + + + Note, however, that many parts of the server are not designed or + maintained as publicly-consumable APIs (and that, in most cases, the + actual boundary is also not well-defined). If urgent needs arise, + changes in those parts will naturally be made with less consideration + for extension code than changes in well-defined and widely used + interfaces. + + + + Also, in the absence of automated detection of such changes, this is + not a guarantee, but historically such breaking changes have been + extremely rare. + + + + + + Composite-Type Arguments