From 7de0149b2b69a133ef8762cce67a16ed2defd087 Mon Sep 17 00:00:00 2001 From: Michael Paquier Date: Fri, 1 Dec 2023 12:55:56 +0900 Subject: [PATCH v8 6/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 | 80 ++++++++++++++++++++++ 6 files changed, 119 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 12feac6087..651caa7491 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -8993,6 +8993,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 a7ff5f8264..07aa3f18c7 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -95,6 +95,7 @@ + diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index ec9f90e283..6b82f4c7fc 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -256,6 +256,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 dae43dbaed..3067dc4d4d 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, SEQUENCE and + INDEX 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 1e283f13d1..52c6096e4b 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 0000000000..a96170bfac --- /dev/null +++ b/doc/src/sgml/sequenceam.sgml @@ -0,0 +1,80 @@ + + + + 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 entirely new access method types 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 local implementation present in + src/backend/access/sequence/local.c for details of + its implementation. + + -- 2.45.2