From a27af2ef1cd72ae1eeac635823fc2036051c7213 Mon Sep 17 00:00:00 2001 From: Ayush Vatsa Date: Mon, 12 Aug 2024 01:29:46 +0530 Subject: [PATCH v2 2/2] fix alter_server, alter_foreign_data_wrapper, alter_foreign_table and alter_user_mapping documentation --- .../sgml/ref/alter_foreign_data_wrapper.sgml | 51 +++++++++++++--- doc/src/sgml/ref/alter_foreign_table.sgml | 43 +++++++++++--- doc/src/sgml/ref/alter_server.sgml | 59 ++++++++++++++++--- doc/src/sgml/ref/alter_user_mapping.sgml | 42 ++++++++++--- 4 files changed, 167 insertions(+), 28 deletions(-) diff --git a/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml b/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml index dc0957d965..c20cc479d9 100644 --- a/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml +++ b/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml @@ -24,7 +24,7 @@ PostgreSQL documentation ALTER FOREIGN DATA WRAPPER name [ HANDLER handler_function | NO HANDLER ] [ VALIDATOR validator_function | NO VALIDATOR ] - [ OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ]) ] + [ OPTIONS ( [ ADD | SET | DROP | APPEND | REMOVE ] option ['value'] [, ... ]) ] ALTER FOREIGN DATA WRAPPER name OWNER TO { new_owner | CURRENT_ROLE | CURRENT_USER | SESSION_USER } ALTER FOREIGN DATA WRAPPER name RENAME TO new_name @@ -113,15 +113,43 @@ ALTER FOREIGN DATA WRAPPER name REN - OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ] ) + OPTIONS ( [ ADD | SET | DROP | APPEND | REMOVE ] option ['value'] [, ... ] ) Change options for the foreign-data - wrapper. ADD, SET, and DROP - specify the action to be performed. ADD is assumed - if no operation is explicitly specified. Option names must be - unique; names and values are also validated using the foreign - data wrapper's validator function, if any. + wrapper. ADD, SET, DROP, + APPEND and REMOVE specify the action to be + performed. ADD is assumed if no operation is explicitly + specified. Option names must be unique; names and values are also validated + using the foreign data wrapper's validator function, if any. + + + + ADD can only be used for option names that don't already exist. + It sets the specified name's value as provided. + + + + SET can only be used for option names that already exist. + It overwrites the entire existing value for the specified option. + + + + DROP can only be used for option names that already exist. + It removes the specified name from the list of OPTIONS. + + + + APPEND can be used regardless of whether the option name exists or not. + If the option name doesn't exist, it acts like ADD. + If it does exist, it adds the provided values to the existing ones. + + + + REMOVE can only be used for option names that already exist. + It removes the provided values from the values of the specified option name. + If some provided values don't exist in the option values, they won't have any effect. + Only the values that exist in the options will be removed. @@ -157,6 +185,15 @@ ALTER FOREIGN DATA WRAPPER dbi OPTIONS (ADD foo '1', DROP bar); + + Change a foreign-data wrapper dbi, add + values in option foo, and remove values from + option bar: + +ALTER FOREIGN DATA WRAPPER dbi OPTIONS (APPEND foo '1, 2, 3', REMOVE bar '1, 2'); + + + Change the foreign-data wrapper dbi validator to bob.myvalidator: diff --git a/doc/src/sgml/ref/alter_foreign_table.sgml b/doc/src/sgml/ref/alter_foreign_table.sgml index 3cb6f08fcf..b417f74026 100644 --- a/doc/src/sgml/ref/alter_foreign_table.sgml +++ b/doc/src/sgml/ref/alter_foreign_table.sgml @@ -42,7 +42,7 @@ ALTER FOREIGN TABLE [ IF EXISTS ] namecolumn_name SET ( attribute_option = value [, ... ] ) ALTER [ COLUMN ] column_name RESET ( attribute_option [, ... ] ) ALTER [ COLUMN ] column_name SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN | DEFAULT } - ALTER [ COLUMN ] column_name OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ]) + ALTER [ COLUMN ] column_name OPTIONS ( [ ADD | SET | DROP | APPEND | REMOVE ] option ['value'] [, ... ]) ADD table_constraint [ NOT VALID ] VALIDATE CONSTRAINT constraint_name DROP CONSTRAINT [ IF EXISTS ] constraint_name [ RESTRICT | CASCADE ] @@ -54,7 +54,7 @@ ALTER FOREIGN TABLE [ IF EXISTS ] nameparent_table NO INHERIT parent_table OWNER TO { new_owner | CURRENT_ROLE | CURRENT_USER | SESSION_USER } - OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ]) + OPTIONS ( [ ADD | SET | DROP | APPEND | REMOVE ] option ['value'] [, ... ]) @@ -266,17 +266,46 @@ ALTER FOREIGN TABLE [ IF EXISTS ] name - OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ] ) + OPTIONS ( [ ADD | SET | DROP | APPEND | REMOVE ] option ['value'] [, ... ] ) Change options for the foreign table or one of its columns. - ADD, SET, and DROP - specify the action to be performed. ADD is assumed - if no operation is explicitly specified. Duplicate option names are not + ADD, SET, DROP, + APPEND and REMOVE specify the action to be + performed. ADD is assumed if no operation is explicitly + specified. Duplicate option names are not allowed (although it's OK for a table option and a column option to have the same name). Option names and values are also validated using the foreign data wrapper library. + + + ADD can only be used for option names that don't already exist. + It sets the specified name's value as provided. + + + + SET can only be used for option names that already exist. + It overwrites the entire existing value for the specified option. + + + + DROP can only be used for option names that already exist. + It removes the specified name from the list of OPTIONS. + + + + APPEND can be used regardless of whether the option name exists or not. + If the option name doesn't exist, it acts like ADD. + If it does exist, it adds the provided values to the existing ones. + + + + REMOVE can only be used for option names that already exist. + It removes the provided values from the values of the specified option name. + If some provided values don't exist in the option values, they won't have any effect. + Only the values that exist in the options will be removed. + @@ -521,7 +550,7 @@ ALTER FOREIGN TABLE distributors ALTER COLUMN street SET NOT NULL; To change options of a foreign table: -ALTER FOREIGN TABLE myschema.distributors OPTIONS (ADD opt1 'value', SET opt2 'value2', DROP opt3); +ALTER FOREIGN TABLE myschema.distributors OPTIONS (ADD opt1 'value', SET opt2 'value2', DROP opt3, APPEND opt4 'value3, value4', REMOVE opt5 'value5, value6'); diff --git a/doc/src/sgml/ref/alter_server.sgml b/doc/src/sgml/ref/alter_server.sgml index 467bf85589..953fdf1bc2 100644 --- a/doc/src/sgml/ref/alter_server.sgml +++ b/doc/src/sgml/ref/alter_server.sgml @@ -22,7 +22,7 @@ PostgreSQL documentation ALTER SERVER name [ VERSION 'new_version' ] - [ OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ] ) ] + [ OPTIONS ( [ ADD | SET | DROP | APPEND | REMOVE ] option ['value'] [, ... ] ) ] ALTER SERVER name OWNER TO { new_owner | CURRENT_ROLE | CURRENT_USER | SESSION_USER } ALTER SERVER name RENAME TO new_name @@ -71,15 +71,43 @@ ALTER SERVER name RENAME TO - OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ] ) + OPTIONS ( [ ADD | SET | DROP | APPEND | REMOVE ] option ['value'] [, ... ] ) Change options for the - server. ADD, SET, and DROP - specify the action to be performed. ADD is assumed - if no operation is explicitly specified. Option names must be - unique; names and values are also validated using the server's - foreign-data wrapper library. + server. ADD, SET, DROP, + APPEND and REMOVE specify the action to be + performed. ADD is assumed if no operation is explicitly + specified. Option names must be unique; names and values are also validated + using the server's foreign-data wrapper library. + + + + ADD can only be used for option names that don't already exist. + It sets the specified name's value as provided. + + + + SET can only be used for option names that already exist. + It overwrites the entire existing value for the specified option. + + + + DROP can only be used for option names that already exist. + It removes the specified name from the list of OPTIONS. + + + + APPEND can be used regardless of whether the option name exists or not. + If the option name doesn't exist, it acts like ADD. + If it does exist, it adds the provided values to the existing ones. + + + + REMOVE can only be used for option names that already exist. + It removes the provided values from the values of the specified option name. + If some provided values don't exist in the option values, they won't have any effect. + Only the values that exist in the options will be removed. @@ -114,6 +142,23 @@ ALTER SERVER foo OPTIONS (host 'foo', dbname 'foodb'); + + Suppose a server already contains few extensions then to add + more extensions into existing values use + Alter server foo, append extensions: + +ALTER SERVER foo OPTIONS (APPEND extensions 'ext1, ext2, ext3'); + + + + + To remove some selected values from extensions use + Alter server foo, remove extensions: + +ALTER SERVER foo OPTIONS (REMOVE extensions 'ext1, ext3'); + + + Alter server foo, change version, change host option: diff --git a/doc/src/sgml/ref/alter_user_mapping.sgml b/doc/src/sgml/ref/alter_user_mapping.sgml index ee5aee9bc9..ff420f9c72 100644 --- a/doc/src/sgml/ref/alter_user_mapping.sgml +++ b/doc/src/sgml/ref/alter_user_mapping.sgml @@ -23,7 +23,7 @@ PostgreSQL documentation ALTER USER MAPPING FOR { user_name | USER | CURRENT_ROLE | CURRENT_USER | SESSION_USER | PUBLIC } SERVER server_name - OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ] ) + OPTIONS ( [ ADD | SET | DROP | APPEND | REMOVE ] option ['value'] [, ... ] ) @@ -69,16 +69,44 @@ ALTER USER MAPPING FOR { user_name - OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ] ) + OPTIONS ( [ ADD | SET | DROP | APPEND | REMOVE ] option ['value'] [, ... ] ) Change options for the user mapping. The new options override any previously specified - options. ADD, SET, and DROP - specify the action to be performed. ADD is assumed - if no operation is explicitly specified. Option names must be - unique; options are also validated by the server's foreign-data - wrapper. + options. ADD, SET, DROP, + APPEND and REMOVE specify the action to be + performed. ADD is assumed if no operation is explicitly + specified. Option names must be unique; options are also validated + by the server's foreign-data wrapper. + + + + ADD can only be used for option names that don't already exist. + It sets the specified name's value as provided. + + + + SET can only be used for option names that already exist. + It overwrites the entire existing value for the specified option. + + + + DROP can only be used for option names that already exist. + It removes the specified name from the list of OPTIONS. + + + + APPEND can be used regardless of whether the option name exists or not. + If the option name doesn't exist, it acts like ADD. + If it does exist, it adds the provided values to the existing ones. + + + + REMOVE can only be used for option names that already exist. + It removes the provided values from the values of the specified option name. + If some provided values don't exist in the option values, they won't have any effect. + Only the values that exist in the options will be removed. -- 2.41.0