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 ASSELECT
+ 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