database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-30 11:03:19 +03:00
Code Activity

doc: Add minimal C and SQL example to add a custom table AM handler

Browse Source 
The documentation was rather sparse on this matter and there is no
extension in-core that shows how to do it.  Adding a small example will
hopefully help newcomers.  An advantage of writing things this way is
that the contents are not going to rot because of backend changes.

Author: Phil Eaton
Reviewed-by: Robert Haas, Fabrízio de Royes Mello
Discussion: https://postgr.es/m/CAByiw+r+CS-ojBDP7Dm=9YeOLkZTXVnBmOe_ajK=en8C_zB3_g@mail.gmail.com
This commit is contained in:
Michael Paquier
2024-10-07 15:47:40 +09:00
parent 2e7c4abe5a
commit e09fff7c98
1 changed files with 49 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
doc/src/sgml/tableam.sgml
View File

@ -35,13 +35,60 @@
argument of type <type>internal</type> and to return the pseudo-type argument of type <type>internal</type> and to return the pseudo-type
<type>table_am_handler</type>. The argument is a dummy value that simply <type>table_am_handler</type>. The argument is a dummy value that simply
serves to prevent handler functions from being called directly from SQL commands. serves to prevent handler functions from being called directly from SQL commands.
</para>
<para>
Here is how an extension SQL script file might create a table access
method handler:
</para>
<programlisting>
CREATE OR REPLACE FUNCTION my_tableam_handler(internal)
RETURNS table_am_handler AS 'my_extension', 'my_tableam_handler'
LANGUAGE C STRICT;
CREATE ACCESS METHOD myam TYPE TABLE HANDLER my_tableam_handler;
</programlisting>
<para>
The result of the function must be a pointer to a struct of type The result of the function must be a pointer to a struct of type
<structname>TableAmRoutine</structname>, which contains everything that the <structname>TableAmRoutine</structname>, which contains everything that the
core code needs to know to make use of the table access method. The return core code needs to know to make use of the table access method. The return
value needs to be of server lifetime, which is typically achieved by value needs to be of server lifetime, which is typically achieved by
defining it as a <literal>static const</literal> variable in global defining it as a <literal>static const</literal> variable in global scope.
scope. The <structname>TableAmRoutine</structname> struct, also called the </para>
<para>
Here is how a source file with the table access method handler might
look like:
</para>
<programlisting><![CDATA[
#include "postgres.h"
#include "access/tableam.h"
#include "fmgr.h"
PG_MODULE_MAGIC;
static const TableAmRoutine my_tableam_methods = {
.type = T_TableAmRoutine,
/* Methods of TableAmRoutine omitted from example, add them here. */
};
PG_FUNCTION_INFO_V1(my_tableam_handler);
Datum
my_tableam_handler(PG_FUNCTION_ARGS)
{
PG_RETURN_POINTER(&my_tableam_methods);
}
]]>
</programlisting>
<para>
The <structname>TableAmRoutine</structname> struct, also called the
access method's <firstterm>API struct</firstterm>, defines the behavior of access method's <firstterm>API struct</firstterm>, defines the behavior of
the access method using callbacks. These callbacks are pointers to plain C the access method using callbacks. These callbacks are pointers to plain C
functions and are not visible or callable at the SQL level. All the functions and are not visible or callable at the SQL level. All the