From: Justin Pryzby Date: Thu, 4 Apr 2019 00:48:09 -0500 Subject: [PATCH v1] Fine tune documentation for tableam Added at commit b73c3a11963c8bb783993cfffabb09f558f86e37 --- doc/src/sgml/catalogs.sgml | 2 +- doc/src/sgml/config.sgml | 4 ++-- doc/src/sgml/ref/select_into.sgml | 6 +++--- doc/src/sgml/storage.sgml | 17 ++++++++------- doc/src/sgml/tableam.sgml | 44 ++++++++++++++++++++------------------- 5 files changed, 38 insertions(+), 35 deletions(-) diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 58c8c96..40ddec4 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -587,7 +587,7 @@ The catalog pg_am stores information about relation access methods. There is one row for each access method supported by the system. - Currently, only table and indexes have access methods. The requirements for table + Currently, only tables and indexes have access methods. The requirements for table and index access methods are discussed in detail in and respectively. diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 4a9a1e8..90b478d 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -7306,8 +7306,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; This parameter specifies the default table access method to use when creating tables or materialized views if the CREATE command does not explicitly specify an access method, or when - SELECT ... INTO is used, which does not allow to - specify a table access method. The default is heap. + SELECT ... INTO is used, which does not allow + specification of a table access method. The default is heap. diff --git a/doc/src/sgml/ref/select_into.sgml b/doc/src/sgml/ref/select_into.sgml index 17bed24..1443d79 100644 --- a/doc/src/sgml/ref/select_into.sgml +++ b/doc/src/sgml/ref/select_into.sgml @@ -106,11 +106,11 @@ SELECT [ ALL | DISTINCT [ ON ( expression - In contrast to CREATE TABLE AS SELECT - INTO does not allow to specify properties like a table's access + In contrast to CREATE TABLE AS, SELECT + INTO does not allow specification of properties like a table's access method with or the table's tablespace with . Use if necessary. Therefore the default table + linkend="sql-createtableas"/> if necessary. Therefore, the default table access method is chosen for the new table. See for more information. diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml index 62333e3..5dfca1b 100644 --- a/doc/src/sgml/storage.sgml +++ b/doc/src/sgml/storage.sgml @@ -189,11 +189,11 @@ there. - Note that the following sections describe the way the builtin + Note that the following sections describe the behavior of the builtin heap table access method, - and the builtin index access methods work. Due - to the extensible nature of PostgreSQL other types - of access method might work similar or not. + and the builtin index access methods. Due + to the extensible nature of PostgreSQL, other + access methods might work differently. @@ -703,11 +703,12 @@ erased (they will be recreated automatically as needed). This section provides an overview of the page format used within PostgreSQL tables and indexes. - Actually, neither table nor index access methods need not use this page - format. All the existing index methods do use this basic format, but the + Actually, use of this page format is not required for either table or index + access methods. + The heap table access method always uses this format. + All the existing index methods also use the basic format, but the data kept on index metapages usually doesn't follow the item layout - rules. The heap table access method also always uses - this format. + rules. Sequences and TOAST tables are formatted just like a regular table. diff --git a/doc/src/sgml/tableam.sgml b/doc/src/sgml/tableam.sgml index 8d9bfd8..0a89935 100644 --- a/doc/src/sgml/tableam.sgml +++ b/doc/src/sgml/tableam.sgml @@ -48,54 +48,56 @@ callbacks and their behavior is defined in the TableAmRoutine structure (with comments inside the struct defining the requirements for callbacks). Most callbacks have - wrapper functions, which are documented for the point of view of a user, - rather than an implementor, of the table access method. For details, + wrapper functions, which are documented from the point of view of a user + (rather than an implementor) of the table access method. For details, please refer to the src/include/access/tableam.h file. - To implement a access method, an implementor will typically need to - implement a AM specific type of tuple table slot (see + To implement an access method, an implementor will typically need to + implement an AM-specific type of tuple table slot (see - src/include/executor/tuptable.h) which allows + src/include/executor/tuptable.h), which allows code outside the access method to hold references to tuples of the AM, and to access the columns of the tuple. - Currently the the way an AM actually stores data is fairly - unconstrained. It is e.g. possible to use postgres' shared buffer cache, - but not required. In case shared buffers are used, it likely makes to - postgres' standard page layout described in . One fairly large constraint of the table access method API is that, currently, if the AM wants to support modifications and/or indexes, it is - necessary that each tuple has a tuple identifier (TID) + necessary for each tuple to have a tuple identifier (TID) consisting of a block number and an item number (see also ). It is not strictly necessary that the - sub-parts of TIDs have the same meaning they e.g. have + sub-parts of TIDs have the same meaning as used for heap, but if bitmap scan support is desired (it is optional), the block number needs to provide locality. - For crash safety an AM can use postgres' WAL, or a custom approach can be - implemented. If WAL is chosen, either Generic WAL Records can be used — which - implies higher WAL volume but is easy, or a new type of - WAL records can be implemented — but that - currently requires modifications of core code (namely modifying + For crash safety, an AM can use postgres' WAL, or a custom implementation. + If WAL is chosen, either Generic WAL Records can be used, + or a new type of WAL records can be implemented. + Generic WAL Records are easy, but imply higher WAL volume. + Implementation of a new type of WAL record + currently requires modifications to core code (specifically, src/include/access/rmgrlist.h). To implement transactional support in a manner that allows different table - access methods be accessed within a single transaction, it likely is + access methods be accessed within a single transaction, it's likely necessary to closely integrate with the machinery in src/backend/access/transam/xlog.c. @@ -103,8 +105,8 @@ Any developer of a new table access method can refer to the existing heap implementation present in - src/backend/heap/heapam_handler.c for more details of - how it is implemented. + src/backend/heap/heapam_handler.c for details of + its implementation. -- 2.1.4 --ibTvN161/egqYuK8--