diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index f4aabf5dc7..0e38382f31 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -587,8 +587,9 @@ The catalog pg_am stores information about relation access methods. There is one row for each access method supported by the system. - Currently, only indexes have access methods. The requirements for index - access methods are discussed in detail in . + Currently, only table and indexes have access methods. The requirements for table + and index access methods are discussed in detail in and + respectively. @@ -634,8 +635,8 @@ char - Currently always i to indicate an index access - method; other values may be allowed in future + t = table (including materialized views), + i = index. diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 4cbcc7a8e5..bc1d0f7bfa 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -7294,6 +7294,23 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + + default_table_access_method (string) + + default_table_access_method configuration parameter + + + + + 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. + + + + default_tablespace (string) diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index a03ea1427b..7e37042a55 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -89,6 +89,7 @@ + diff --git a/doc/src/sgml/indexam.sgml b/doc/src/sgml/indexam.sgml index ff8290da9f..dd54c68802 100644 --- a/doc/src/sgml/indexam.sgml +++ b/doc/src/sgml/indexam.sgml @@ -3,6 +3,14 @@ Index Access Method Interface Definition + + Index Access Method + + + indexam + Index Access Method + + This chapter defines the interface between the core PostgreSQL system and index access @@ -50,8 +58,8 @@ Each index 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 access - method. These entries can be created and deleted using the + specifies a name and a handler function for the index + access method. These entries can be created and deleted using the and SQL commands. diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 96d196d229..3e115f1c76 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -250,6 +250,7 @@ &tablesample-method; &custom-scan; &geqo; + &tableam; &indexam; &generic-wal; &btree; diff --git a/doc/src/sgml/ref/create_access_method.sgml b/doc/src/sgml/ref/create_access_method.sgml index 851c5e63be..dae43dbaed 100644 --- a/doc/src/sgml/ref/create_access_method.sgml +++ b/doc/src/sgml/ref/create_access_method.sgml @@ -61,7 +61,8 @@ CREATE ACCESS METHOD name This clause specifies the type of access method to define. - Only INDEX is supported at present. + Only TABLE and INDEX + are supported at present. @@ -75,10 +76,13 @@ CREATE ACCESS METHOD name that represents the access method. The handler function must be declared to take a single argument of type internal, and its return type depends on the type of access method; - for INDEX access methods, it must - be index_am_handler. The C-level API that the handler - function must implement varies depending on the type of access method. - The index access method API is described in . + for TABLE access methods, it must + be table_am_handler and for INDEX + access methods, it must be index_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 . diff --git a/doc/src/sgml/ref/create_materialized_view.sgml b/doc/src/sgml/ref/create_materialized_view.sgml index 7f31ab4d26..ec8847ed40 100644 --- a/doc/src/sgml/ref/create_materialized_view.sgml +++ b/doc/src/sgml/ref/create_materialized_view.sgml @@ -23,6 +23,7 @@ PostgreSQL documentation CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] table_name [ (column_name [, ...] ) ] + [ USING method ] [ WITH ( storage_parameter [= value] [, ... ] ) ] [ TABLESPACE tablespace_name ] AS query @@ -85,6 +86,21 @@ CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] table_name + + USING method + + + This optional clause specifies the table access method to use to store + the contents for the new materialized view; the method needs be an + access method of type TABLE. See for more information. If this option is not + specified, the default table access method is chosen for the new + materialized view. See + for more information. + + + + WITH ( storage_parameter [= value] [, ... ] ) diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index 99b95bbdb4..85c0ec1b31 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -29,6 +29,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI ] ) [ INHERITS ( parent_table [, ... ] ) ] [ PARTITION BY { RANGE | LIST | HASH } ( { column_name | ( expression ) } [ COLLATE collation ] [ opclass ] [, ... ] ) ] +[ USING method ] [ WITH ( storage_parameter [= value] [, ... ] ) | WITHOUT OIDS ] [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] [ TABLESPACE tablespace_name ] @@ -40,6 +41,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI [, ... ] ) ] [ PARTITION BY { RANGE | LIST | HASH } ( { column_name | ( expression ) } [ COLLATE collation ] [ opclass ] [, ... ] ) ] +[ USING method ] [ WITH ( storage_parameter [= value] [, ... ] ) | WITHOUT OIDS ] [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] [ TABLESPACE tablespace_name ] @@ -51,6 +53,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI [, ... ] ) ] { FOR VALUES partition_bound_spec | DEFAULT } [ PARTITION BY { RANGE | LIST | HASH } ( { column_name | ( expression ) } [ COLLATE collation ] [ opclass ] [, ... ] ) ] +[ USING method ] [ WITH ( storage_parameter [= value] [, ... ] ) | WITHOUT OIDS ] [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] [ TABLESPACE tablespace_name ] @@ -1165,6 +1168,20 @@ WITH ( MODULUS numeric_literal, REM + + USING method + + + This optional clause specifies the table access method to use to store + the contents for the new table; the method needs be an access method of + type TABLE. See for more + information. If this option is not specified, the default table access + method is chosen for the new materialized view. See for more information. + + + + WITH ( storage_parameter [= value] [, ... ] ) @@ -1238,7 +1255,7 @@ WITH ( MODULUS numeric_literal, REM - + TABLESPACE tablespace_name diff --git a/doc/src/sgml/ref/create_table_as.sgml b/doc/src/sgml/ref/create_table_as.sgml index 679e8f521e..1371261e0a 100644 --- a/doc/src/sgml/ref/create_table_as.sgml +++ b/doc/src/sgml/ref/create_table_as.sgml @@ -23,6 +23,7 @@ PostgreSQL documentation CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] table_name [ (column_name [, ...] ) ] + [ USING method ] [ WITH ( storage_parameter [= value] [, ... ] ) | WITHOUT OIDS ] [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] [ TABLESPACE tablespace_name ] @@ -120,6 +121,20 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI + + USING method + + + This optional clause specifies the table access method to use to store + the contents for the new table; the method needs be an access method of + type TABLE. See for more + information. If this option is not specified, the default table access + method is chosen for the new materialized view. See for more information. + + + + WITH ( storage_parameter [= value] [, ... ] ) diff --git a/doc/src/sgml/ref/select_into.sgml b/doc/src/sgml/ref/select_into.sgml index 462e372381..17bed24743 100644 --- a/doc/src/sgml/ref/select_into.sgml +++ b/doc/src/sgml/ref/select_into.sgml @@ -104,6 +104,16 @@ SELECT [ ALL | DISTINCT [ ON ( expressionCREATE TABLE AS offers a superset of the functionality provided by SELECT INTO. + + + In contrast to CREATE TABLE AS SELECT + INTO does not allow to specify properties like a table's access + method with or the table's + tablespace with . Use 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 5df987f9c9..62333e31a0 100644 --- a/doc/src/sgml/storage.sgml +++ b/doc/src/sgml/storage.sgml @@ -188,6 +188,14 @@ for the database's files; in particular, its system catalogs are stored there. + + Note that the following sections describe the way 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. + + Each table and index is stored in a separate file. For ordinary relations, these files are named after the table or index's filenode number, @@ -695,10 +703,11 @@ erased (they will be recreated automatically as needed). This section provides an overview of the page format used within PostgreSQL tables and indexes. - Actually, index access methods need not use this page format. - All the existing index methods do use this basic format, - but the data kept on index metapages usually doesn't follow - the item layout rules. + 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 + data kept on index metapages usually doesn't follow the item layout + rules. The heap table access method also always uses + this format. 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 new file mode 100644 index 0000000000..8d9bfd8130 --- /dev/null +++ b/doc/src/sgml/tableam.sgml @@ -0,0 +1,110 @@ + + + + Table Access Method Interface Definition + + + Table Access Method + + + tableam + Table Access Method + + + + This chapter explains the interface between the core + PostgreSQL system and table access + methods, which manage the storage for tables. 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 table 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 table access method. These + entries can be created and deleted using the and SQL commands. + + + + A table access method handler function must be declared to accept a single + argument of type internal and to return the pseudo-type + table_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 + TableAmRoutine, which contains everything that the + core code needs to know to make use of the table 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 TableAmRoutine 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 + 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, + 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 + + 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) + 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 + 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 + 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 + necessary to closely integrate with the machinery in + src/backend/access/transam/xlog.c. + + + + 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. + + + diff --git a/src/include/access/tableam.h b/src/include/access/tableam.h index 4b760c2cd7..42e2ba68bf 100644 --- a/src/include/access/tableam.h +++ b/src/include/access/tableam.h @@ -9,6 +9,9 @@ * * src/include/access/tableam.h * + * NOTES + * See tableam.sgml for higher level documentation. + * *------------------------------------------------------------------------- */ #ifndef TABLEAM_H