From 545ba728433d34f0213a734a59a0858c107b024c Mon Sep 17 00:00:00 2001 From: Michael Paquier Date: Fri, 26 Dec 2025 12:05:36 +0900 Subject: [PATCH v29 5/7] Sequence access methods - core documentation --- doc/src/sgml/config.sgml | 16 +++++ doc/src/sgml/filelist.sgml | 1 + doc/src/sgml/postgres.sgml | 1 + doc/src/sgml/ref/create_access_method.sgml | 15 ++-- doc/src/sgml/ref/create_sequence.sgml | 12 ++++ doc/src/sgml/sequenceam.sgml | 79 ++++++++++++++++++++++ 6 files changed, 118 insertions(+), 6 deletions(-) create mode 100644 doc/src/sgml/sequenceam.sgml diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 73cc0412330..24952bb0e0b 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -10307,6 +10307,22 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + + default_sequence_access_method (string) + + default_sequence_access_method configuration parameter + + + + + This parameter specifies the default sequence access method to use when + creating sequences if the CREATE SEQUENCE + command does not explicitly specify an access method. The default is + local. + + + + default_tablespace (string) diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 25a85082759..3276b0a9122 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -98,6 +98,7 @@ + diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 2101442c90f..9ceed4064a4 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -258,6 +258,7 @@ break is not needed in a wider output rendering. &geqo; &tableam; &indexam; + &sequenceam; &wal-for-extensions; &indextypes; &storage; diff --git a/doc/src/sgml/ref/create_access_method.sgml b/doc/src/sgml/ref/create_access_method.sgml index dae43dbaed5..905f2be9933 100644 --- a/doc/src/sgml/ref/create_access_method.sgml +++ b/doc/src/sgml/ref/create_access_method.sgml @@ -61,8 +61,8 @@ CREATE ACCESS METHOD name This clause specifies the type of access method to define. - Only TABLE and INDEX - are supported at present. + Only TABLE, INDEX and + SEQUENCE are supported at present. @@ -77,12 +77,15 @@ CREATE ACCESS METHOD name declared to take a single argument of type internal, and its return type depends on the type of access method; for TABLE access methods, it must - be table_am_handler and for INDEX - access methods, it must be index_am_handler. + be table_am_handler; for INDEX + access methods, it must be index_am_handler; + for SEQUENCE, it must be + sequence_am_handler; The C-level API that the handler function must implement varies depending on the type of access method. The table access method API - is described in and the index access method - API is described in . + is described in , the index access method + API is described in and the sequence access + method is described in . diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml index 0ffcd0febd1..e89ffbbcf90 100644 --- a/doc/src/sgml/ref/create_sequence.sgml +++ b/doc/src/sgml/ref/create_sequence.sgml @@ -29,6 +29,7 @@ CREATE [ { TEMPORARY | TEMP } | UNLOGGED ] SEQUENCE [ IF NOT EXISTS ] start ] [ CACHE cache ] [ OWNED BY { table_name.column_name | NONE } ] + [ USING access_method ] @@ -263,6 +264,17 @@ SELECT * FROM name; + + + USING access_method + + + The USING option specifies which sequence access + method will be used when generating the sequence numbers. The default + is local. + + + diff --git a/doc/src/sgml/sequenceam.sgml b/doc/src/sgml/sequenceam.sgml new file mode 100644 index 00000000000..22ee3a4bfa0 --- /dev/null +++ b/doc/src/sgml/sequenceam.sgml @@ -0,0 +1,79 @@ + + + + Sequence Access Method Interface Definition + + + Sequence Access Method + + + sequenceam + Sequence Access Method + + + + This chapter explains the interface between the core + PostgreSQL system and sequence access + methods, which manage the operations around sequences. The core + system knows little about these access methods beyond what is specified here, + so it is possible to develop new access methods by writing add-on code. + + + + Each sequence access method is described by a row in the + pg_am system + catalog. The pg_am entry specifies a name and a + handler function for the sequence access method. These + entries can be created and deleted using the + and + SQL commands. + + + + A sequence access method handler function must be declared to accept a single + argument of type internal and to return the pseudo-type + sequence_am_handler. The argument is a dummy value that simply + serves to prevent handler functions from being called directly from SQL commands. + + The result of the function must be a pointer to a struct of type + SequenceAmRoutine, which contains everything that the + core code needs to know to make use of the sequence access method. The return + value needs to be of server lifetime, which is typically achieved by + defining it as a static const variable in global + scope. The SequenceAmRoutine struct, also called the + access method's API struct, 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 + callbacks and their behavior is defined in the + SequenceAmRoutine structure (with comments inside + the struct defining the requirements for callbacks). Most callbacks have + wrapper functions, which are documented from the point of view of a user + (rather than an implementor) of the sequence access method. For details, + please refer to the + src/include/access/sequenceam.h file. + + + + Currently, the way a sequence access method stores data is fairly + unconstrained, and it is possible to use a predefined + Table Access Method to store sequence + data. + + + + For crash safety, a sequence access method can use + WAL, or a custom + implementation. + If WAL is chosen, either + Generic WAL Records can be used, or a + Custom WAL Resource Manager can be + implemented. + + + + Any developer of a new sequence access method can refer to + the existing seqlocal implementation present in + src/backend/access/sequence/seqlocalam.c for details of + its implementation. + + -- 2.54.0