Skip to content

Commit 9b56cc3

Browse files
author
Nikita Malakhov
committed
Toaster API documentation package: SQL syntax (CREATE TABLE, ALTER TABLE, CREATE TOASTER) + Toaster API short explanation
0006_toasterapi_docs patch
1 parent f737ba6 commit 9b56cc3

File tree

6 files changed

+275
-2
lines changed

6 files changed

+275
-2
lines changed

‎doc/src/sgml/catalogs.sgml

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8132,6 +8132,71 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
81328132
</sect1>
81338133

81348134

8135+
<sect1 id="catalog-pg-toaster">
8136+
<title><structname>pg_toaster</structname></title>
8137+
8138+
<indexterm zone="catalog-pg-toaster">
8139+
<primary>pg_toaster</primary>
8140+
</indexterm>
8141+
8142+
<para>
8143+
The catalog <structname>pg_toaster</structname> stores information
8144+
about all available toaster. There are 2 toasters already provided
8145+
with database: default (deftoaster) and sample (dummy_toaster).
8146+
</para>
8147+
8148+
<para>
8149+
Every toaster registered in database is stored in <structname>pg_toaster</structname>.
8150+
This table contains toaster OID, toaster name and related handler procedire.
8151+
</para>
8152+
8153+
<table>
8154+
<title><structname>pg_toaster</structname> Columns</title>
8155+
<tgroup cols="1">
8156+
<thead>
8157+
<row>
8158+
<entry role="catalog_table_entry"><para role="column_definition">
8159+
Column Type
8160+
</para>
8161+
<para>
8162+
Description
8163+
</para></entry>
8164+
</row>
8165+
</thead>
8166+
8167+
<tbody>
8168+
<row>
8169+
<entry role="catalog_table_entry"><para role="column_definition">
8170+
<structfield>oid</structfield> <type>oid</type>
8171+
</para>
8172+
<para>
8173+
Toaster identifier
8174+
</para></entry>
8175+
</row>
8176+
8177+
<row>
8178+
<entry role="catalog_table_entry"><para role="column_definition">
8179+
<structfield>namedata</structfield> <type>toaster_name</type>
8180+
</para>
8181+
<para>
8182+
Toaster name
8183+
</para></entry>
8184+
</row>
8185+
8186+
<row>
8187+
<entry role="catalog_table_entry"><para role="column_definition">
8188+
<structfield>regproc</structfield> <type>Tsr handler</type>
8189+
</para>
8190+
<para>
8191+
Toast API handler procedure
8192+
</para></entry>
8193+
</row>
8194+
</tbody>
8195+
</tgroup>
8196+
</table>
8197+
</sect1>
8198+
8199+
81358200
<sect1 id="catalog-pg-transform">
81368201
<title><structname>pg_transform</structname></title>
81378202

‎doc/src/sgml/ref/allfiles.sgml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,7 @@ Complete list of usable sgml source files in this directory.
9090
<!ENTITY createTable SYSTEM "create_table.sgml">
9191
<!ENTITY createTableAs SYSTEM "create_table_as.sgml">
9292
<!ENTITY createTableSpace SYSTEM "create_tablespace.sgml">
93+
<!ENTITY createToaster SYSTEM "create_toaster.sgml">
9394
<!ENTITY createTransform SYSTEM "create_transform.sgml">
9495
<!ENTITY createTrigger SYSTEM "create_trigger.sgml">
9596
<!ENTITY createTSConfig SYSTEM "create_tsconfig.sgml">

‎doc/src/sgml/ref/create_table.sgml

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ PostgreSQL documentation
2222
<refsynopsisdiv>
2323
<synopsis>
2424
CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] <replaceable class="parameter">table_name</replaceable> ( [
25-
{ <replaceable class="parameter">column_name</replaceable> <replaceable class="parameter">data_type</replaceable> [ STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN } ] [ COMPRESSION <replaceable>compression_method</replaceable> ] [ COLLATE <replaceable>collation</replaceable> ] [ <replaceable class="parameter">column_constraint</replaceable> [ ... ] ]
25+
{ <replaceable class="parameter">column_name</replaceable> <replaceable class="parameter">data_type</replaceable> [ STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN } ] [ TOASTER <replaceable>compression_method</replaceable> ] [ COMPRESSION <replaceable>compression_method</replaceable> ] [ COLLATE <replaceable>collation</replaceable> ] [ <replaceable class="parameter">column_constraint</replaceable> [ ... ] ]
2626
| <replaceable>table_constraint</replaceable>
2727
| LIKE <replaceable>source_table</replaceable> [ <replaceable>like_option</replaceable> ... ] }
2828
[, ... ]
@@ -324,6 +324,18 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
324324
</listitem>
325325
</varlistentry>
326326

327+
<varlistentry>
328+
<term> <literal>SET TOASTER <replaceable class="parameter">toaster_name</replaceable></literal></term>
329+
<listitem>
330+
<para>
331+
This form sets the toaster function for toastable column. This function
332+
must implement how toastable data is stored, and fetched. Also, toast
333+
function could compress data and use different access methods.
334+
See <xref linkend="storage-toast"/> for more information.
335+
</para>
336+
</listitem>
337+
</varlistentry>
338+
327339
<varlistentry>
328340
<term><literal>COMPRESSION <replaceable class="parameter">compression_method</replaceable></literal></term>
329341
<listitem>

‎doc/src/sgml/ref/create_table_as.sgml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ PostgreSQL documentation
2222
<refsynopsisdiv>
2323
<synopsis>
2424
CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] <replaceable>table_name</replaceable>
25-
[ (<replaceable>column_name</replaceable> [, ...] ) ]
25+
[ (<replaceable>column_name</replaceable> [ STORAGE external TOASTER <replaceable>toaster_name</replaceable> ] [, ...] ) ]
2626
[ USING <replaceable class="parameter">method</replaceable> ]
2727
[ WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) | WITHOUT OIDS ]
2828
[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
@@ -122,6 +122,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
122122
<para>
123123
The name of a column in the new table. If column names are not
124124
provided, they are taken from the output column names of the query.
125+
Toaster could be assigned to toastable column with expression
126+
<literal>STORAGE external TOASTER <replaceable>toaster_name</replaceable></literal>
125127
</para>
126128
</listitem>
127129
</varlistentry>

‎doc/src/sgml/ref/create_toaster.sgml

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
<!--
2+
doc/src/sgml/ref/create_toaster.sgml
3+
PostgreSQL documentation
4+
-->
5+
6+
<refentry id="sql-createtoaster">
7+
<indexterm zone="sql-createtoaster">
8+
<primary>CREATE TOASTER</primary>
9+
</indexterm>
10+
11+
<refmeta>
12+
<refentrytitle>CREATE TOASTER</refentrytitle>
13+
<manvolnum>7</manvolnum>
14+
<refmiscinfo>SQL - Language Statements</refmiscinfo>
15+
</refmeta>
16+
17+
<refnamediv>
18+
<refname>CREATE TOASTER</refname>
19+
<refpurpose>define a new toaster</refpurpose>
20+
</refnamediv>
21+
22+
<refsynopsisdiv>
23+
<synopsis>
24+
CREATE TOASTER [ IF NOT EXISTS ] <replaceable class="parameter">toaster_name</replaceable> HANDLER <replaceable class="parameter">handler_name</replaceable>
25+
26+
</synopsis>
27+
28+
</refsynopsisdiv>
29+
30+
<refsect1 id="sql-createtoaster-description">
31+
<title>Description</title>
32+
33+
<para>
34+
<command>CREATE TOASTER</command> will attach already defined handler <replaceable class="parameter">handler_name</replaceable>
35+
function to a toaster with name <replaceable class="parameter">toaster_name</replaceable>
36+
in the current database. This function will be used for toasting and de-toasting
37+
values in toasted columns for tables where this toaster is set in <literal>CREATE TABLE
38+
...TOASTER <replaceable class="parameter">toaster_name</replaceable>...</literal> or
39+
<literal>ALTER TABLE ALTER COLUMN ... SET TOASTER <replaceable class="parameter">toaster_name</replaceable>...</literal>
40+
command. New OID is assigned to a <replaceable class="parameter">toaster_name</replaceable> automatically.
41+
</para>
42+
43+
<para>
44+
To be able to create a table, you must have <literal>USAGE</literal>
45+
privilege on all column types or the type in the <literal>OF</literal>
46+
clause, respectively.
47+
</para>
48+
</refsect1>
49+
50+
<refsect1>
51+
<title>Parameters</title>
52+
53+
<variablelist>
54+
55+
<varlistentry>
56+
<term><literal>IF NOT EXISTS</literal></term>
57+
<listitem>
58+
<para>
59+
Do not throw an error if a toaster with the same name already exists.
60+
A notice is issued in this case. Note that there is no guarantee that
61+
the existing toaster is anything like the one that would have been
62+
created.
63+
</para>
64+
</listitem>
65+
</varlistentry>
66+
67+
<varlistentry>
68+
<term><replaceable class="parameter">toaster_name</replaceable></term>
69+
<listitem>
70+
<para>
71+
The name of the toaster table to be created.
72+
</para>
73+
</listitem>
74+
</varlistentry>
75+
76+
<varlistentry>
77+
<term><replaceable class="parameter">handler_name</replaceable></term>
78+
<listitem>
79+
<para>
80+
The name of toast functions handler procedure. Must be reigstered before
81+
using with <literal>CREATE FUNCTION</literal> command, example:
82+
CREATE FUNCTION dummy_toaster_handler(internal)
83+
RETURNS toaster_handler
84+
AS 'MODULE_PATHNAME'
85+
LANGUAGE C;
86+
</para>
87+
</listitem>
88+
</varlistentry>
89+
</variablelist>
90+
91+
92+
<refsect1 id="sql-createtoaster-examples">
93+
<title>Examples</title>
94+
95+
<para>
96+
Create toaster <structname>dummy_toaster</structname> with handler
97+
<structname>dummy_toaster_handler</structname>:
98+
99+
<programlisting>
100+
CREATE FUNCTION dummy_toaster_handler(internal)
101+
RETURNS toaster_handler
102+
AS 'MODULE_PATHNAME'
103+
LANGUAGE C;
104+
105+
106+
CREATE TOASTER dummy_toaster HANDLER dummy_toaster_handler;
107+
108+
COMMENT ON TOASTER dummy_toaster IS 'dummy_toaster is a dummy toaster';
109+
</programlisting>
110+
</para>
111+
</refsect1>
112+
113+
<refsect1 id="sql-createtable-compatibility" xreflabel="Compatibility">
114+
<title>Compatibility</title>
115+
116+
<para>
117+
The <command>CREATE TABLE</command> command does not conform to the
118+
<acronym>SQL</acronym>.
119+
</para>
120+
</refsect1>
121+
122+
<refsect1>
123+
<title>See Also</title>
124+
125+
<simplelist type="inline">
126+
<member><xref linkend="sql-storage"/></member>
127+
<member><xref linkend="sql-createtable"/></member>
128+
<member><xref linkend="sql-createtableas"/></member>
129+
<member><xref linkend="sql-altertable"/></member>
130+
</simplelist>
131+
</refsect1>
132+
</refentry>

‎doc/src/sgml/storage.sgml

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -590,6 +590,67 @@ tuple would otherwise be too big.
590590

591591
</sect2>
592592

593+
<sect2 id="storage-toasterapi">
594+
<title>Toaster API</title>
595+
596+
<para>
597+
Currently, it is possible to develop and assign custom toaster functions, which could
598+
implement different functionality, use other storage strategies and access methods.
599+
This API consists of toast handler header routine and toaster module that implements
600+
main functions defined in Toaster routine.
601+
All toasters are registere in <structname>pg_toaster</structname> table.
602+
</para>
603+
604+
<para>
605+
Toaster API header routine defines main Toast functions that must be implemented by
606+
any custome Toaster:
607+
typedef struct TsrRoutine
608+
{
609+
NodeTag type;
610+
611+
/* interface functions */
612+
toast_init init;
613+
toast_function toast;
614+
update_toast_function update_toast;
615+
copy_toast_function copy_toast;
616+
detoast_function detoast;
617+
del_toast_function deltoast;
618+
get_vtable_function get_vtable;
619+
toastervalidate_function toastervalidate;
620+
} TsrRoutine;
621+
622+
Custom toaster functions must implement at least methods
623+
toast
624+
detoast
625+
626+
For data storage custom toasters user structure VARATT_CUSTOM
627+
typedef struct varatt_custom
628+
{
629+
int32 va_placeholder; /* Placeholder for 2 bits to differ old toast pointer from new */
630+
Oid va_toasterid; /* ID of TOAST handler from PG_TOASTER table */
631+
char va_toasterdata[FLEXIBLE_ARRAY_MEMBER]; /* Custom toaster data */
632+
} varatt_custom;
633+
</para>
634+
635+
<para>
636+
Toast functions are added as an extension module, and must be attached to database
637+
accordingly. An example os custom Toaster is provided as DUMMY_TOASTER module:
638+
CREATE EXTENSION dummy_toaster;
639+
640+
Extension header should contain the following information:
641+
CREATE FUNCTION dummy_toaster_handler(internal)
642+
RETURNS toaster_handler
643+
AS 'MODULE_PATHNAME'
644+
LANGUAGE C;
645+
646+
647+
CREATE TOASTER dummy_toaster HANDLER dummy_toaster_handler;
648+
649+
COMMENT ON TOASTER dummy_toaster IS 'dummy_toaster is a dummy toaster';
650+
</para>
651+
652+
</sect2>
653+
593654
</sect1>
594655

595656
<sect1 id="storage-fsm">

0 commit comments

Comments
 (0)