Hi,
On 2019-04-02 17:11:07 +1100, Haribabu Kommi wrote:
> From a72cfcd523887f1220473231d7982928acc23684 Mon Sep 17 00:00:00 2001
> From: Hari Babu <kommi.harib...@gmail.com>
> Date: Tue, 2 Apr 2019 15:41:17 +1100
> Subject: [PATCH 1/2] tableam : doc update of table access methods
>
> Providing basic explanation of table access methods
> including their structure details and reference heap
> implementation files.
> ---
> doc/src/sgml/catalogs.sgml | 5 ++--
> doc/src/sgml/filelist.sgml | 1 +
> doc/src/sgml/postgres.sgml | 1 +
> doc/src/sgml/tableam.sgml | 56 ++++++++++++++++++++++++++++++++++++++
> 4 files changed, 61 insertions(+), 2 deletions(-)
> create mode 100644 doc/src/sgml/tableam.sgml
>
> diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
> index f4aabf5dc7..200708e121 100644
> --- a/doc/src/sgml/catalogs.sgml
> +++ b/doc/src/sgml/catalogs.sgml
> @@ -587,8 +587,9 @@
> The catalog <structname>pg_am</structname> 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 <xref linkend="indexam"/>.
> + Currently, only table and indexes have access methods. The requirements
> for table
> + access methods are discussed in detail in <xref linkend="tableam"/> and
> the
> + requirements for index access methods are discussed in detail in <xref
> linkend="indexam"/>.
> </para>
I also adapted pg_am.amtype.
> diff --git a/doc/src/sgml/tableam.sgml b/doc/src/sgml/tableam.sgml
> new file mode 100644
> index 0000000000..9eca52ee70
> --- /dev/null
> +++ b/doc/src/sgml/tableam.sgml
> @@ -0,0 +1,56 @@
> +<!-- doc/src/sgml/tableam.sgml -->
> +
> +<chapter id="tableam">
> + <title>Table Access Method Interface Definition</title>
> +
> + <para>
> + This chapter defines the interface between the core
> <productname>PostgreSQL</productname>
> + system and <firstterm>access methods</firstterm>, which manage
> <literal>TABLE</literal>
> + types. The core system knows nothing 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.
> + </para>
> +
> + <para>
> + All Tables in <productname>PostgreSQL</productname> system are the primary
> + data store. Each table is stored as its own physical
> <firstterm>relation</firstterm>
> + and so is described by an entry in the <structname>pg_class</structname>
> + catalog. A table's content is entirely controlled by its access method.
> + (All the access methods furthermore use the standard page layout described
> + in <xref linkend="storage-page-layout"/>.)
> + </para>
I don't think there's actually any sort of dependency on the page
layout. It's entirely conceivable to write an AM that doesn't use
postgres' shared buffers.
> + <para>
> + A table access method handler function must be declared to accept a single
> + argument of type <type>internal</type> and to return the pseudo-type
> + <type>table_am_handler</type>. 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 palloc'd struct of type
> <structname>TableAmRoutine</structname>,
> + which contains everything that the core code needs to know to make use of
> + the table access method.
That's not been correct for a while...
> The <structname>TableAmRoutine</structname> struct,
> + also called the access method's <firstterm>API struct</firstterm>,
> includes
> + fields specifying assorted fixed properties of the access method, such as
> + whether it can support bitmap scans. More importantly, it contains
> pointers
> + to support functions for the access method, which do all of the real work
> to
> + access tables. These support functions are plain C functions and are not
> + visible or callable at the SQL level. The support functions are described
> + in <structname>TableAmRoutine</structname> structure. For more details,
> please
> + refer the file <filename>src/include/access/tableam.h</filename>.
> + </para>
This seems to not have been adapted after copying it from indexam?
I'm still working on this (in particular I think storage.sgml and
probably some other places needs updates to make clear they apply to
heap not generally; I think there needs to be some references to generic
WAL records in tableam.sgml, ...), but I got to run a few errands.
One thing I want to call out is that I made the reference to
src/include/access/tableam.h a link to gitweb. I think that makes it
much more useful to the casual reader. But it also means that, baring
some infrastructure / procedure we don't have, the link will just
continue to point to master. I'm not particularly concerned about that,
but it seems worth pointing out, given that we've only a single link to
gitweb in the sgml docs so far.
Greetings,
Andres Freund
>From 33826b211e3f2d5fe76024e2938ff2eb6aeb00da Mon Sep 17 00:00:00 2001
From: Andres Freund <and...@anarazel.de>
Date: Tue, 2 Apr 2019 14:55:30 -0700
Subject: [PATCH] tableam: docs
---
doc/src/sgml/catalogs.sgml | 9 +-
doc/src/sgml/config.sgml | 17 ++++
doc/src/sgml/filelist.sgml | 1 +
doc/src/sgml/postgres.sgml | 1 +
doc/src/sgml/ref/create_access_method.sgml | 14 ++--
.../sgml/ref/create_materialized_view.sgml | 15 ++++
doc/src/sgml/ref/create_table.sgml | 19 ++++-
doc/src/sgml/ref/create_table_as.sgml | 15 ++++
doc/src/sgml/ref/select_into.sgml | 8 ++
doc/src/sgml/tableam.sgml | 83 +++++++++++++++++++
src/include/access/tableam.h | 3 +
11 files changed, 175 insertions(+), 10 deletions(-)
create mode 100644 doc/src/sgml/tableam.sgml
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index f4aabf5dc7f..0e38382f319 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -587,8 +587,9 @@
The catalog <structname>pg_am</structname> 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 <xref linkend="indexam"/>.
+ Currently, only table and indexes have access methods. The requirements for table
+ and index access methods are discussed in detail in <xref linkend="tableam"/> and
+ <xref linkend="indexam"/> respectively.
</para>
<table>
@@ -634,8 +635,8 @@
<entry><type>char</type></entry>
<entry></entry>
<entry>
- Currently always <literal>i</literal> to indicate an index access
- method; other values may be allowed in future
+ <literal>t</literal> = table (including materialized views),
+ <literal>i</literal> = index.
</entry>
</row>
</tbody>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 2166b99fc4e..84c507512f1 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -7266,6 +7266,23 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
</listitem>
</varlistentry>
+ <varlistentry id="guc-default-table-access-method" xreflabel="default_table_access_method">
+ <term><varname>default_table_access_method</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>default_table_access_method</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ This parameter specifies the default table access method to use when
+ creating tables or materialized views if the <command>CREATE</command>
+ command does not explicitly specify an access method, or when
+ <command>SELECT ... INTO</command> is used, which does not allow to
+ specify a table access method.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry id="guc-default-tablespace" xreflabel="default_tablespace">
<term><varname>default_tablespace</varname> (<type>string</type>)
<indexterm>
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index a03ea1427b9..7e37042a55e 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -89,6 +89,7 @@
<!ENTITY gin SYSTEM "gin.sgml">
<!ENTITY brin SYSTEM "brin.sgml">
<!ENTITY planstats SYSTEM "planstats.sgml">
+<!ENTITY tableam SYSTEM "tableam.sgml">
<!ENTITY indexam SYSTEM "indexam.sgml">
<!ENTITY nls SYSTEM "nls.sgml">
<!ENTITY plhandler SYSTEM "plhandler.sgml">
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 96d196d2293..3e115f1c76c 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 851c5e63beb..dae43dbaed5 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 <replaceable class="parameter">name</replaceable>
<listitem>
<para>
This clause specifies the type of access method to define.
- Only <literal>INDEX</literal> is supported at present.
+ Only <literal>TABLE</literal> and <literal>INDEX</literal>
+ are supported at present.
</para>
</listitem>
</varlistentry>
@@ -75,10 +76,13 @@ CREATE ACCESS METHOD <replaceable class="parameter">name</replaceable>
that represents the access method. The handler function must be
declared to take a single argument of type <type>internal</type>,
and its return type depends on the type of access method;
- for <literal>INDEX</literal> access methods, it must
- be <type>index_am_handler</type>. 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 <xref linkend="indexam"/>.
+ for <literal>TABLE</literal> access methods, it must
+ be <type>table_am_handler</type> and for <literal>INDEX</literal>
+ access methods, it must be <type>index_am_handler</type>.
+ 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 <xref linkend="tableam"/> and the index access method
+ API is described in <xref linkend="indexam"/>.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/create_materialized_view.sgml b/doc/src/sgml/ref/create_materialized_view.sgml
index 7f31ab4d26d..2824248130c 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
<synopsis>
CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] <replaceable>table_name</replaceable>
[ (<replaceable>column_name</replaceable> [, ...] ) ]
+ [ USING <replaceable class="parameter">method</replaceable> ]
[ WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ]
[ TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
AS <replaceable>query</replaceable>
@@ -85,6 +86,20 @@ CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] <replaceable>table_name</replaceable>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><literal>USING <replaceable class="parameter">method</replaceable></literal></term>
+ <listitem>
+ <para>
+ This clause specifies optional method for the new materialized view; The
+ method should be an access method of type <literal>TABLE</literal>. See
+ <xref linkend="tableam"/> for more information. If this option is not
+ specified, the default table access method is chosen for the new
+ materialized view. See <xref linkend="guc-default-table-access-method"/>
+ for more information.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><literal>WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
<listitem>
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index 0fcbc660b31..e3e377a46fc 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 ( <replaceable>parent_table</replaceable> [, ... ] ) ]
[ PARTITION BY { RANGE | LIST | HASH } ( { <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ COLLATE <replaceable class="parameter">collation</replaceable> ] [ <replaceable class="parameter">opclass</replaceable> ] [, ... ] ) ]
+[ USING <replaceable class="parameter">method</replaceable> ]
[ WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) | WITHOUT OIDS ]
[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
[ TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
@@ -40,6 +41,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
[, ... ]
) ]
[ PARTITION BY { RANGE | LIST | HASH } ( { <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ COLLATE <replaceable class="parameter">collation</replaceable> ] [ <replaceable class="parameter">opclass</replaceable> ] [, ... ] ) ]
+[ USING <replaceable class="parameter">method</replaceable> ]
[ WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) | WITHOUT OIDS ]
[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
[ TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
@@ -51,6 +53,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
[, ... ]
) ] { FOR VALUES <replaceable class="parameter">partition_bound_spec</replaceable> | DEFAULT }
[ PARTITION BY { RANGE | LIST | HASH } ( { <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ COLLATE <replaceable class="parameter">collation</replaceable> ] [ <replaceable class="parameter">opclass</replaceable> ] [, ... ] ) ]
+[ USING <replaceable class="parameter">method</replaceable> ]
[ WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) | WITHOUT OIDS ]
[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
[ TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
@@ -1170,6 +1173,20 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
</listitem>
</varlistentry>
+ <varlistentry id="sql-createtable-method">
+ <term><literal>USING <replaceable class="parameter">method</replaceable></literal></term>
+ <listitem>
+ <para>
+ This clause specifies optional method for the new table; The method
+ should be an access method of type <literal>TABLE</literal>. See <xref
+ linkend="tableam"/> for more information. If this option is not
+ specified, the default table access method is chosen for the new
+ table. See <xref linkend="guc-default-table-access-method"/> for more
+ information.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><literal>WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
<listitem>
@@ -1243,7 +1260,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createtable-tablespace">
<term><literal>TABLESPACE <replaceable class="parameter">tablespace_name</replaceable></literal></term>
<listitem>
<para>
diff --git a/doc/src/sgml/ref/create_table_as.sgml b/doc/src/sgml/ref/create_table_as.sgml
index 679e8f521ed..385fcf4ad1e 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
<synopsis>
CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] <replaceable>table_name</replaceable>
[ (<replaceable>column_name</replaceable> [, ...] ) ]
+ [ USING <replaceable class="parameter">method</replaceable> ]
[ WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) | WITHOUT OIDS ]
[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
[ TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
@@ -120,6 +121,20 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><literal>USING <replaceable class="parameter">method</replaceable></literal></term>
+ <listitem>
+ <para>
+ This clause specifies optional method for the new table; The method
+ should be an access method of type <literal>TABLE</literal>. See <xref
+ linkend="tableam"/> for more information. If this option is not
+ specified, then the default table access method is chosen for the new
+ table. see <xref linkend="guc-default-table-access-method"/> for more
+ information.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><literal>WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
<listitem>
diff --git a/doc/src/sgml/ref/select_into.sgml b/doc/src/sgml/ref/select_into.sgml
index 462e3723819..73dd93e9a39 100644
--- a/doc/src/sgml/ref/select_into.sgml
+++ b/doc/src/sgml/ref/select_into.sgml
@@ -104,6 +104,14 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="parameter">expression</replac
<command>CREATE TABLE AS</command> offers a superset of the
functionality provided by <command>SELECT INTO</command>.
</para>
+
+ <para>
+ In contrast to <command>CREATE TABLE AS</command> <command>SELECT
+ INTO</command> does not allow to specify properties like a table's access
+ method with <xref linkend="sql-createtable-method" /> or the table's
+ tablespace with <xref linkend="sql-createtable-tablespace" />. Use <xref
+ linkend="sql-createtableas"/> if necessary.
+ </para>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/tableam.sgml b/doc/src/sgml/tableam.sgml
new file mode 100644
index 00000000000..fb11df6c744
--- /dev/null
+++ b/doc/src/sgml/tableam.sgml
@@ -0,0 +1,83 @@
+<!-- doc/src/sgml/tableam.sgml -->
+
+<chapter id="tableam">
+ <title>Table Access Method Interface Definition</title>
+
+ <para>
+ This chapter defines the interface between the core
+ <productname>PostgreSQL</productname> system and <firstterm>table access
+ methods</firstterm>, 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.
+ </para>
+
+ <para>
+ Each table access method is described by a row in the <link
+ linkend="catalog-pg-am"><structname>pg_am</structname></link> system
+ catalog. The <structname>pg_am</structname> entry specifies a
+ <firstterm>type</firstterm> of the access method and a <firstterm>handler
+ function</firstterm> for the access method. These entries can be created
+ and deleted using the <xref linkend="sql-create-access-method"/> and <xref
+ linkend="sql-drop-access-method"/> SQL commands.
+ </para>
+
+ <para>
+ A table access method handler function must be declared to accept a single
+ argument of type <type>internal</type> and to return the pseudo-type
+ <type>table_am_handler</type>. 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
+ <structname>TableAmRoutine</structname>, 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 <literal>static const</literal> variable in global
+ scope. The <structname>TableAmRoutine</structname> struct, also called the
+ access method's <firstterm>API struct</firstterm>, 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
+ <structname>TableAmRoutine</structname> 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 <ulink url="https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/access/tableam.h;hb=HEAD";>
+ <filename>src/include/access/tableam.h</filename></ulink> file.
+ </para>
+
+ <para>
+ To implement a access method, an implementor will typically need to
+ implement a AM specific type of tuple table slot (see
+ <ulink url="https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/executor/tuptable.h;hb=HEAD";>
+ <filename>src/include/executor/tuptable.h</filename></ulink>) which allows
+ code outside the access method to hold references to tuples of the AM, and
+ to access the columns of the tuple.
+ </para>
+
+ <para>
+ Currently the design of the actual storage an AM implements is fairly
+ unconstrained. It is possible to use postgres' shared buffer cache, but not
+ required. One fairly large constraint is that currently, if the AM wants to
+ support modifications and/or indexes, it is necessary that each tuple has a
+ tuple identifier (<acronym>TID</acronym>) consisting of a block number and
+ an item number within that block (see also <xref
+ linkend="storage-page-layout"/>). It is not strictly necessary that the
+ sub-parts of <acronym>TIDs</acronym> have the same meaning they e.g. have
+ for <literal>heap</literal>, but if bitmap scan support is desired (it is
+ optional), the block number needs to provide locality.
+ </para>
+
+ <para>
+ For crash safety an AM can use postgres' <xref linkend="wal"/>, or a custom
+ approach can be implemented.
+ </para>
+
+ <para>
+ Any developer of a new <literal>table access method</literal> can refer to
+ the existing <literal>heap</literal> implementation present in
+ <filename>src/backend/heap/heapam_handler.c</filename> for more details of
+ how it is implemented.
+ </para>
+
+</chapter>
diff --git a/src/include/access/tableam.h b/src/include/access/tableam.h
index 4b760c2cd75..42e2ba68bf9 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
--
2.21.0.dirty
