Skip to content

Commit d49ffdc

Browse files
author
Nikita Malakhov
committed
Pluggable TOAST API documentation package
Pluggable TOAST documentation package - changes in SQL syntax (CREATE TABLE, ALTER TABLE, CREATE TOASTER) and short TOAST API explanation. Author: Teodor Sigaev <[email protected]> Author: Oleg Bartunov <[email protected]> Author: Nikita Glukhov <[email protected]> Author: Nikita Malakhov <[email protected]> Discussion: https://www.postgresql.org/message-id/flat/[email protected]
1 parent 4c4c353 commit d49ffdc

File tree

6 files changed

+482
-2
lines changed

6 files changed

+482
-2
lines changed

‎doc/src/sgml/catalogs.sgml

+76
Original file line numberDiff line numberDiff line change
@@ -1266,6 +1266,17 @@
12661266
</para></entry>
12671267
</row>
12681268

1269+
<row>
1270+
<entry role="catalog_table_entry"><para role="column_definition">
1271+
<structfield>atttoaster</structfield> <type>oid</type>
1272+
</para>
1273+
<para>
1274+
OID of the Toaster <literal>pg_toaster.toaster_oid</literal>
1275+
assigned to table's column. If no Custom Toaster assigned to
1276+
the table atttoaster is set to DEFAULT_TOASTER_ID.
1277+
</para></entry>
1278+
</row>
1279+
12691280
<row>
12701281
<entry role="catalog_table_entry"><para role="column_definition">
12711282
<structfield>attcompression</structfield> <type>char</type>
@@ -8186,6 +8197,71 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
81868197
</sect1>
81878198

81888199

8200+
<sect1 id="catalog-pg-toaster">
8201+
<title><structname>pg_toaster</structname></title>
8202+
8203+
<indexterm zone="catalog-pg-toaster">
8204+
<primary>pg_toaster</primary>
8205+
</indexterm>
8206+
8207+
<para>
8208+
The catalog <structname>pg_toaster</structname> stores information
8209+
about all available toaster. Default toaster entry is provided with
8210+
database and thus already exists in database.
8211+
</para>
8212+
8213+
<para>
8214+
Every toaster registered in database is stored in <structname>pg_toaster</structname>.
8215+
This table contains toaster OID, toaster name and related handler procedure.
8216+
</para>
8217+
8218+
<table>
8219+
<title><structname>pg_toaster</structname> Columns</title>
8220+
<tgroup cols="1">
8221+
<thead>
8222+
<row>
8223+
<entry role="catalog_table_entry"><para role="column_definition">
8224+
Column Type
8225+
</para>
8226+
<para>
8227+
Description
8228+
</para></entry>
8229+
</row>
8230+
</thead>
8231+
8232+
<tbody>
8233+
<row>
8234+
<entry role="catalog_table_entry"><para role="column_definition">
8235+
<structfield>oid</structfield> <type>oid</type>
8236+
</para>
8237+
<para>
8238+
Toaster identifier
8239+
</para></entry>
8240+
</row>
8241+
8242+
<row>
8243+
<entry role="catalog_table_entry"><para role="column_definition">
8244+
<structfield>namedata</structfield> <type>toaster_name</type>
8245+
</para>
8246+
<para>
8247+
Toaster name
8248+
</para></entry>
8249+
</row>
8250+
8251+
<row>
8252+
<entry role="catalog_table_entry"><para role="column_definition">
8253+
<structfield>regproc</structfield> <type>Tsr handler</type>
8254+
</para>
8255+
<para>
8256+
Toast API handler procedure
8257+
</para></entry>
8258+
</row>
8259+
</tbody>
8260+
</tgroup>
8261+
</table>
8262+
</sect1>
8263+
8264+
81898265
<sect1 id="catalog-pg-transform">
81908266
<title><structname>pg_transform</structname></title>
81918267

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

+1
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

+13-1
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 | DEFAULT } ] [ 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 | DEFAULT } ] [ 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
[, ... ]
@@ -326,6 +326,18 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
326326
</listitem>
327327
</varlistentry>
328328

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

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

+3-1
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 } ]
@@ -121,6 +121,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
121121
<para>
122122
The name of a column in the new table. If column names are not
123123
provided, they are taken from the output column names of the query.
124+
Toaster could be assigned to toastable column with expression
125+
<literal>STORAGE external TOASTER <replaceable>toaster_name</replaceable></literal>
124126
</para>
125127
</listitem>
126128
</varlistentry>

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

+132
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>

0 commit comments

Comments
 (0)