From 036bd1e0d6b36c8a1ee28bae5665b0f2ea1cb2d0 Mon Sep 17 00:00:00 2001 From: "David E. Wheeler" Date: Thu, 27 Jun 2024 18:06:09 -0400 Subject: [PATCH v3] Add API an ABI 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 | 134 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 1d0b65193e..e4a46e1c9c 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -2704,6 +2704,140 @@ CREATE FUNCTION concat_text(text, text) RETURNS text &dfunc; + + Server API and ABI Guidance + + + This section contains guidance to authors of extensions and other server + plugins about ABI and API stability in the + PostgreSQL server. + + + + General + + + The PostgreSQL server contains several + well-delimited APIs for server plugins, such as the function manager + (fmgr), + 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 ABI or API 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-defined + 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 . + + + + + + 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 + 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 . + + + + 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 -- 2.45.2