From 13a7f79dd5b4c5f32d81edc0d88229e828a19b9f Mon Sep 17 00:00:00 2001 From: Zsolt Parragi Date: Wed, 18 Nov 2026 18:44:24 +0000 Subject: [PATCH v1 3/3] Check tablespace options in pg_upgrade Tablespace options registered by an extension are only known while that extension is in shared_preload_libraries. If the new cluster lacks it, pg_upgrade fails late, when restoring the global objects runs ALTER TABLESPACE ... SET with options the new server does not recognize. Add two SQL functions: pg_available_tablespace_options() lists the tablespace options the server knows about, with type, default and bounds, and pg_validate_tablespace_options() checks an options array the way CREATE TABLESPACE would, without touching any tablespace or running utility hooks. pg_upgrade now remembers the options of the old cluster's user tablespaces and validates them on the new cluster before doing anything, reporting the failing tablespaces in tablespace_options.txt. Catversion bump needed. --- doc/src/sgml/func/func-info.sgml | 39 ++++++ doc/src/sgml/ref/alter_tablespace.sgml | 2 + doc/src/sgml/ref/create_tablespace.sgml | 2 + doc/src/sgml/ref/pgupgrade.sgml | 7 ++ src/backend/access/common/reloptions.c | 118 ++++++++++++++++++ src/bin/pg_upgrade/check.c | 7 ++ src/bin/pg_upgrade/pg_upgrade.h | 1 + src/bin/pg_upgrade/tablespace.c | 115 +++++++++++++++++ src/include/catalog/pg_proc.dat | 12 ++ .../test_tablespace_options/meson.build | 1 + .../t/001_tablespace_options.pl | 35 ++++++ .../t/002_pg_upgrade.pl | 86 +++++++++++++ src/test/regress/expected/tablespace.out | 28 +++++ src/test/regress/sql/tablespace.sql | 8 ++ 14 files changed, 461 insertions(+) create mode 100644 src/test/modules/test_tablespace_options/t/002_pg_upgrade.pl diff --git a/doc/src/sgml/func/func-info.sgml b/doc/src/sgml/func/func-info.sgml index b6c080715ba..37a082cdb1a 100644 --- a/doc/src/sgml/func/func-info.sgml +++ b/doc/src/sgml/func/func-info.sgml @@ -1409,6 +1409,29 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); + + + + pg_available_tablespace_options + + pg_available_tablespace_options () + setof record + ( name text, + type text, + default_value text, + min_value text, + max_value text, + description text ) + + + Returns the options that can be set on a tablespace, including those + defined by extensions loaded via + . + min_value and max_value + are null for options that are not numeric. + + + @@ -1954,6 +1977,22 @@ SELECT currval(pg_get_serial_sequence('sometable', 'id')); + + + + pg_validate_tablespace_options + + pg_validate_tablespace_options ( options_array text[] ) + void + + + Checks a value of the form stored in + pg_tablespace.spcoptions + the way CREATE TABLESPACE would, and raises an + error if an option is not recognized or has an invalid value. + + + diff --git a/doc/src/sgml/ref/alter_tablespace.sgml b/doc/src/sgml/ref/alter_tablespace.sgml index 5a5461d1974..e8795ced8f3 100644 --- a/doc/src/sgml/ref/alter_tablespace.sgml +++ b/doc/src/sgml/ref/alter_tablespace.sgml @@ -103,6 +103,8 @@ ALTER TABLESPACE name RESET ( tablespace_name prefix chosen by the extension, as in my_extension.my_option, and can be written without quotes. See the documentation of the extension for their meaning. + pg_available_tablespace_options() lists all + parameters the server accepts. diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index e4e8c02e6d6..14aa47315ab 100644 --- a/doc/src/sgml/ref/pgupgrade.sgml +++ b/doc/src/sgml/ref/pgupgrade.sgml @@ -479,6 +479,13 @@ make prefix=/usr/local/pgsql.new install pg_upgrade will report this and create a script that can be run later to update them. + + + If tablespaces of the old cluster use options defined by an extension, + add that extension to + of the new cluster, or pg_upgrade will + refuse to upgrade. + diff --git a/src/backend/access/common/reloptions.c b/src/backend/access/common/reloptions.c index fb867e72e5b..aae17720735 100644 --- a/src/backend/access/common/reloptions.c +++ b/src/backend/access/common/reloptions.c @@ -27,6 +27,7 @@ #include "catalog/pg_type.h" #include "commands/defrem.h" #include "commands/tablespace.h" +#include "funcapi.h" #include "miscadmin.h" #include "nodes/makefuncs.h" #include "storage/lock.h" @@ -36,6 +37,7 @@ #include "utils/guc.h" #include "utils/memutils.h" #include "utils/rel.h" +#include "utils/tuplestore.h" /* * Contents of pg_class.reloptions @@ -2534,3 +2536,119 @@ AlterTableGetRelOptionsLockLevel(List *defList) return lockmode; } + +/* + * pg_available_tablespace_options + * List the tablespace options known to this backend, built-in ones and + * those registered by extensions. + */ +Datum +pg_available_tablespace_options(PG_FUNCTION_ARGS) +{ + ReturnSetInfo *rsinfo = (ReturnSetInfo *) fcinfo->resultinfo; + + InitMaterializedSRF(fcinfo, 0); + + if (need_initialization) + initialize_reloptions(); + + for (int i = 0; relOpts[i]; i++) + { + relopt_gen *gen = relOpts[i]; + Datum values[6] = {0}; + bool nulls[6] = {0}; + + if ((gen->kinds & RELOPT_KIND_TABLESPACE) == 0) + continue; + + values[0] = CStringGetTextDatum(gen->name); + nulls[2] = nulls[3] = nulls[4] = true; + + switch (gen->type) + { + case RELOPT_TYPE_BOOL: + values[1] = CStringGetTextDatum("bool"); + values[2] = CStringGetTextDatum(((relopt_bool *) gen)->default_val ? + "true" : "false"); + nulls[2] = false; + break; + case RELOPT_TYPE_TERNARY: + values[1] = CStringGetTextDatum("ternary"); + break; + case RELOPT_TYPE_INT: + { + relopt_int *opt = (relopt_int *) gen; + + values[1] = CStringGetTextDatum("integer"); + values[2] = CStringGetTextDatum(psprintf("%d", opt->default_val)); + values[3] = CStringGetTextDatum(psprintf("%d", opt->min)); + values[4] = CStringGetTextDatum(psprintf("%d", opt->max)); + nulls[2] = nulls[3] = nulls[4] = false; + } + break; + case RELOPT_TYPE_REAL: + { + relopt_real *opt = (relopt_real *) gen; + + values[1] = CStringGetTextDatum("real"); + values[2] = CStringGetTextDatum(psprintf("%g", opt->default_val)); + values[3] = CStringGetTextDatum(psprintf("%g", opt->min)); + values[4] = CStringGetTextDatum(psprintf("%g", opt->max)); + nulls[2] = nulls[3] = nulls[4] = false; + } + break; + case RELOPT_TYPE_ENUM: + { + relopt_enum *opt = (relopt_enum *) gen; + + values[1] = CStringGetTextDatum("enum"); + for (relopt_enum_elt_def *elt = opt->members; + elt->string_val; elt++) + { + if (elt->symbol_val == opt->default_val) + { + values[2] = CStringGetTextDatum(elt->string_val); + nulls[2] = false; + break; + } + } + } + break; + case RELOPT_TYPE_STRING: + { + relopt_string *opt = (relopt_string *) gen; + + values[1] = CStringGetTextDatum("string"); + if (!opt->default_isnull) + { + values[2] = CStringGetTextDatum(opt->default_val); + nulls[2] = false; + } + } + break; + } + + if (gen->desc) + values[5] = CStringGetTextDatum(gen->desc); + else + nulls[5] = true; + + tuplestore_putvalues(rsinfo->setResult, rsinfo->setDesc, + values, nulls); + } + + return (Datum) 0; +} + +/* + * pg_validate_tablespace_options + * Check a tablespace options array the way CREATE and ALTER TABLESPACE + * would, without touching any tablespace. + */ +Datum +pg_validate_tablespace_options(PG_FUNCTION_ARGS) +{ + (void) tablespace_reloptions(PG_GETARG_DATUM(0), true); + + PG_RETURN_VOID(); +} diff --git a/src/bin/pg_upgrade/check.c b/src/bin/pg_upgrade/check.c index 2d4aaf22a0f..2d107d99710 100644 --- a/src/bin/pg_upgrade/check.c +++ b/src/bin/pg_upgrade/check.c @@ -707,6 +707,13 @@ check_new_cluster(void) check_new_cluster_is_empty(); + /* + * Check tablespace options first. A library that defines them fails to + * load unless preloaded, which check_loadable_libraries() would report + * less clearly. + */ + check_tablespace_options(); + check_loadable_libraries(); switch (user_opts.transfer_mode) diff --git a/src/bin/pg_upgrade/pg_upgrade.h b/src/bin/pg_upgrade/pg_upgrade.h index 30a2e263d2d..f084b26fc30 100644 --- a/src/bin/pg_upgrade/pg_upgrade.h +++ b/src/bin/pg_upgrade/pg_upgrade.h @@ -445,6 +445,7 @@ void transfer_all_new_dbs(DbInfoArr *old_db_arr, /* tablespace.c */ void init_tablespaces(void); +void check_tablespace_options(void); /* server.c */ diff --git a/src/bin/pg_upgrade/tablespace.c b/src/bin/pg_upgrade/tablespace.c index 95ea7819457..a9bc9479d86 100644 --- a/src/bin/pg_upgrade/tablespace.c +++ b/src/bin/pg_upgrade/tablespace.c @@ -12,13 +12,21 @@ #include "pg_upgrade.h" static void get_tablespace_paths(void); +static void get_tablespace_options(void); static void set_tablespace_directory_suffix(ClusterInfo *cluster); +/* user tablespaces of the old cluster that have options set */ +static char **old_spcnames = NULL; +static char **old_spcoptions = NULL; +static int num_old_spcoptions = 0; +static int old_spcoptions_encoding; + void init_tablespaces(void) { get_tablespace_paths(); + get_tablespace_options(); set_tablespace_directory_suffix(&old_cluster); set_tablespace_directory_suffix(&new_cluster); @@ -138,6 +146,113 @@ get_tablespace_paths(void) } +/* + * get_tablespace_options() + * + * Remember the options of the old cluster's user tablespaces, so that + * check_tablespace_options() can try them on the new cluster. Only + * tablespaces pg_dumpall dumps are of interest. + */ +static void +get_tablespace_options(void) +{ + PGconn *conn = connectToServer(&old_cluster, "template1"); + PGresult *res; + + res = executeQueryOrDie(conn, + "SELECT spcname, spcoptions " + "FROM pg_catalog.pg_tablespace " + "WHERE spcname !~ '^pg_' AND " + " spcoptions IS NOT NULL"); + + old_spcoptions_encoding = PQclientEncoding(conn); + num_old_spcoptions = PQntuples(res); + if (num_old_spcoptions > 0) + { + old_spcnames = pg_malloc_array(char *, num_old_spcoptions); + old_spcoptions = pg_malloc_array(char *, num_old_spcoptions); + } + + for (int i = 0; i < num_old_spcoptions; i++) + { + old_spcnames[i] = pg_strdup(PQgetvalue(res, i, 0)); + old_spcoptions[i] = pg_strdup(PQgetvalue(res, i, 1)); + } + + PQclear(res); + PQfinish(conn); +} + +/* + * check_tablespace_options() + * + * Verify that the new cluster accepts the options of the old cluster's + * tablespaces. Options registered by an extension are only known when the + * extension is in the new cluster's shared_preload_libraries, otherwise + * restoring the tablespaces would fail. + */ +void +check_tablespace_options(void) +{ + PGconn *conn; + FILE *script = NULL; + char output_path[MAXPGPATH]; + + prep_status("Checking for tablespace options"); + + if (num_old_spcoptions == 0) + { + check_ok(); + return; + } + + snprintf(output_path, sizeof(output_path), "%s/%s", + log_opts.basedir, "tablespace_options.txt"); + + conn = connectToServer(&new_cluster, "template1"); + + /* send the options in the encoding we fetched them in */ + if (PQsetClientEncoding(conn, + pg_encoding_to_char(old_spcoptions_encoding)) != 0) + pg_fatal("could not set client encoding: %s", PQerrorMessage(conn)); + + for (int i = 0; i < num_old_spcoptions; i++) + { + const char *params[1]; + PGresult *res; + + params[0] = old_spcoptions[i]; + res = PQexecParams(conn, + "SELECT pg_catalog.pg_validate_tablespace_options($1::pg_catalog.text[])", + 1, NULL, params, NULL, NULL, 0); + + if (PQresultStatus(res) != PGRES_TUPLES_OK) + { + if (script == NULL && (script = fopen_priv(output_path, "w")) == NULL) + pg_fatal("could not open file \"%s\": %m", output_path); + fprintf(script, "tablespace \"%s\": %s", + old_spcnames[i], PQerrorMessage(conn)); + } + + PQclear(res); + } + + PQfinish(conn); + + if (script) + { + fclose(script); + pg_log(PG_REPORT, "fatal"); + pg_fatal("Your installation contains tablespaces with options the new cluster does\n" + "not accept. Options defined by an extension require that extension in\n" + "\"shared_preload_libraries\" of the new cluster. A list of problem\n" + "tablespaces is in the file:\n" + " %s", output_path); + } + else + check_ok(); +} + static void set_tablespace_directory_suffix(ClusterInfo *cluster) { diff --git a/src/include/catalog/pg_proc.dat b/src/include/catalog/pg_proc.dat index 50fb182cb79..0e106f8b968 100644 --- a/src/include/catalog/pg_proc.dat +++ b/src/include/catalog/pg_proc.dat @@ -4068,6 +4068,18 @@ proallargtypes => '{_text,text,text}', proargmodes => '{i,o,o}', proargnames => '{options_array,option_name,option_value}', prosrc => 'pg_options_to_table' }, +{ oid => '9403', descr => 'list available tablespace options', + proname => 'pg_available_tablespace_options', prorows => '10', + proretset => 't', provolatile => 's', prorettype => 'record', + proargtypes => '', proallargtypes => '{text,text,text,text,text,text}', + proargmodes => '{o,o,o,o,o,o}', + proargnames => '{name,type,default_value,min_value,max_value,description}', + prosrc => 'pg_available_tablespace_options' }, +{ oid => '9404', descr => 'validate a tablespace options array', + proname => 'pg_validate_tablespace_options', provolatile => 's', + prorettype => 'void', proargtypes => '_text', + proargnames => '{options_array}', + prosrc => 'pg_validate_tablespace_options' }, { oid => '1619', descr => 'type of the argument', proname => 'pg_typeof', proisstrict => 'f', provolatile => 's', diff --git a/src/test/modules/test_tablespace_options/meson.build b/src/test/modules/test_tablespace_options/meson.build index 8230b1273e4..a5f6571f70e 100644 --- a/src/test/modules/test_tablespace_options/meson.build +++ b/src/test/modules/test_tablespace_options/meson.build @@ -23,6 +23,7 @@ tests += { 'tap': { 'tests': [ 't/001_tablespace_options.pl', + 't/002_pg_upgrade.pl', ], }, } diff --git a/src/test/modules/test_tablespace_options/t/001_tablespace_options.pl b/src/test/modules/test_tablespace_options/t/001_tablespace_options.pl index 35a80537c39..47c3aa61419 100644 --- a/src/test/modules/test_tablespace_options/t/001_tablespace_options.pl +++ b/src/test/modules/test_tablespace_options/t/001_tablespace_options.pl @@ -49,6 +49,27 @@ is( spcoptions('regress_ts1'), '{test_tablespace_options.mode=safe,random_page_cost=2,test_tablespace_options.level=4}', 'ALTER TABLESPACE RESET with an unquoted name'); +# The options are listed and can be validated without a tablespace +is( $node->safe_psql('postgres', + "SELECT name, type, default_value, min_value, max_value FROM pg_available_tablespace_options() WHERE name LIKE 'test_tablespace_options.%' ORDER BY name" + ), + 'test_tablespace_options.flag|bool|false|| +test_tablespace_options.label|string||| +test_tablespace_options.level|integer|1|0|10 +test_tablespace_options.mode|enum|fast||', + 'pg_available_tablespace_options lists extension options'); + +$node->safe_psql('postgres', + "SELECT pg_validate_tablespace_options('{test_tablespace_options.level=5,test_tablespace_options.mode=fast}')" +); +($ret, $stdout, $stderr) = $node->psql('postgres', + "SELECT pg_validate_tablespace_options('{test_tablespace_options.level=50}')" +); +like( + $stderr, + qr/value 50 out of bounds for option "test_tablespace_options.level"/, + 'pg_validate_tablespace_options rejects invalid value'); + # Values are validated ($ret, $stdout, $stderr) = $node->psql('postgres', "ALTER TABLESPACE regress_ts1 SET (test_tablespace_options.level = 11)"); @@ -122,6 +143,20 @@ $node->restart; is($node->safe_psql('postgres', 'SELECT count(*) FROM regress_tab'), '0', 'table in tablespace with unknown options is usable'); +is( $node->safe_psql('postgres', + "SELECT count(*) FROM pg_available_tablespace_options() WHERE name LIKE 'test_tablespace_options.%'" + ), + '0', + 'extension options are not listed without the extension'); + +($ret, $stdout, $stderr) = $node->psql('postgres', + "SELECT pg_validate_tablespace_options('{test_tablespace_options.level=5}')" +); +like( + $stderr, + qr/unrecognized parameter "test_tablespace_options.level"/, + 'pg_validate_tablespace_options rejects unknown option'); + ($ret, $stdout, $stderr) = $node->psql('postgres', "ALTER TABLESPACE regress_ts1 SET (seq_page_cost = 2)"); like( diff --git a/src/test/modules/test_tablespace_options/t/002_pg_upgrade.pl b/src/test/modules/test_tablespace_options/t/002_pg_upgrade.pl new file mode 100644 index 00000000000..88cd28655c7 --- /dev/null +++ b/src/test/modules/test_tablespace_options/t/002_pg_upgrade.pl @@ -0,0 +1,86 @@ +# Copyright (c) 2026, PostgreSQL Global Development Group + +# pg_upgrade checks that the new cluster accepts the old cluster's +# tablespace options + +use strict; +use warnings FATAL => 'all'; + +use File::Path qw(rmtree); +use PostgreSQL::Test::Cluster; +use PostgreSQL::Test::Utils; +use Test::More; + +my $preload = "shared_preload_libraries = 'test_tablespace_options'\n"; + +# Use a different encoding in the old cluster, to check that the options +# are passed on unchanged. +my $old = PostgreSQL::Test::Cluster->new('old'); +$old->init(extra => [ '--encoding' => 'LATIN1', '--locale' => 'C' ]); +$old->append_conf('postgresql.conf', + "allow_in_place_tablespaces = on\n" . $preload); +$old->start; +$old->safe_psql('postgres', + "SET client_encoding = 'LATIN1'; + CREATE TABLESPACE regress_ts LOCATION '' WITH (test_tablespace_options.level = 7, test_tablespace_options.label = 'caf\xe9', seq_page_cost = 3)" +); + +# Text in shared catalogs has no defined encoding, so the non-ASCII value +# comes out of the upgrade in the encoding the restore session used. Only +# check that it is there. +my $query = "SELECT string_agg(option_name || '=' || + CASE WHEN option_name = 'test_tablespace_options.label' + THEN '?' ELSE option_value END, ',' ORDER BY option_name) + FROM pg_tablespace, pg_options_to_table(spcoptions) + WHERE spcname = 'regress_ts'"; +my $before = $old->safe_psql('postgres', $query); +$old->stop; + +my $new = PostgreSQL::Test::Cluster->new('new'); +$new->init(extra => [ '--encoding' => 'UTF8', '--locale' => 'C' ]); +$new->append_conf('postgresql.conf', "allow_in_place_tablespaces = on\n"); + +# In a VPATH build, we'll be started in the source directory, but we want +# to run pg_upgrade in the build directory so that any files generated finish +# in it, like delete_old_cluster.{sh,bat}. +chdir ${PostgreSQL::Test::Utils::tmp_check}; + +my @pg_upgrade = ( + 'pg_upgrade', '--no-sync', + '--old-datadir' => $old->data_dir, + '--new-datadir' => $new->data_dir, + '--old-bindir' => $old->config_data('--bindir'), + '--new-bindir' => $new->config_data('--bindir'), + '--socketdir' => $new->host, + '--old-port' => $old->port, + '--new-port' => $new->port, + '--copy'); + +# Without the extension, the new cluster does not accept the options +command_checks_all( + [ @pg_upgrade, '--check' ], + 1, + [qr/Checking for tablespace options\s+fatal/], + [], + 'pg_upgrade --check fails without the extension in the new cluster'); + +my @reports = glob($new->data_dir . '/pg_upgrade_output.d/*/tablespace_options.txt'); +is(scalar(@reports), 1, 'tablespace_options.txt is written'); +like( + slurp_file($reports[0]), + qr/tablespace "regress_ts": ERROR: unrecognized parameter "test_tablespace_options\.\w+"/, + 'tablespace_options.txt names the tablespace'); +rmtree($new->data_dir . '/pg_upgrade_output.d'); + +# With the extension, the check passes and the options are carried over +$new->append_conf('postgresql.conf', $preload); +command_ok([ @pg_upgrade, '--check' ], + 'pg_upgrade --check passes with the extension in the new cluster'); +command_ok(\@pg_upgrade, 'pg_upgrade'); + +$new->start; +is($new->safe_psql('postgres', $query), + $before, 'tablespace options are preserved'); +$new->stop; + +done_testing(); diff --git a/src/test/regress/expected/tablespace.out b/src/test/regress/expected/tablespace.out index f0dd25cdf0c..d8e87e899c5 100644 --- a/src/test/regress/expected/tablespace.out +++ b/src/test/regress/expected/tablespace.out @@ -38,6 +38,34 @@ ERROR: unrecognized parameter "some_nonexistent_parameter" ALTER TABLESPACE regress_tblspace RESET (random_page_cost = 2.0); -- fail ERROR: RESET must not include values for parameters ALTER TABLESPACE regress_tblspace RESET (random_page_cost, effective_io_concurrency); -- ok +-- available options and validation without a tablespace +SELECT name, type, default_value, min_value + FROM pg_available_tablespace_options() ORDER BY name; + name | type | default_value | min_value +----------------------------+---------+---------------+----------- + effective_io_concurrency | integer | -1 | 0 + maintenance_io_concurrency | integer | -1 | 0 + random_page_cost | real | -1 | 0 + seq_page_cost | real | -1 | 0 +(4 rows) + +SELECT pg_validate_tablespace_options('{random_page_cost=2,seq_page_cost=1.5}'); -- ok + pg_validate_tablespace_options +-------------------------------- + +(1 row) + +SELECT pg_validate_tablespace_options('{effective_io_concurrency=10000}'); -- fail +ERROR: value 10000 out of bounds for option "effective_io_concurrency" +DETAIL: Valid values are between "0" and "1000". +SELECT pg_validate_tablespace_options('{some_nonexistent_parameter=true}'); -- fail +ERROR: unrecognized parameter "some_nonexistent_parameter" +SELECT pg_validate_tablespace_options('{}'); -- ok + pg_validate_tablespace_options +-------------------------------- + +(1 row) + -- REINDEX (TABLESPACE) -- catalogs and system tablespaces -- system catalog, fail diff --git a/src/test/regress/sql/tablespace.sql b/src/test/regress/sql/tablespace.sql index c43a59e5957..366246c1afe 100644 --- a/src/test/regress/sql/tablespace.sql +++ b/src/test/regress/sql/tablespace.sql @@ -31,6 +31,14 @@ ALTER TABLESPACE regress_tblspace SET (some_nonexistent_parameter = true); -- f ALTER TABLESPACE regress_tblspace RESET (random_page_cost = 2.0); -- fail ALTER TABLESPACE regress_tblspace RESET (random_page_cost, effective_io_concurrency); -- ok +-- available options and validation without a tablespace +SELECT name, type, default_value, min_value + FROM pg_available_tablespace_options() ORDER BY name; +SELECT pg_validate_tablespace_options('{random_page_cost=2,seq_page_cost=1.5}'); -- ok +SELECT pg_validate_tablespace_options('{effective_io_concurrency=10000}'); -- fail +SELECT pg_validate_tablespace_options('{some_nonexistent_parameter=true}'); -- fail +SELECT pg_validate_tablespace_options('{}'); -- ok + -- REINDEX (TABLESPACE) -- catalogs and system tablespaces -- system catalog, fail -- 2.56.0