database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-05-03 22:24:49 +03:00
Code

Add API and ABI stability guidance to the C language docs

Browse Source 
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
This commit is contained in:
Peter Eisentraut 2024-07-31 11:08:28 +02:00
parent 4f29394ea9
commit e54a42ac9d
1 changed files with 136 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

136
doc/src/sgml/xfunc.sgml
View File

@ -2704,6 +2704,142 @@ CREATE FUNCTION concat_text(text, text) RETURNS text
&dfunc;
<sect2 id="xfunc-api-abi-stability-guidance">
<title>Server API and ABI Stability Guidance</title>
<para>
This section contains guidance to authors of extensions and other server
plugins about API and ABI stability in the
<productname>PostgreSQL</productname> server.
</para>
<sect3 id="xfunc-guidance-general">
<title>General</title>
<para>
The <productname>PostgreSQL</productname> server contains several
well-demarcated APIs for server plugins, such as the function manager
(<acronym>fmgr</acronym>, described in this chapter),
<acronym>SPI</acronym> (<xref linkend="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.
</para>
<para>
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.
</para>
</sect3>
<sect3 id="xfunc-guidance-api-compatibility">
<title>API Compatibility</title>
<para>
The <acronym>API</acronym>, or application programming interface, is the
interface used at compile time.
</para>
<sect4 id="xfunc-guidance-api-major-versions">
<title>Major Versions</title>
<para>
There is <emphasis>no</emphasis> promise of API compatibility between
<productname>PostgreSQL</productname> 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 <literal>#if PG_VERSION_NUM &gt;= 160000</literal>.
Sophisticated extensions that use interfaces beyond the well-demarcated
ones usually require a few such changes for each major server version.
</para>
</sect4>
<sect4 id="xfunc-guidance-api-mninor-versions">
<title>Minor Versions</title>
<para>
<productname>PostgreSQL</productname> 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.
</para>
<para>
When a change <emphasis>is</emphasis> required, it will be carefully
managed, taking the requirements of extensions into account. Such
changes will be communicated in the release notes (<xref
linkend="release"/>).
</para>
</sect4>
</sect3>
<sect3 id="xfunc-guidance-abi-compatibility">
<title>ABI Compatibility</title>
<para>
The <acronym>ABI</acronym>, or application binary interface, is the
interface used at run time.
</para>
<sect4 id="xfunc-guidance-abi-major-versions">
<title>Major Versions</title>
<para>
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 <literal>PG_MODULE_MAGIC</literal>
(see <xref linkend="xfunc-c-dynload"/>) ensures that code compiled for
one major version will be rejected by other major versions.
</para>
</sect4>
<sect4 id="xfunc-guidance-abi-mninor-versions">
<title>Minor Versions</title>
<para>
<productname>PostgreSQL</productname> 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.
</para>
<para>
When a change <emphasis>is</emphasis> required,
<productname>PostgreSQL</productname> 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.
</para>
<para>
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 (<xref
linkend="release"/>).
</para>
<para>
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.
</para>
<para>
Also, in the absence of automated detection of such changes, this is
not a guarantee, but historically such breaking changes have been
extremely rare.
</para>
</sect4>
</sect3>
</sect2>
<sect2 id="xfunc-c-composite-type-args">
<title>Composite-Type Arguments</title>