Allow table AMs to define their own reloptions

With the help of the new routine 'relation_options', table access
methods can now define their own reloptions.

These options can be set via the following commands:
1. CREATE TABLE ... USING table_am
       WITH (option1='value1', option2='value2');
2. ALTER TABLE ...
       SET (option1 'value1', option2 'value2');
3. ALTER TABLE ... SET ACCESS METHOD table_am
       OPTIONS (option1 'value1', option2 'value2');

When changing table's access method, the settings from the former
table AM can be dropped (if not supported by the new table AM) via:
DROP option, or, updated via: SET option 'value'.

Before this commit, tables using different table AMs than heap were
able to use heap's reloptions (fillfactor, toast_tuple_target,
etc...). Now, this is not the case anymore: if the table AM needs
to have access to settings similar to heap ones, they must
explicitly define them.

This work is directly derived from SadhuPrasad's patch named:
v4-0001-PATCH-V4-Per-table-storage-parameters-for-TableAM.patch

Author: Julien Tachoires

doc/src/sgml/ref/alter_table.sgml

@@ -77,7 +77,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable>
     CLUSTER ON <replaceable class="parameter">index_name</replaceable>
     SET WITHOUT CLUSTER
     SET WITHOUT OIDS
-    SET ACCESS METHOD { <replaceable class="parameter">new_access_method</replaceable> | DEFAULT }
+    SET ACCESS METHOD { <replaceable class="parameter">new_access_method</replaceable> | DEFAULT } [ OPTIONS ( [ ADD | SET | DROP ] <replaceable class="parameter">option</replaceable> ['<replaceable class="parameter">value</replaceable>'] [, ... ] ) ]
     SET TABLESPACE <replaceable class="parameter">new_tablespace</replaceable>
     SET { LOGGED | UNLOGGED }
     SET ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )
@@ -758,7 +758,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
    </varlistentry>
 
    <varlistentry id="sql-altertable-desc-set-access-method">
-    <term><literal>SET ACCESS METHOD</literal></term>
+    <term><literal>SET ACCESS METHOD { <replaceable class="parameter">new_access_method</replaceable> | DEFAULT } [ OPTIONS ( [ ADD | SET | DROP ] <replaceable class="parameter">option</replaceable> ['<replaceable class="parameter">value</replaceable>'] [, ... ] ) ]</literal></term>
     <listitem>
      <para>
       This form changes the access method of the table by rewriting it
@@ -776,6 +776,15 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       causing future partitions to default to
       <varname>default_table_access_method</varname>.
      </para>
+     <para>
+      Specifying <literal>OPTIONS</literal> allows to change options for
+      the table when changing the table access method.
+      <literal>ADD</literal>, <literal>SET</literal>, and
+      <literal>DROP</literal> specify the action to be performed.
+      <literal>ADD</literal> is assumed if no operation is explicitly
+      specified.  Option names must be unique; names and values are also
+      validated using the table access method's library.
+     </para>
     </listitem>
    </varlistentry>
 

doc/src/sgml/ref/create_table.sgml

@@ -1552,7 +1552,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
     Storage parameters for
     indexes are documented in <xref linkend="sql-createindex"/>.
     The storage parameters currently
-    available for tables are listed below.  For many of these parameters, as
+    available for tables are listed below. Each table may have different set of storage
+    parameters through different access methods. For many of these parameters, as
     shown, there is an additional parameter with the same name prefixed with
     <literal>toast.</literal>, which controls the behavior of the
     table's secondary <acronym>TOAST</acronym> table, if any

src/backend/access/common/reloptions.c

@@ -25,6 +25,7 @@
 #include "access/reloptions.h"
 #include "access/spgist_private.h"
 #include "catalog/pg_type.h"
+#include "catalog/pg_am.h"
 #include "commands/defrem.h"
 #include "commands/tablespace.h"
 #include "nodes/makefuncs.h"
@@ -34,6 +35,7 @@
 #include "utils/guc.h"
 #include "utils/memutils.h"
 #include "utils/rel.h"
+#include "utils/syscache.h"
 
 /*
  * Contents of pg_class.reloptions
@@ -1388,7 +1390,7 @@ untransformRelOptions(Datum options)
  */
 bytea *
 extractRelOptions(HeapTuple tuple, TupleDesc tupdesc,
-				  amoptions_function amoptions)
+				  amoptions_function amoptions, reloptions_function reloptsfun)
 {
 	bytea	   *options;
 	bool		isnull;
@@ -1410,7 +1412,8 @@ extractRelOptions(HeapTuple tuple, TupleDesc tupdesc,
 		case RELKIND_RELATION:
 		case RELKIND_TOASTVALUE:
 		case RELKIND_MATVIEW:
-			options = heap_reloptions(classForm->relkind, datum, false);
+			options = table_reloptions(reloptsfun, InvalidOid, classForm->relkind,
+									   datum, false);
 			break;
 		case RELKIND_PARTITIONED_TABLE:
 			options = partitioned_table_reloptions(datum, false);
@@ -2040,7 +2043,8 @@ view_reloptions(Datum reloptions, bool validate)
 }
 
 /*
- * Parse options for heaps, views and toast tables.
+ * Parse options for heaps, views and toast tables. This is the implementation
+ * of relOptions for the access method heap.
  */
 bytea *
 heap_reloptions(char relkind, Datum reloptions, bool validate)
@@ -2070,6 +2074,62 @@ heap_reloptions(char relkind, Datum reloptions, bool validate)
 }
 
 
+/*
+ * Parse options for tables.
+ *
+ *	reloptsfun	Table AM's option parser function. Can be NULL if amid is
+ *				valid. In this case we load the new table AM and use its option
+ *				parser function.
+ *	amid		New table AM's Oid if any.
+ *	relkind		relation kind
+ *	reloptions	options as text[] datum
+ *	validate	error flag
+ */
+bytea *
+table_reloptions(reloptions_function reloptsfun, Oid amid, char relkind,
+				 Datum reloptions, bool validate)
+{
+	/* amid and reloptsfun are mutually exclusive */
+	Assert((!OidIsValid(amid) && (reloptsfun != NULL)) || \
+		   (OidIsValid(amid) && (reloptsfun == NULL)));
+
+	/* Parse/validate options using reloptsfun */
+	if (!OidIsValid(amid) && reloptsfun != NULL)
+	{
+		/* Assume function is strict */
+		if (!PointerIsValid(DatumGetPointer(reloptions)))
+			return NULL;
+
+		return reloptsfun(relkind, reloptions, validate);
+	}
+	/* Parse/validate options using the API of the new Table AM */
+	else if (OidIsValid(amid) && (reloptsfun == NULL))
+	{
+		const TableAmRoutine *routine;
+		HeapTuple	atuple;
+		Form_pg_am	aform;
+
+		atuple = SearchSysCache1(AMOID, ObjectIdGetDatum(amid));
+
+		if (!HeapTupleIsValid(atuple))
+			elog(ERROR, "cache lookup failed for access method %u", amid);
+
+		aform = (Form_pg_am) GETSTRUCT(atuple);
+		routine = GetTableAmRoutine(aform->amhandler);
+		ReleaseSysCache(atuple);
+
+		if (routine->relation_options != NULL)
+			return routine->relation_options(relkind, reloptions, validate);
+
+		return NULL;
+	}
+	else
+	{
+		/* Should not happen */
+		return NULL;
+	}
+}
+
 /*
  * Parse options for indexes.
  *

src/backend/access/heap/heapam_handler.c

@@ -24,6 +24,7 @@
 #include "access/heaptoast.h"
 #include "access/multixact.h"
 #include "access/rewriteheap.h"
+#include "access/reloptions.h"
 #include "access/syncscan.h"
 #include "access/tableam.h"
 #include "access/tsmapi.h"
@@ -2659,6 +2660,7 @@ static const TableAmRoutine heapam_methods = {
 	.index_build_range_scan = heapam_index_build_range_scan,
 	.index_validate_scan = heapam_index_validate_scan,
 
+	.relation_options = heap_reloptions,
 	.relation_size = table_block_relation_size,
 	.relation_needs_toast_table = heapam_relation_needs_toast_table,
 	.relation_toast_am = heapam_relation_toast_am,

src/backend/commands/foreigncmds.c

@@ -62,7 +62,7 @@ static void import_error_callback(void *arg);
  * processing, hence any validation should be done before this
  * conversion.
  */
-static Datum
+Datum
 optionListToArray(List *options)
 {
 	ArrayBuildState *astate = NULL;

src/backend/commands/tablecmds.c

@@ -677,6 +677,8 @@ static void ATPrepSetTableSpace(AlteredTableInfo *tab, Relation rel,
 								const char *tablespacename, LOCKMODE lockmode);
 static void ATExecSetTableSpace(Oid tableOid, Oid newTableSpace, LOCKMODE lockmode);
 static void ATExecSetTableSpaceNoStorage(Relation rel, Oid newTableSpace);
+static void ATExecSetAccessMethodOptions(Relation rel, List *defList, AlterTableType operation,
+										 LOCKMODE lockmode, Oid newAccessMethodId);
 static void ATExecSetRelOptions(Relation rel, List *defList,
 								AlterTableType operation,
 								LOCKMODE lockmode);
@@ -926,24 +928,6 @@ DefineRelation(CreateStmt *stmt, char relkind, Oid ownerId,
 	if (!OidIsValid(ownerId))
 		ownerId = GetUserId();
 
-	/*
-	 * Parse and validate reloptions, if any.
-	 */
-	reloptions = transformRelOptions((Datum) 0, stmt->options, NULL, validnsps,
-									 true, false);
-
-	switch (relkind)
-	{
-		case RELKIND_VIEW:
-			(void) view_reloptions(reloptions, true);
-			break;
-		case RELKIND_PARTITIONED_TABLE:
-			(void) partitioned_table_reloptions(reloptions, true);
-			break;
-		default:
-			(void) heap_reloptions(relkind, reloptions, true);
-	}
-
 	if (stmt->ofTypename)
 	{
 		AclResult	aclresult;
@@ -1046,6 +1030,29 @@ DefineRelation(CreateStmt *stmt, char relkind, Oid ownerId,
 			accessMethodId = get_table_am_oid(default_table_access_method, false);
 	}
 
+	/*
+	 * Parse and validate reloptions, if any.
+	 */
+	reloptions = transformRelOptions((Datum) 0, stmt->options, NULL, validnsps,
+									 true, false);
+	switch (relkind)
+	{
+		case RELKIND_VIEW:
+			(void) view_reloptions(reloptions, true);
+			break;
+		case RELKIND_PARTITIONED_TABLE:
+			(void) partitioned_table_reloptions(reloptions, true);
+			break;
+		case RELKIND_RELATION:
+		case RELKIND_TOASTVALUE:
+		case RELKIND_MATVIEW:
+			(void) table_reloptions(NULL, accessMethodId, relkind, reloptions,
+									true);
+			break;
+		default:
+			(void) heap_reloptions(relkind, reloptions, true);
+	}
+
 	/*
 	 * Create the relation.  Inherited defaults and CHECK constraints are
 	 * passed in for immediate handling --- since they don't need parsing,
@@ -5527,6 +5534,9 @@ ATExecCmd(List **wqueue, AlteredTableInfo *tab,
 			if (rel->rd_rel->relkind == RELKIND_PARTITIONED_TABLE &&
 				tab->chgAccessMethod)
 				ATExecSetAccessMethodNoStorage(rel, tab->newAccessMethod);
+
+			ATExecSetAccessMethodOptions(rel, (List *) cmd->def, cmd->subtype,
+										 lockmode, tab->newAccessMethod);
 			break;
 		case AT_SetTableSpace:	/* SET TABLESPACE */
 
@@ -16550,6 +16560,138 @@ ATPrepSetTableSpace(AlteredTableInfo *tab, Relation rel, const char *tablespacen
 	tab->newTableSpace = tablespaceId;
 }
 
+/* SET, ADD or DROP options in ALTER TABLE SET ACCESS METHOD */
+static void
+ATExecSetAccessMethodOptions(Relation rel, List *options, AlterTableType operation,
+							 LOCKMODE lockmode, Oid newAccessMethodId)
+{
+	Oid			relid;
+	Relation	pgclass;
+	HeapTuple	tuple;
+	HeapTuple	newtuple;
+	Datum		datum;
+	bool		isnull;
+	Datum		newOptions;
+	Datum		repl_val[Natts_pg_class];
+	bool		repl_null[Natts_pg_class];
+	bool		repl_repl[Natts_pg_class];
+	List	   *resultOptions;
+	ListCell   *optcell;
+
+	pgclass = table_open(RelationRelationId, RowExclusiveLock);
+
+	/* Fetch heap tuple */
+	relid = RelationGetRelid(rel);
+	tuple = SearchSysCache1(RELOID, ObjectIdGetDatum(relid));
+	if (!HeapTupleIsValid(tuple))
+		elog(ERROR, "cache lookup failed for relation %u", relid);
+
+	/* Get the old reloptions */
+	datum = SysCacheGetAttr(RELOID, tuple, Anum_pg_class_reloptions, &isnull);
+
+	if (isnull)
+		datum = PointerGetDatum(NULL);
+
+	resultOptions = untransformRelOptions(datum);
+
+	foreach(optcell, options)
+	{
+		DefElem    *od = lfirst(optcell);
+		ListCell   *cell;
+
+		/* Search in existing options */
+		foreach(cell, resultOptions)
+		{
+			DefElem    *def = lfirst(cell);
+
+			if (strcmp(def->defname, od->defname) == 0)
+				break;
+		}
+
+		/*
+		 * It is possible to perform multiple SET/DROP actions on the same
+		 * option.  The standard permits this, as long as the options to be
+		 * added are unique.  Note that an unspecified action is taken to be
+		 * ADD.
+		 */
+		switch (od->defaction)
+		{
+			case DEFELEM_DROP:
+				if (!cell)
+					ereport(ERROR,
+							(errcode(ERRCODE_UNDEFINED_OBJECT),
+							 errmsg("option \"%s\" not found",
+									od->defname)));
+				resultOptions = list_delete_cell(resultOptions, cell);
+				break;
+
+			case DEFELEM_SET:
+				if (!cell)
+					ereport(ERROR,
+							(errcode(ERRCODE_UNDEFINED_OBJECT),
+							 errmsg("option \"%s\" not found",
+									od->defname)));
+				lfirst(cell) = od;
+				break;
+
+			case DEFELEM_ADD:
+			case DEFELEM_UNSPEC:
+				if (cell)
+					ereport(ERROR,
+							(errcode(ERRCODE_DUPLICATE_OBJECT),
+							 errmsg("option \"%s\" provided more than once",
+									od->defname)));
+				resultOptions = lappend(resultOptions, od);
+				break;
+
+			default:
+				elog(ERROR, "unrecognized action %d on option \"%s\"",
+					 (int) od->defaction, od->defname);
+				break;
+		}
+	}
+
+	newOptions = optionListToArray(resultOptions);
+
+	/*
+	 * If the new table access method was not explicitly defined, then use the
+	 * default one.
+	 */
+	if (!OidIsValid(newAccessMethodId))
+		newAccessMethodId = get_table_am_oid(default_table_access_method, false);
+
+	/* Validate new options via the new Table Access Method API */
+	(void) table_reloptions(NULL, newAccessMethodId, rel->rd_rel->relkind,
+							newOptions, true);
+
+	/* Initialize buffers for new tuple values */
+	memset(repl_val, 0, sizeof(repl_val));
+	memset(repl_null, false, sizeof(repl_null));
+	memset(repl_repl, false, sizeof(repl_repl));
+
+	if (newOptions != (Datum) 0)
+		repl_val[Anum_pg_class_reloptions - 1] = newOptions;
+	else
+		repl_null[Anum_pg_class_reloptions - 1] = true;
+
+	repl_repl[Anum_pg_class_reloptions - 1] = true;
+
+	/* Everything looks good - update the tuple */
+	newtuple = heap_modify_tuple(tuple, RelationGetDescr(pgclass),
+								 repl_val, repl_null, repl_repl);
+
+	CatalogTupleUpdate(pgclass, &newtuple->t_self, newtuple);
+
+	InvokeObjectPostAlterHook(RelationRelationId, RelationGetRelid(rel),
+							  InvalidOid);
+
+	ReleaseSysCache(tuple);
+
+	table_close(pgclass, RowExclusiveLock);
+
+	heap_freetuple(newtuple);
+}
+
 /*
  * Set, reset, or replace reloptions.
  */
@@ -16607,7 +16749,7 @@ ATExecSetRelOptions(Relation rel, List *defList, AlterTableType operation,
 	{
 		case RELKIND_RELATION:
 		case RELKIND_MATVIEW:
-			(void) heap_reloptions(rel->rd_rel->relkind, newOptions, true);
+			rel->rd_tableam->relation_options(rel->rd_rel->relkind, newOptions, true);
 			break;
 		case RELKIND_PARTITIONED_TABLE:
 			(void) partitioned_table_reloptions(newOptions, true);