From e09fff7c980a8b545a18e119be41bf67cd2e9182 Mon Sep 17 00:00:00 2001
From: Michael Paquier <michael@paquier.xyz>
Date: Mon, 7 Oct 2024 15:47:40 +0900
Subject: [PATCH] doc: Add minimal C and SQL example to add a custom table AM
 handler
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

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
---
 doc/src/sgml/tableam.sgml | 51 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 49 insertions(+), 2 deletions(-)

diff --git a/doc/src/sgml/tableam.sgml b/doc/src/sgml/tableam.sgml
index 4b37f2e5a60..9ccf5b739ed 100644
--- a/doc/src/sgml/tableam.sgml
+++ b/doc/src/sgml/tableam.sgml
@@ -35,13 +35,60 @@
   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
   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
   <structname>TableAmRoutine</structname>, which contains everything that the
   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
-  defining it as a <literal>static const</literal> variable in global
-  scope. The <structname>TableAmRoutine</structname> struct, also called the
+  defining it as a <literal>static const</literal> variable in global scope.
+ </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
   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
-- 
2.30.2