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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy