Home Explore Blog CI



postgresql

36th chunk of `doc/src/sgml/xfunc.sgml`
1a9cf53758ce1ce794b3b921c41f0e31e3ca9005b0ef40be0000000100000fa7
 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>

    <para>
     Composite types do not have a fixed layout like C structures.
     Instances of a composite type can contain null fields.  In
     addition, composite types that are part of an inheritance
     hierarchy can have different fields than other members of the
     same inheritance hierarchy.  Therefore,
     <productname>PostgreSQL</productname> provides a function
     interface for accessing fields of composite types from C.
    </para>

    <para>
     Suppose we want to write a function to answer the query:

<programlisting>
SELECT name, c_overpaid(emp, 1500) AS overpaid
    FROM emp
    WHERE name = 'Bill' OR name = 'Sam';
</programlisting>

     Using the version-1 calling conventions, we can define
     <function>c_overpaid</function> as:

<programlisting><![CDATA[
#include "postgres.h"
#include "executor/executor.h"  /* for GetAttributeByName() */

PG_MODULE_MAGIC;

PG_FUNCTION_INFO_V1(c_overpaid);

Datum
c_overpaid(PG_FUNCTION_ARGS)
{
    HeapTupleHeader  t = PG_GETARG_HEAPTUPLEHEADER(0);
    int32            limit = PG_GETARG_INT32(1);
    bool isnull;
    Datum salary;

    salary = GetAttributeByName(t, "salary", &isnull);
    if (isnull)
        PG_RETURN_BOOL(false);
    /* Alternatively, we might prefer to do PG_RETURN_NULL() for null salary. */

    PG_RETURN_BOOL(DatumGetInt32(salary) > limit);
}
]]>
</programlisting>
    </para>

    <para>
     <function>GetAttributeByName</function> is the
     <productname>PostgreSQL</productname> system function that
     returns attributes out of the specified row.  It has
     three arguments: the argument of type <type>HeapTupleHeader</type> passed
     into
     the  function, the name of the desired attribute, and a
     return parameter that tells whether  the  attribute
     is  null.   <function>GetAttributeByName</function> returns

Title: ABI Compatibility in PostgreSQL Minor Versions and Composite-Type Arguments
Summary
This section continues the discussion on ABI compatibility, focusing on PostgreSQL minor versions. While efforts are made to avoid ABI breaks, changes might occur, addressed with minimal invasiveness. It notes that many parts of the server aren't designed as public APIs, and changes there may impact extensions. The section then transitions to handling composite-type arguments in C functions. Composite types lack a fixed layout, and the text introduces the 'GetAttributeByName' function for accessing fields of composite types, providing an example of a C function, c_overpaid, that uses this function to determine if an employee's salary exceeds a specified limit.