Skip to content

Commit 5a5775b

Browse files
michaelpqCommitfest Bot
michaelpq
authored and
Commitfest Bot
committed
Sequence access methods - core documentation
1 parent 06243f2 commit 5a5775b

File tree

6 files changed

+119
-6
lines changed

6 files changed

+119
-6
lines changed

‎doc/src/sgml/config.sgml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9826,6 +9826,22 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
98269826
</listitem>
98279827
</varlistentry>
98289828

9829+
<varlistentry id="guc-default-sequence-access-method" xreflabel="default_sequence_access_method">
9830+
<term><varname>default_sequence_access_method</varname> (<type>string</type>)
9831+
<indexterm>
9832+
<primary><varname>default_sequence_access_method</varname> configuration parameter</primary>
9833+
</indexterm>
9834+
</term>
9835+
<listitem>
9836+
<para>
9837+
This parameter specifies the default sequence access method to use when
9838+
creating sequences if the <command>CREATE SEQUENCE</command>
9839+
command does not explicitly specify an access method. The default is
9840+
<literal>local</literal>.
9841+
</para>
9842+
</listitem>
9843+
</varlistentry>
9844+
98299845
<varlistentry id="guc-default-tablespace" xreflabel="default_tablespace">
98309846
<term><varname>default_tablespace</varname> (<type>string</type>)
98319847
<indexterm>

‎doc/src/sgml/filelist.sgml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@
9898
<!ENTITY planstats SYSTEM "planstats.sgml">
9999
<!ENTITY tableam SYSTEM "tableam.sgml">
100100
<!ENTITY indexam SYSTEM "indexam.sgml">
101+
<!ENTITY sequenceam SYSTEM "sequenceam.sgml">
101102
<!ENTITY nls SYSTEM "nls.sgml">
102103
<!ENTITY plhandler SYSTEM "plhandler.sgml">
103104
<!ENTITY fdwhandler SYSTEM "fdwhandler.sgml">

‎doc/src/sgml/postgres.sgml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -258,6 +258,7 @@ break is not needed in a wider output rendering.
258258
&geqo;
259259
&tableam;
260260
&indexam;
261+
&sequenceam;
261262
&wal-for-extensions;
262263
&indextypes;
263264
&storage;

‎doc/src/sgml/ref/create_access_method.sgml‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,8 @@ CREATE ACCESS METHOD <replaceable class="parameter">name</replaceable>
6161
<listitem>
6262
<para>
6363
This clause specifies the type of access method to define.
64-
Only <literal>TABLE</literal> and <literal>INDEX</literal>
65-
are supported at present.
64+
Only <literal>TABLE</literal>, <literal>SEQUENCE</literal> and
65+
<literal>INDEX</literal> are supported at present.
6666
</para>
6767
</listitem>
6868
</varlistentry>
@@ -77,12 +77,15 @@ CREATE ACCESS METHOD <replaceable class="parameter">name</replaceable>
7777
declared to take a single argument of type <type>internal</type>,
7878
and its return type depends on the type of access method;
7979
for <literal>TABLE</literal> access methods, it must
80-
be <type>table_am_handler</type> and for <literal>INDEX</literal>
81-
access methods, it must be <type>index_am_handler</type>.
80+
be <type>table_am_handler</type>; for <literal>INDEX</literal>
81+
access methods, it must be <type>index_am_handler</type>;
82+
for <literal>SEQUENCE</literal>, it must be
83+
<type>sequence_am_handler</type>;
8284
The C-level API that the handler function must implement varies
8385
depending on the type of access method. The table access method API
84-
is described in <xref linkend="tableam"/> and the index access method
85-
API is described in <xref linkend="indexam"/>.
86+
is described in <xref linkend="tableam"/>, the index access method
87+
API is described in <xref linkend="indexam"/> and the sequence access
88+
method is described in <xref linkend="sequenceam"/>.
8689
</para>
8790
</listitem>
8891
</varlistentry>

‎doc/src/sgml/ref/create_sequence.sgml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ CREATE [ { TEMPORARY | TEMP } | UNLOGGED ] SEQUENCE [ IF NOT EXISTS ] <replaceab
2929
[ START [ WITH ] <replaceable class="parameter">start</replaceable> ]
3030
[ CACHE <replaceable class="parameter">cache</replaceable> ]
3131
[ OWNED BY { <replaceable class="parameter">table_name</replaceable>.<replaceable class="parameter">column_name</replaceable> | NONE } ]
32+
[ USING <replaceable class="parameter">access_method</replaceable> ]
3233
</synopsis>
3334
</refsynopsisdiv>
3435

@@ -263,6 +264,17 @@ SELECT * FROM <replaceable>name</replaceable>;
263264
</para>
264265
</listitem>
265266
</varlistentry>
267+
268+
<varlistentry>
269+
<term><literal>USING</literal> <replaceable class="parameter">access_method</replaceable></term>
270+
<listitem>
271+
<para>
272+
The <literal>USING</literal> option specifies which sequence access
273+
method will be used when generating the sequence numbers. The default
274+
is <literal>local</literal>.
275+
</para>
276+
</listitem>
277+
</varlistentry>
266278
</variablelist>
267279
</refsect1>
268280

‎doc/src/sgml/sequenceam.sgml‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
<!-- doc/src/sgml/sequenceam.sgml -->
2+
3+
<chapter id="sequenceam">
4+
<title>Sequence Access Method Interface Definition</title>
5+
6+
<indexterm>
7+
<primary>Sequence Access Method</primary>
8+
</indexterm>
9+
<indexterm>
10+
<primary>sequenceam</primary>
11+
<secondary>Sequence Access Method</secondary>
12+
</indexterm>
13+
14+
<para>
15+
This chapter explains the interface between the core
16+
<productname>PostgreSQL</productname> system and <firstterm>sequence access
17+
methods</firstterm>, which manage the operations around sequences . The core
18+
system knows little about these access methods beyond what is specified here,
19+
so it is possible to develop entirely new access method types by writing
20+
add-on code.
21+
</para>
22+
23+
<para>
24+
Each sequence access method is described by a row in the
25+
<link linkend="catalog-pg-am"><structname>pg_am</structname></link> system
26+
catalog. The <structname>pg_am</structname> entry specifies a name and a
27+
<firstterm>handler function</firstterm> for the sequence access method. These
28+
entries can be created and deleted using the
29+
<xref linkend="sql-create-access-method"/> and
30+
<xref linkend="sql-drop-access-method"/> SQL commands.
31+
</para>
32+
33+
<para>
34+
A sequence access method handler function must be declared to accept a single
35+
argument of type <type>internal</type> and to return the pseudo-type
36+
<type>sequence_am_handler</type>. The argument is a dummy value that simply
37+
serves to prevent handler functions from being called directly from SQL commands.
38+
39+
The result of the function must be a pointer to a struct of type
40+
<structname>SequenceAmRoutine</structname>, which contains everything that the
41+
core code needs to know to make use of the sequence access method. The return
42+
value needs to be of server lifetime, which is typically achieved by
43+
defining it as a <literal>static const</literal> variable in global
44+
scope. The <structname>SequenceAmRoutine</structname> struct, also called the
45+
access method's <firstterm>API struct</firstterm>, defines the behavior of
46+
the access method using callbacks. These callbacks are pointers to plain C
47+
functions and are not visible or callable at the SQL level. All the
48+
callbacks and their behavior is defined in the
49+
<structname>SequenceAmRoutine</structname> structure (with comments inside
50+
the struct defining the requirements for callbacks). Most callbacks have
51+
wrapper functions, which are documented from the point of view of a user
52+
(rather than an implementor) of the sequence access method. For details,
53+
please refer to the <ulink url="https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/access/sequenceam.h;hb=HEAD">
54+
<filename>src/include/access/sequenceam.h</filename></ulink> file.
55+
</para>
56+
57+
<para>
58+
Currently, the way a sequence access method stores data is fairly
59+
unconstrained, and it is possible to use a predefined
60+
<link linkend="tableam">Table Access Method</link> to store sequence
61+
data.
62+
</para>
63+
64+
<para>
65+
For crash safety, a sequence access method can use
66+
<link linkend="wal"><acronym>WAL</acronym></link>, or a custom
67+
implementation.
68+
If <acronym>WAL</acronym> is chosen, either
69+
<link linkend="generic-wal">Generic WAL Records</link> can be used, or a
70+
<link linkend="custom-rmgr">Custom WAL Resource Manager</link> can be
71+
implemented.
72+
</para>
73+
74+
<para>
75+
Any developer of a new <literal>sequence access method</literal> can refer to
76+
the existing <literal>local</literal> implementation present in
77+
<filename>src/backend/access/sequence/local.c</filename> for details of
78+
its implementation.
79+
</para>
80+
</chapter>

0 commit comments

Comments
 (0)