rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
postgresql/doc/src/sgml/ref/alter_table.sgml

1554 lines
65 KiB
Plaintext
Raw Normal View History

Complete merge of all old man page information. ecpg reference page still needs formatting.
1999-07-22 17:09:15 +02:00
<!--
Remove cvs keywords from all files.
2010-09-20 22:08:53 +02:00
doc/src/sgml/ref/alter_table.sgml
Use PostgreSQL consistantly throughout docs. Before, usage was split evenly between Postgres and PostgreSQL.
2001-12-08 04:24:40 +01:00
PostgreSQL documentation
Complete merge of all old man page information. ecpg reference page still needs formatting.
1999-07-22 17:09:15 +02:00
-->
Convert SGML IDs to lower case IDs in SGML are case insensitive, and we have accumulated a mix of upper and lower case IDs, including different variants of the same ID. In XML, these will be case sensitive, so we need to fix up those differences. Going to all lower case seems most straightforward, and the current build process already makes all anchors and lower case anyway during the SGML->XML conversion, so this doesn't create any difference in the output right now. A future XML-only build process would, however, maintain any mixed case ID spellings in the output, so that is another reason to clean this up beforehand. Author: Alexander Lakhin <exclusion@gmail.com>
2017-10-20 03:16:39 +02:00
<refentry id="sql-altertable">
doc: Improve DocBook XML validity DocBook XML is superficially compatible with DocBook SGML but has a slightly stricter DTD that we have been violating in a few cases. Although XSLT doesn't care whether the document is valid, the style sheets don't necessarily process invalid documents correctly, so we need to work toward fixing this. This first commit moves the indexterms in refentry elements to an allowed position. It has no impact on the output.
2014-02-24 03:25:35 +01:00
<indexterm zone="sql-altertable">
<primary>ALTER TABLE</primary>
</indexterm>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<refmeta>
Remove unnecessary xref endterm attributes and title ids The endterm attribute is mainly useful when the toolchain does not support automatic link target text generation for a particular situation. In the past, this was required by the man page tools for all reference page links, but that is no longer the case, and it now actually gets in the way of proper automatic link text generation. The only remaining use cases are currently xrefs to refsects.
2010-04-03 09:23:02 +02:00
<refentrytitle>ALTER TABLE</refentrytitle>
Set SQL man pages to be section 7 by default, and only transform them to another section if required by the platform (instead of the old way of building them in section "l" and always transforming them to the platform-specific section). This speeds up the installation on common platforms, and it avoids some funny business with the man page tools and build process.
2008-11-14 11:22:48 +01:00
<manvolnum>7</manvolnum>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<refnamediv>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<refname>ALTER TABLE</refname>
<refpurpose>change the definition of a table</refpurpose>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</refnamediv>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<refsynopsisdiv>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<synopsis>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
ALTER TABLE [ IF EXISTS ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ]
<replaceable class="parameter">action</replaceable> [, ... ]
ALTER TABLE [ IF EXISTS ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ]
RENAME [ COLUMN ] <replaceable class="parameter">column_name</replaceable> TO <replaceable class="parameter">new_column_name</replaceable>
ALTER TABLE [ IF EXISTS ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ]
RENAME CONSTRAINT <replaceable class="parameter">constraint_name</replaceable> TO <replaceable class="parameter">new_constraint_name</replaceable>
ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable>
RENAME TO <replaceable class="parameter">new_name</replaceable>
ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable>
SET SCHEMA <replaceable class="parameter">new_schema</replaceable>
ALTER TABLE ALL IN TABLESPACE <replaceable class="parameter">name</replaceable> [ OWNED BY <replaceable class="parameter">role_name</replaceable> [, ... ] ]
SET TABLESPACE <replaceable class="parameter">new_tablespace</replaceable> [ NOWAIT ]
ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable>
ATTACH PARTITION <replaceable class="parameter">partition_name</replaceable> { FOR VALUES <replaceable class="parameter">partition_bound_spec</replaceable> | DEFAULT }
ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable>
DETACH PARTITION <replaceable class="parameter">partition_name</replaceable>
<phrase>where <replaceable class="parameter">action</replaceable> is one of:</phrase>
ADD [ COLUMN ] [ IF NOT EXISTS ] <replaceable class="parameter">column_name</replaceable> <replaceable class="parameter">data_type</replaceable> [ COLLATE <replaceable class="parameter">collation</replaceable> ] [ <replaceable class="parameter">column_constraint</replaceable> [ ... ] ]
DROP [ COLUMN ] [ IF EXISTS ] <replaceable class="parameter">column_name</replaceable> [ RESTRICT | CASCADE ]
ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> [ SET DATA ] TYPE <replaceable class="parameter">data_type</replaceable> [ COLLATE <replaceable class="parameter">collation</replaceable> ] [ USING <replaceable class="parameter">expression</replaceable> ]
ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> SET DEFAULT <replaceable class="parameter">expression</replaceable>
ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> DROP DEFAULT
ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> { SET | DROP } NOT NULL
ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> ADD GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( <replaceable>sequence_options</replaceable> ) ]
ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> { SET GENERATED { ALWAYS | BY DEFAULT } | SET <replaceable>sequence_option</replaceable> | RESTART [ [ WITH ] <replaceable class="parameter">restart</replaceable> ] } [...]
ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> DROP IDENTITY [ IF EXISTS ]
ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> SET STATISTICS <replaceable class="parameter">integer</replaceable>
ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> SET ( <replaceable class="parameter">attribute_option</replaceable> = <replaceable class="parameter">value</replaceable> [, ... ] )
ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> RESET ( <replaceable class="parameter">attribute_option</replaceable> [, ... ] )
ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN }
ADD <replaceable class="parameter">table_constraint</replaceable> [ NOT VALID ]
ADD <replaceable class="parameter">table_constraint_using_index</replaceable>
ALTER CONSTRAINT <replaceable class="parameter">constraint_name</replaceable> [ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
VALIDATE CONSTRAINT <replaceable class="parameter">constraint_name</replaceable>
DROP CONSTRAINT [ IF EXISTS ] <replaceable class="parameter">constraint_name</replaceable> [ RESTRICT | CASCADE ]
DISABLE TRIGGER [ <replaceable class="parameter">trigger_name</replaceable> | ALL | USER ]
ENABLE TRIGGER [ <replaceable class="parameter">trigger_name</replaceable> | ALL | USER ]
ENABLE REPLICA TRIGGER <replaceable class="parameter">trigger_name</replaceable>
ENABLE ALWAYS TRIGGER <replaceable class="parameter">trigger_name</replaceable>
DISABLE RULE <replaceable class="parameter">rewrite_rule_name</replaceable>
ENABLE RULE <replaceable class="parameter">rewrite_rule_name</replaceable>
ENABLE REPLICA RULE <replaceable class="parameter">rewrite_rule_name</replaceable>
ENABLE ALWAYS RULE <replaceable class="parameter">rewrite_rule_name</replaceable>
Row-Level Security Policies (RLS) Building on the updatable security-barrier views work, add the ability to define policies on tables to limit the set of rows which are returned from a query and which are allowed to be added to a table. Expressions defined by the policy for filtering are added to the security barrier quals of the query, while expressions defined to check records being added to a table are added to the with-check options of the query. New top-level commands are CREATE/ALTER/DROP POLICY and are controlled by the table owner. Row Security is able to be enabled and disabled by the owner on a per-table basis using ALTER TABLE .. ENABLE/DISABLE ROW SECURITY. Per discussion, ROW SECURITY is disabled on tables by default and must be enabled for policies on the table to be used. If no policies exist on a table with ROW SECURITY enabled, a default-deny policy is used and no records will be visible. By default, row security is applied at all times except for the table owner and the superuser. A new GUC, row_security, is added which can be set to ON, OFF, or FORCE. When set to FORCE, row security will be applied even for the table owner and superusers. When set to OFF, row security will be disabled when allowed and an error will be thrown if the user does not have rights to bypass row security. Per discussion, pg_dump sets row_security = OFF by default to ensure that exports and backups will have all data in the table or will error if there are insufficient privileges to bypass row security. A new option has been added to pg_dump, --enable-row-security, to ask pg_dump to export with row security enabled. A new role capability, BYPASSRLS, which can only be set by the superuser, is added to allow other users to be able to bypass row security using row_security = OFF. Many thanks to the various individuals who have helped with the design, particularly Robert Haas for his feedback. Authors include Craig Ringer, KaiGai Kohei, Adam Brightwell, Dean Rasheed, with additional changes and rework by me. Reviewers have included all of the above, Greg Smith, Jeff McCormick, and Robert Haas.
2014-09-19 17:18:35 +02:00
DISABLE ROW LEVEL SECURITY
ENABLE ROW LEVEL SECURITY
ALTER TABLE .. FORCE ROW LEVEL SECURITY To allow users to force RLS to always be applied, even for table owners, add ALTER TABLE .. FORCE ROW LEVEL SECURITY. row_security=off overrides FORCE ROW LEVEL SECURITY, to ensure pg_dump output is complete (by default). Also add SECURITY_NOFORCE_RLS context to avoid data corruption when ALTER TABLE .. FORCE ROW SECURITY is being used. The SECURITY_NOFORCE_RLS security context is used only during referential integrity checks and is only considered in check_enable_rls() after we have already checked that the current user is the owner of the relation (which should always be the case during referential integrity checks). Back-patch to 9.5 where RLS was added.
2015-10-05 03:05:08 +02:00
FORCE ROW LEVEL SECURITY
NO FORCE ROW LEVEL SECURITY
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
CLUSTER ON <replaceable class="parameter">index_name</replaceable>
OK, here's the final version of ALTER TABLE ... SET WITHOUT CLUSTER. Has docs + regression test. Christopher Kings-Lynne
2004-06-02 23:01:10 +02:00
SET WITHOUT CLUSTER
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
SET WITH OIDS
ALTER TABLE SET TABLESPACE. Gavin Sherry, some rework by Tom Lane.
2004-07-12 01:13:58 +02:00
SET WITHOUT OIDS
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
SET TABLESPACE <replaceable class="parameter">new_tablespace</replaceable>
Minor enhancement of readability of ALTER TABLE syntax in the doc. Fabrízio Mello
2015-05-22 14:42:15 +02:00
SET { LOGGED | UNLOGGED }
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
SET ( <replaceable class="parameter">storage_parameter</replaceable> = <replaceable class="parameter">value</replaceable> [, ... ] )
RESET ( <replaceable class="parameter">storage_parameter</replaceable> [, ... ] )
INHERIT <replaceable class="parameter">parent_table</replaceable>
NO INHERIT <replaceable class="parameter">parent_table</replaceable>
OF <replaceable class="parameter">type_name</replaceable>
Allow ALTER TABLE name {OF type | NOT OF}. This syntax allows a standalone table to be made into a typed table, or a typed table to be made standalone. This is possibly a mildly useful feature in its own right, but the real motivation for this change is that we need it to make pg_upgrade work with typed tables. This doesn't actually fix that problem, but it's necessary infrastructure. Noah Misch
2011-04-21 03:35:15 +02:00
NOT OF
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
OWNER TO { <replaceable class="parameter">new_owner</replaceable> | CURRENT_USER | SESSION_USER }
REPLICA IDENTITY { DEFAULT | USING INDEX <replaceable class="parameter">index_name</replaceable> | FULL | NOTHING }
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
Improve ALTER TABLE synopsis Add into the ALTER TABLE synopsis the definition of partition_bound_spec, column_constraint, index_parameters and exclude_element. Initial patch by Lætitia Avrot, with further improvements by Amit Langote and Thomas Munro. Discussion: https://postgr.es/m/flat/27ec4df3-d1ab-3411-f87f-647f944897e1%40lab.ntt.co.jp
2018-02-02 11:30:04 +01:00
<phrase>and <replaceable class="parameter">partition_bound_spec</replaceable> is:</phrase>
Fix handling of partition bounds for boolean partitioning columns. Previously, you could partition by a boolean column as long as you spelled the bound values as string literals, for instance FOR VALUES IN ('t'). The trouble with this is that ruleutils.c printed that as FOR VALUES IN (TRUE), which is reasonable syntax but wasn't accepted by the grammar. That results in dump-and-reload failures for such cases. Apply a minimal fix that just causes TRUE and FALSE to be converted to strings 'true' and 'false'. This is pretty grotty, but it's too late for a more principled fix in v11 (to say nothing of v10). We should revisit the whole issue of how partition bound values are parsed for v12. Amit Langote Discussion: https://postgr.es/m/e05c5162-1103-7e37-d1ab-6de3e0afaf70@lab.ntt.co.jp
2018-04-23 21:29:11 +02:00
IN ( { <replaceable class="parameter">numeric_literal</replaceable> | <replaceable class="parameter">string_literal</replaceable> | TRUE | FALSE | NULL } [, ...] ) |
FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replaceable class="parameter">string_literal</replaceable> | TRUE | FALSE | MINVALUE | MAXVALUE } [, ...] )
TO ( { <replaceable class="parameter">numeric_literal</replaceable> | <replaceable class="parameter">string_literal</replaceable> | TRUE | FALSE | MINVALUE | MAXVALUE } [, ...] ) |
Improve ALTER TABLE synopsis Add into the ALTER TABLE synopsis the definition of partition_bound_spec, column_constraint, index_parameters and exclude_element. Initial patch by Lætitia Avrot, with further improvements by Amit Langote and Thomas Munro. Discussion: https://postgr.es/m/flat/27ec4df3-d1ab-3411-f87f-647f944897e1%40lab.ntt.co.jp
2018-02-02 11:30:04 +01:00
WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REMAINDER <replaceable class="parameter">numeric_literal</replaceable> )
<phrase>and <replaceable class="parameter">column_constraint</replaceable> is:</phrase>
[ CONSTRAINT <replaceable class="parameter">constraint_name</replaceable> ]
{ NOT NULL |
NULL |
CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] |
DEFAULT <replaceable>default_expr</replaceable> |
GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( <replaceable>sequence_options</replaceable> ) ] |
UNIQUE <replaceable class="parameter">index_parameters</replaceable> |
PRIMARY KEY <replaceable class="parameter">index_parameters</replaceable> |
REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> ) ] [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ]
[ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON UPDATE <replaceable class="parameter">action</replaceable> ] }
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
Add table_constraint synopsis to ALTER TABLE documentation. This is already present in the CREATE TABLE documentation, but it's nicer not to have to refer to CREATE TABLE to find out the syntax for ALTER TABLE. Lætitia Avrot
2017-10-28 11:20:00 +02:00
<phrase>and <replaceable class="parameter">table_constraint</replaceable> is:</phrase>
[ CONSTRAINT <replaceable class="parameter">constraint_name</replaceable> ]
{ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] |
UNIQUE ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) <replaceable class="parameter">index_parameters</replaceable> |
PRIMARY KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) <replaceable class="parameter">index_parameters</replaceable> |
EXCLUDE [ USING <replaceable class="parameter">index_method</replaceable> ] ( <replaceable class="parameter">exclude_element</replaceable> WITH <replaceable class="parameter">operator</replaceable> [, ... ] ) <replaceable class="parameter">index_parameters</replaceable> [ WHERE ( <replaceable class="parameter">predicate</replaceable> ) ] |
FOREIGN KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> [, ... ] ) ]
[ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] [ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON UPDATE <replaceable class="parameter">action</replaceable> ] }
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<phrase>and <replaceable class="parameter">table_constraint_using_index</replaceable> is:</phrase>
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
[ CONSTRAINT <replaceable class="parameter">constraint_name</replaceable> ]
{ UNIQUE | PRIMARY KEY } USING INDEX <replaceable class="parameter">index_name</replaceable>
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
Improve ALTER TABLE synopsis Add into the ALTER TABLE synopsis the definition of partition_bound_spec, column_constraint, index_parameters and exclude_element. Initial patch by Lætitia Avrot, with further improvements by Amit Langote and Thomas Munro. Discussion: https://postgr.es/m/flat/27ec4df3-d1ab-3411-f87f-647f944897e1%40lab.ntt.co.jp
2018-02-02 11:30:04 +01:00
<phrase><replaceable class="parameter">index_parameters</replaceable> in <literal>UNIQUE</literal>, <literal>PRIMARY KEY</literal>, and <literal>EXCLUDE</literal> constraints are:</phrase>
Improve docs for the new INCLUDE directive in CREATE/ALTER TABLE. Author: Michael Paquier Discussion: https://www.postgresql.org/message-id/20180411082020.GD19732%40paquier.xyz
2018-04-18 11:44:29 +02:00
[ INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ]
Improve ALTER TABLE synopsis Add into the ALTER TABLE synopsis the definition of partition_bound_spec, column_constraint, index_parameters and exclude_element. Initial patch by Lætitia Avrot, with further improvements by Amit Langote and Thomas Munro. Discussion: https://postgr.es/m/flat/27ec4df3-d1ab-3411-f87f-647f944897e1%40lab.ntt.co.jp
2018-02-02 11:30:04 +01:00
[ WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ]
[ USING INDEX TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
<phrase><replaceable class="parameter">exclude_element</replaceable> in an <literal>EXCLUDE</literal> constraint is:</phrase>
{ <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ <replaceable class="parameter">opclass</replaceable> ] [ ASC | DESC ] [ NULLS { FIRST | LAST } ]
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</synopsis>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</refsynopsisdiv>
First files for reference pages.
1998-05-13 07:34:00 +02:00
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<refsect1>
<title>Description</title>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<para>
Markup and editing adjustments...
1998-09-16 16:43:12 +02:00
<command>ALTER TABLE</command> changes the definition of an existing table.
Reduce lock levels of some ALTER TABLE cmds VALIDATE CONSTRAINT CLUSTER ON SET WITHOUT CLUSTER ALTER COLUMN SET STATISTICS ALTER COLUMN SET () ALTER COLUMN RESET () All other sub-commands use AccessExclusiveLock Simon Riggs and Noah Misch Reviews by Robert Haas and Andres Freund
2014-04-06 17:13:43 +02:00
There are several subforms described below. Note that the lock level required
may differ for each subform. An <literal>ACCESS EXCLUSIVE</literal> lock is held
unless explicitly noted. When multiple subcommands are listed, the lock
held will be the strictest one required from any subcommand.
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
<variablelist>
<varlistentry>
Add IF NOT EXISTS processing to ALTER TABLE ADD COLUMN Fabrízio de Royes Mello, reviewed by Payal Singh, Alvaro Herrera and Michael Paquier.
2015-07-30 03:30:00 +02:00
<term><literal>ADD COLUMN [ IF NOT EXISTS ]</literal></term>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
<listitem>
<para>
Documentation for ALTER object SET SCHEMA commands. Also some minor editorialization.
2005-08-01 18:11:14 +02:00
This form adds a new column to the table, using the same syntax as
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="sql-createtable"/>. If <literal>IF NOT EXISTS</literal>
Add IF NOT EXISTS processing to ALTER TABLE ADD COLUMN Fabrízio de Royes Mello, reviewed by Payal Singh, Alvaro Herrera and Michael Paquier.
2015-07-30 03:30:00 +02:00
is specified and a column already exists with this name,
no error is thrown.
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
</para>
</listitem>
</varlistentry>
ALTER TABLE DROP COLUMN works. Patch by Christopher Kings-Lynne, code review by Tom Lane. Remaining issues: functions that take or return tuple types are likely to break if one drops (or adds!) a column in the table defining the type. Need to think about what to do here. Along the way: some code review for recent COPY changes; mark system columns attnotnull = true where appropriate, per discussion a month ago.
2002-08-02 20:15:10 +02:00
<varlistentry>
DROP IF EXISTS for columns and constraints. Andres Freund.
2009-07-20 04:42:28 +02:00
<term><literal>DROP COLUMN [ IF EXISTS ]</literal></term>
ALTER TABLE DROP COLUMN works. Patch by Christopher Kings-Lynne, code review by Tom Lane. Remaining issues: functions that take or return tuple types are likely to break if one drops (or adds!) a column in the table defining the type. Need to think about what to do here. Along the way: some code review for recent COPY changes; mark system columns attnotnull = true where appropriate, per discussion a month ago.
2002-08-02 20:15:10 +02:00
<listitem>
<para>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
This form drops a column from a table. Indexes and
ALTER TABLE DROP COLUMN works. Patch by Christopher Kings-Lynne, code review by Tom Lane. Remaining issues: functions that take or return tuple types are likely to break if one drops (or adds!) a column in the table defining the type. Need to think about what to do here. Along the way: some code review for recent COPY changes; mark system columns attnotnull = true where appropriate, per discussion a month ago.
2002-08-02 20:15:10 +02:00
table constraints involving the column will be automatically
Implement multivariate n-distinct coefficients Add support for explicitly declared statistic objects (CREATE STATISTICS), allowing collection of statistics on more complex combinations that individual table columns. Companion commands DROP STATISTICS and ALTER STATISTICS ... OWNER TO / SET SCHEMA / RENAME are added too. All this DDL has been designed so that more statistic types can be added later on, such as multivariate most-common-values and multivariate histograms between columns of a single table, leaving room for permitting columns on multiple tables, too, as well as expressions. This commit only adds support for collection of n-distinct coefficient on user-specified sets of columns in a single table. This is useful to estimate number of distinct groups in GROUP BY and DISTINCT clauses; estimation errors there can cause over-allocation of memory in hashed aggregates, for instance, so it's a worthwhile problem to solve. A new special pseudo-type pg_ndistinct is used. (num-distinct estimation was deemed sufficiently useful by itself that this is worthwhile even if no further statistic types are added immediately; so much so that another version of essentially the same functionality was submitted by Kyotaro Horiguchi: https://postgr.es/m/20150828.173334.114731693.horiguchi.kyotaro@lab.ntt.co.jp though this commit does not use that code.) Author: Tomas Vondra. Some code rework by Álvaro. Reviewed-by: Dean Rasheed, David Rowley, Kyotaro Horiguchi, Jeff Janes, Ideriha Takeshi Discussion: https://postgr.es/m/543AFA15.4080608@fuzzy.cz https://postgr.es/m/20170320190220.ixlaueanxegqd5gr@alvherre.pgsql
2017-03-24 18:06:10 +01:00
dropped as well.
Multivariate statistics referencing the dropped column will also be
removed if the removal of the column would cause the statistics to
contain data for only a single column.
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
You will need to say <literal>CASCADE</literal> if anything outside the table
Implement multivariate n-distinct coefficients Add support for explicitly declared statistic objects (CREATE STATISTICS), allowing collection of statistics on more complex combinations that individual table columns. Companion commands DROP STATISTICS and ALTER STATISTICS ... OWNER TO / SET SCHEMA / RENAME are added too. All this DDL has been designed so that more statistic types can be added later on, such as multivariate most-common-values and multivariate histograms between columns of a single table, leaving room for permitting columns on multiple tables, too, as well as expressions. This commit only adds support for collection of n-distinct coefficient on user-specified sets of columns in a single table. This is useful to estimate number of distinct groups in GROUP BY and DISTINCT clauses; estimation errors there can cause over-allocation of memory in hashed aggregates, for instance, so it's a worthwhile problem to solve. A new special pseudo-type pg_ndistinct is used. (num-distinct estimation was deemed sufficiently useful by itself that this is worthwhile even if no further statistic types are added immediately; so much so that another version of essentially the same functionality was submitted by Kyotaro Horiguchi: https://postgr.es/m/20150828.173334.114731693.horiguchi.kyotaro@lab.ntt.co.jp though this commit does not use that code.) Author: Tomas Vondra. Some code rework by Álvaro. Reviewed-by: Dean Rasheed, David Rowley, Kyotaro Horiguchi, Jeff Janes, Ideriha Takeshi Discussion: https://postgr.es/m/543AFA15.4080608@fuzzy.cz https://postgr.es/m/20170320190220.ixlaueanxegqd5gr@alvherre.pgsql
2017-03-24 18:06:10 +01:00
depends on the column, for example, foreign key references or views.
Add ALTER TABLE ... ALTER COLUMN ... SET STATISTICS DISTINCT Robert Haas
2009-08-03 00:14:53 +02:00
If <literal>IF EXISTS</literal> is specified and the column
does not exist, no error is thrown. In this case a notice
DROP IF EXISTS for columns and constraints. Andres Freund.
2009-07-20 04:42:28 +02:00
is issued instead.
ALTER TABLE DROP COLUMN works. Patch by Christopher Kings-Lynne, code review by Tom Lane. Remaining issues: functions that take or return tuple types are likely to break if one drops (or adds!) a column in the table defining the type. Need to think about what to do here. Along the way: some code review for recent COPY changes; mark system columns attnotnull = true where appropriate, per discussion a month ago.
2002-08-02 20:15:10 +02:00
</para>
</listitem>
</varlistentry>
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
<varlistentry>
Allow SQL:2008 syntax ALTER TABLE ... ALTER COLUMN ... SET DATA TYPE alongside our traditional syntax.
2008-10-21 10:38:16 +02:00
<term><literal>SET DATA TYPE</literal></term>
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
<listitem>
<para>
This form changes the type of a column of a table. Indexes and
simple table constraints involving the column will be automatically
converted to use the new column type by reparsing the originally
Remove collation information from TypeName, where it does not belong. The initial collations patch treated a COLLATE spec as part of a TypeName, following what can only be described as brain fade on the part of the SQL committee. It's a lot more reasonable to treat COLLATE as a syntactically separate object, so that it can be added in only the productions where it actually belongs, rather than needing to reject it in a boatload of places where it doesn't belong (something the original patch mostly failed to do). In addition this change lets us meet the spec's requirement to allow COLLATE anywhere in the clauses of a ColumnDef, and it avoids unfriendly behavior for constructs such as "foo::type COLLATE collation". To do this, pull collation information out of TypeName and put it in ColumnDef instead, thus reverting most of the collation-related changes in parse_type.c's API. I made one additional structural change, which was to use a ColumnDef as an intermediate node in AT_AlterColumnType AlterTableCmd nodes. This provides enough room to get rid of the "transform" wart in AlterTableCmd too, since the ColumnDef can carry the USING expression easily enough. Also fix some other minor bugs that have crept in in the same areas, like failure to copy recently-added fields of ColumnDef in copyfuncs.c. While at it, document the formerly secret ability to specify a collation in ALTER TABLE ALTER COLUMN TYPE, ALTER TYPE ADD ATTRIBUTE, and ALTER TYPE ALTER ATTRIBUTE TYPE; and correct some misstatements about what the default collation selection will be when COLLATE is omitted. BTW, the three-parameter form of format_type() should go away too, since it just contributes to the confusion in this area; but I'll do that in a separate patch.
2011-03-10 04:38:52 +01:00
supplied expression.
The optional <literal>COLLATE</literal> clause specifies a collation
for the new column; if omitted, the collation is the default for the
new column type.
The optional <literal>USING</literal>
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
clause specifies how to compute the new column value from the old;
if omitted, the default conversion is the same as an assignment
cast from old data type to new. A <literal>USING</literal>
clause must be provided if there is no implicit or assignment
cast from old to new type.
</para>
</listitem>
</varlistentry>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
<varlistentry>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<term><literal>SET</literal>/<literal>DROP DEFAULT</literal></term>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
<listitem>
<para>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
These forms set or remove the default value for a column.
Support automatically-updatable views. This patch makes "simple" views automatically updatable, without the need to create either INSTEAD OF triggers or INSTEAD rules. "Simple" views are those classified as updatable according to SQL-92 rules. The rewriter transforms INSERT/UPDATE/DELETE commands on such views directly into an equivalent command on the underlying table, which will generally have noticeably better performance than is possible with either triggers or user-written rules. A view that has INSTEAD OF triggers or INSTEAD rules continues to operate the same as before. For the moment, security_barrier views are not considered simple. Also, we do not support WITH CHECK OPTION. These features may be added in future. Dean Rasheed, reviewed by Amit Kapila
2012-12-09 00:25:48 +01:00
Default values only apply in subsequent <command>INSERT</command>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
or <command>UPDATE</command> commands; they do not cause rows already in the
Support automatically-updatable views. This patch makes "simple" views automatically updatable, without the need to create either INSTEAD OF triggers or INSTEAD rules. "Simple" views are those classified as updatable according to SQL-92 rules. The rewriter transforms INSERT/UPDATE/DELETE commands on such views directly into an equivalent command on the underlying table, which will generally have noticeably better performance than is possible with either triggers or user-written rules. A view that has INSTEAD OF triggers or INSTEAD rules continues to operate the same as before. For the moment, security_barrier views are not considered simple. Also, we do not support WITH CHECK OPTION. These features may be added in future. Dean Rasheed, reviewed by Amit Kapila
2012-12-09 00:25:48 +01:00
table to change.
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
</para>
</listitem>
</varlistentry>
<varlistentry>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<term><literal>SET</literal>/<literal>DROP NOT NULL</literal></term>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
<listitem>
<para>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
These forms change whether a column is marked to allow null
values or to reject null values. You can only use <literal>SET
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
NOT NULL</literal> when the column contains no null values.
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
</para>
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
<para>
Improve documentation of how NOT NULL works with partitioning. Amit Langote Discussion: http://postgr.es/m/a6f99cdb-21e7-1d65-1381-91f2cfa156e2@lab.ntt.co.jp
2017-03-27 17:01:33 +02:00
If this table is a partition, one cannot perform <literal>DROP NOT NULL</literal>
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
on a column if it is marked <literal>NOT NULL</literal> in the parent
Improve documentation of how NOT NULL works with partitioning. Amit Langote Discussion: http://postgr.es/m/a6f99cdb-21e7-1d65-1381-91f2cfa156e2@lab.ntt.co.jp
2017-03-27 17:01:33 +02:00
table. To drop the <literal>NOT NULL</literal> constraint from all the
partitions, perform <literal>DROP NOT NULL</literal> on the parent
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
table. Even if there is no <literal>NOT NULL</literal> constraint on the
Improve documentation of how NOT NULL works with partitioning. Amit Langote Discussion: http://postgr.es/m/a6f99cdb-21e7-1d65-1381-91f2cfa156e2@lab.ntt.co.jp
2017-03-27 17:01:33 +02:00
parent, such a constraint can still be added to individual partitions,
if desired; that is, the children can disallow nulls even if the parent
Trim trailing whitespace
2017-06-12 15:51:18 +02:00
allows them, but not the other way around.
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
</para>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
</listitem>
</varlistentry>
Identity columns This is the SQL standard-conforming variant of PostgreSQL's serial columns. It fixes a few usability issues that serial columns have: - CREATE TABLE / LIKE copies default but refers to same sequence - cannot add/drop serialness with ALTER TABLE - dropping default does not drop sequence - need to grant separate privileges to sequence - other slight weirdnesses because serial is some kind of special macro Reviewed-by: Vitaly Burovoy <vitaly.burovoy@gmail.com>
2017-04-06 14:33:16 +02:00
<varlistentry>
<term><literal>ADD GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY</literal></term>
<term><literal>SET GENERATED { ALWAYS | BY DEFAULT }</literal></term>
<term><literal>DROP IDENTITY [ IF EXISTS ]</literal></term>
<listitem>
<para>
These forms change whether a column is an identity column or change the
generation attribute of an existing identity column.
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
See <xref linkend="sql-createtable"/> for details.
Identity columns This is the SQL standard-conforming variant of PostgreSQL's serial columns. It fixes a few usability issues that serial columns have: - CREATE TABLE / LIKE copies default but refers to same sequence - cannot add/drop serialness with ALTER TABLE - dropping default does not drop sequence - need to grant separate privileges to sequence - other slight weirdnesses because serial is some kind of special macro Reviewed-by: Vitaly Burovoy <vitaly.burovoy@gmail.com>
2017-04-06 14:33:16 +02:00
</para>
<para>
If <literal>DROP IDENTITY IF EXISTS</literal> is specified and the
column is not an identity column, no error is thrown. In this case a
notice is issued instead.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SET <replaceable>sequence_option</replaceable></literal></term>
<term><literal>RESTART</literal></term>
<listitem>
<para>
These forms alter the sequence that underlies an existing identity
column. <replaceable>sequence_option</replaceable> is an option
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
supported by <xref linkend="sql-altersequence"/> such
Identity columns This is the SQL standard-conforming variant of PostgreSQL's serial columns. It fixes a few usability issues that serial columns have: - CREATE TABLE / LIKE copies default but refers to same sequence - cannot add/drop serialness with ALTER TABLE - dropping default does not drop sequence - need to grant separate privileges to sequence - other slight weirdnesses because serial is some kind of special macro Reviewed-by: Vitaly Burovoy <vitaly.burovoy@gmail.com>
2017-04-06 14:33:16 +02:00
as <literal>INCREMENT BY</literal>.
</para>
</listitem>
</varlistentry>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
<varlistentry>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<term><literal>SET STATISTICS</literal></term>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
<listitem>
<para>
This form
sets the per-column statistics-gathering target for subsequent
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="sql-analyze"/> operations.
Increase the default value of default_statistics_target from 10 to 100, and its maximum value from 1000 to 10000. ALTER TABLE SET STATISTICS similarly now allows a value up to 10000. Per discussion.
2008-12-13 20:13:44 +01:00
The target can be set in the range 0 to 10000; alternatively, set it
Add a few more xrefs, where they seemed appropriate: for example, refer to the discussion of planner statistics in the documentation for the default_statistics_target GUC var.
2004-03-01 18:58:39 +01:00
to -1 to revert to using the system default statistics
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
target (<xref linkend="guc-default-statistics-target"/>).
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
For more information on the use of statistics by the
Add a few more xrefs, where they seemed appropriate: for example, refer to the discussion of planner statistics in the documentation for the default_statistics_target GUC var.
2004-03-01 18:58:39 +01:00
<productname>PostgreSQL</productname> query planner, refer to
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="planner-stats"/>.
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
</para>
Reduce lock levels of some ALTER TABLE cmds VALIDATE CONSTRAINT CLUSTER ON SET WITHOUT CLUSTER ALTER COLUMN SET STATISTICS ALTER COLUMN SET () ALTER COLUMN RESET () All other sub-commands use AccessExclusiveLock Simon Riggs and Noah Misch Reviews by Robert Haas and Andres Freund
2014-04-06 17:13:43 +02:00
<para>
docs: Add missing <literal> markup. Michael Paquier
2015-01-14 22:40:58 +01:00
<literal>SET STATISTICS</literal> acquires a
<literal>SHARE UPDATE EXCLUSIVE</literal> lock.
Reduce lock levels of some ALTER TABLE cmds VALIDATE CONSTRAINT CLUSTER ON SET WITHOUT CLUSTER ALTER COLUMN SET STATISTICS ALTER COLUMN SET () ALTER COLUMN RESET () All other sub-commands use AccessExclusiveLock Simon Riggs and Noah Misch Reviews by Robert Haas and Andres Freund
2014-04-06 17:13:43 +02:00
</para>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
</listitem>
</varlistentry>
Add ALTER TABLE ... ALTER COLUMN ... SET STATISTICS DISTINCT Robert Haas
2009-08-03 00:14:53 +02:00
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><literal>SET ( <replaceable class="parameter">attribute_option</replaceable> = <replaceable class="parameter">value</replaceable> [, ... ] )</literal></term>
<term><literal>RESET ( <replaceable class="parameter">attribute_option</replaceable> [, ... ] )</literal></term>
Add ALTER TABLE ... ALTER COLUMN ... SET STATISTICS DISTINCT Robert Haas
2009-08-03 00:14:53 +02:00
<listitem>
<para>
Stamp 9.0 release notes with expected release date; also some last-minute copy-editing.
2010-09-16 20:15:21 +02:00
This form sets or resets per-attribute options. Currently, the only
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
defined per-attribute options are <literal>n_distinct</literal> and
<literal>n_distinct_inherited</literal>, which override the
Stamp 9.0 release notes with expected release date; also some last-minute copy-editing.
2010-09-16 20:15:21 +02:00
number-of-distinct-values estimates made by subsequent
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="sql-analyze"/>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
operations. <literal>n_distinct</literal> affects the statistics for the table
itself, while <literal>n_distinct_inherited</literal> affects the statistics
Stamp 9.0 release notes with expected release date; also some last-minute copy-editing.
2010-09-16 20:15:21 +02:00
gathered for the table plus its inheritance children. When set to a
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
positive value, <command>ANALYZE</command> will assume that the column contains
Replace ALTER TABLE ... SET STATISTICS DISTINCT with a more general mechanism. Attributes can now have options, just as relations and tablespaces do, and the reloptions code is used to parse, validate, and store them. For simplicity and because these options are not performance critical, we store them in a separate cache rather than the main relcache. Thanks to Alex Hunsaker for the review.
2010-01-22 17:40:19 +01:00
exactly the specified number of distinct nonnull values. When set to a
negative value, which must be greater
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
than or equal to -1, <command>ANALYZE</command> will assume that the number of
Add ALTER TABLE ... ALTER COLUMN ... SET STATISTICS DISTINCT Robert Haas
2009-08-03 00:14:53 +02:00
distinct nonnull values in the column is linear in the size of the
table; the exact count is to be computed by multiplying the estimated
table size by the absolute value of the given number. For example,
a value of -1 implies that all values in the column are distinct, while
a value of -0.5 implies that each value appears twice on the average.
This can be useful when the size of the table changes over time, since
the multiplication by the number of rows in the table is not performed
until query planning time. Specify a value of 0 to revert to estimating
the number of distinct values normally. For more information on the use
of statistics by the <productname>PostgreSQL</productname> query
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
planner, refer to <xref linkend="planner-stats"/>.
Add ALTER TABLE ... ALTER COLUMN ... SET STATISTICS DISTINCT Robert Haas
2009-08-03 00:14:53 +02:00
</para>
Reduce lock levels of some ALTER TABLE cmds VALIDATE CONSTRAINT CLUSTER ON SET WITHOUT CLUSTER ALTER COLUMN SET STATISTICS ALTER COLUMN SET () ALTER COLUMN RESET () All other sub-commands use AccessExclusiveLock Simon Riggs and Noah Misch Reviews by Robert Haas and Andres Freund
2014-04-06 17:13:43 +02:00
<para>
Changing per-attribute options acquires a
<literal>SHARE UPDATE EXCLUSIVE</literal> lock.
</para>
Add ALTER TABLE ... ALTER COLUMN ... SET STATISTICS DISTINCT Robert Haas
2009-08-03 00:14:53 +02:00
</listitem>
</varlistentry>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
<varlistentry>
doc: Fix DocBook XML validity The main problem is that DocBook SGML allows indexterm elements just about everywhere, but DocBook XML is stricter. For example, this common pattern <varlistentry> <indexterm>...</indexterm> <term>...</term> ... </varlistentry> needs to be changed to something like <varlistentry> <term>...<indexterm>...</indexterm></term> ... </varlistentry> See also bb4eefe7bf518e42c73797ea37b033a5d8a8e70a. There is currently nothing in the build system that enforces that things stay valid, because that requires additional tools and will receive separate consideration.
2014-05-07 03:28:58 +02:00
<term>
<literal>SET STORAGE</literal>
<indexterm>
<primary>TOAST</primary>
<secondary>per-column storage settings</secondary>
</indexterm>
</term>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
<listitem>
<para>
This form sets the storage mode for a column. This controls whether this
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
column is held inline or in a secondary <acronym>TOAST</acronym> table, and
Use "TOAST table" in place of the vague, not-used-elsewhere phrase "supplementary storage table".
2010-05-13 20:54:18 +02:00
whether the data
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
should be compressed or not. <literal>PLAIN</literal> must be used
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
for fixed-length values such as <type>integer</type> and is
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
inline, uncompressed. <literal>MAIN</literal> is for inline,
compressible data. <literal>EXTERNAL</literal> is for external,
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
uncompressed data, and <literal>EXTENDED</literal> is for external,
Add some real documentation about TOAST (finally). Combine this with the old 'page' chapter and the recently added 'filelayout' chapter to make a coherent chapter about PostgreSQL's physical storage layout.
2005-01-10 01:04:43 +01:00
compressed data. <literal>EXTENDED</literal> is the default for most
data types that support non-<literal>PLAIN</literal> storage.
Use "TOAST table" in place of the vague, not-used-elsewhere phrase "supplementary storage table".
2010-05-13 20:54:18 +02:00
Use of <literal>EXTERNAL</literal> will make substring operations on
very large <type>text</type> and <type>bytea</type> values run faster,
at the penalty of increased storage space. Note that
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>SET STORAGE</literal> doesn't itself change anything in the table,
Add some real documentation about TOAST (finally). Combine this with the old 'page' chapter and the recently added 'filelayout' chapter to make a coherent chapter about PostgreSQL's physical storage layout.
2005-01-10 01:04:43 +01:00
it just sets the strategy to be pursued during future table updates.
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
See <xref linkend="storage-toast"/> for more information.
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
</para>
</listitem>
</varlistentry>
Code for WITHOUT OIDS. On Wed, 2003-01-08 at 21:59, Christopher Kings-Lynne wrote: > I agree. I want to remove OIDs from heaps of our tables when we go to 7.3. > I'd rather not have to do it in the dump due to down time. Rod Taylor <rbt@rbt.ca>
2003-02-13 06:20:05 +01:00
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><literal>ADD <replaceable class="parameter">table_constraint</replaceable> [ NOT VALID ]</literal></term>
Code for WITHOUT OIDS. On Wed, 2003-01-08 at 21:59, Christopher Kings-Lynne wrote: > I agree. I want to remove OIDs from heaps of our tables when we go to 7.3. > I'd rather not have to do it in the dump due to down time. Rod Taylor <rbt@rbt.ca>
2003-02-13 06:20:05 +01:00
<listitem>
<para>
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
This form adds a new constraint to a table using the same syntax as
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="sql-createtable"/>, plus the option <literal>NOT
Rework parsing of ConstraintAttributeSpec to improve NOT VALID handling. The initial commit of the ALTER TABLE ADD FOREIGN KEY NOT VALID feature failed to support labeling such constraints as deferrable. The best fix for this seems to be to fold NOT VALID into ConstraintAttributeSpec. That's a bit more general than the documented syntax, but it allows better-targeted syntax error messages. In addition, do some mostly-but-not-entirely-cosmetic code review for the whole NOT VALID patch.
2011-06-16 01:05:11 +02:00
VALID</literal>, which is currently only allowed for foreign key
Enable CHECK constraints to be declared NOT VALID This means that they can initially be added to a large existing table without checking its initial contents, but new tuples must comply to them; a separate pass invoked by ALTER TABLE / VALIDATE can verify existing data and ensure it complies with the constraint, at which point it is marked validated and becomes a normal part of the table ecosystem. An non-validated CHECK constraint is ignored in the planner for constraint_exclusion purposes; when validated, cached plans are recomputed so that partitioning starts working right away. This patch also enables domains to have unvalidated CHECK constraints attached to them as well by way of ALTER DOMAIN / ADD CONSTRAINT / NOT VALID, which can later be validated with ALTER DOMAIN / VALIDATE CONSTRAINT. Thanks to Thom Brown, Dean Rasheed and Jaime Casanova for the various reviews, and Robert Hass for documentation wording improvement suggestions. This patch was sponsored by Enova Financial.
2011-06-02 00:43:50 +02:00
and CHECK constraints.
Rework parsing of ConstraintAttributeSpec to improve NOT VALID handling. The initial commit of the ALTER TABLE ADD FOREIGN KEY NOT VALID feature failed to support labeling such constraints as deferrable. The best fix for this seems to be to fold NOT VALID into ConstraintAttributeSpec. That's a bit more general than the documented syntax, but it allows better-targeted syntax error messages. In addition, do some mostly-but-not-entirely-cosmetic code review for the whole NOT VALID patch.
2011-06-16 01:05:11 +02:00
If the constraint is marked <literal>NOT VALID</literal>, the
potentially-lengthy initial check to verify that all rows in the table
satisfy the constraint is skipped. The constraint will still be
enforced against subsequent inserts or updates (that is, they'll fail
Enable CHECK constraints to be declared NOT VALID This means that they can initially be added to a large existing table without checking its initial contents, but new tuples must comply to them; a separate pass invoked by ALTER TABLE / VALIDATE can verify existing data and ensure it complies with the constraint, at which point it is marked validated and becomes a normal part of the table ecosystem. An non-validated CHECK constraint is ignored in the planner for constraint_exclusion purposes; when validated, cached plans are recomputed so that partitioning starts working right away. This patch also enables domains to have unvalidated CHECK constraints attached to them as well by way of ALTER DOMAIN / ADD CONSTRAINT / NOT VALID, which can later be validated with ALTER DOMAIN / VALIDATE CONSTRAINT. Thanks to Thom Brown, Dean Rasheed and Jaime Casanova for the various reviews, and Robert Hass for documentation wording improvement suggestions. This patch was sponsored by Enova Financial.
2011-06-02 00:43:50 +02:00
unless there is a matching row in the referenced table, in the case
of foreign keys; and they'll fail unless the new row matches the
specified check constraints). But the
Rework parsing of ConstraintAttributeSpec to improve NOT VALID handling. The initial commit of the ALTER TABLE ADD FOREIGN KEY NOT VALID feature failed to support labeling such constraints as deferrable. The best fix for this seems to be to fold NOT VALID into ConstraintAttributeSpec. That's a bit more general than the documented syntax, but it allows better-targeted syntax error messages. In addition, do some mostly-but-not-entirely-cosmetic code review for the whole NOT VALID patch.
2011-06-16 01:05:11 +02:00
database will not assume that the constraint holds for all rows in
the table, until it is validated by using the <literal>VALIDATE
Foreign keys on partitioned tables Author: Álvaro Herrera Discussion: https://postgr.es/m/20171231194359.cvojcour423ulha4@alvherre.pgsql Reviewed-by: Peter Eisentraut
2018-04-04 19:02:31 +02:00
CONSTRAINT</literal> option. Foreign key constraints on partitioned
tables may not be declared <literal>NOT VALID</literal> at present.
This patch adds a new GUC var, "default_with_oids", which follows the proposal for eventually deprecating OIDs on user tables that I posted earlier to pgsql-hackers. pg_dump now always specifies WITH OIDS or WITHOUT OIDS when dumping a table. The documentation has been updated. Neil Conway
2003-12-01 23:08:02 +01:00
</para>
Adjust ALTER TABLE docs on partitioned constraints Move the "additional restrictions" comment to ALTER TABLE ADD CONSTRAINT instead of ADD CONSTRAINT USING INDEX; and in the latter instead indicate that partitioned tables are unsupported Noted by David G. Johnston Discussion: https://postgr.es/m/CAKFQuwY4Ld7ecxL_KAmaxwt0FUu5VcPPN2L4dh+3BeYbrdBa5g@mail.gmail.com
2018-02-20 16:08:55 +01:00
<para>
Additional restrictions apply when unique or primary key constraints
are added to partitioned tables; see <xref linkend="sql-createtable" />.
</para>
Code for WITHOUT OIDS. On Wed, 2003-01-08 at 21:59, Christopher Kings-Lynne wrote: > I agree. I want to remove OIDs from heaps of our tables when we go to 7.3. > I'd rather not have to do it in the dump due to down time. Rod Taylor <rbt@rbt.ca>
2003-02-13 06:20:05 +01:00
</listitem>
</varlistentry>
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><literal>ADD <replaceable class="parameter">table_constraint_using_index</replaceable></literal></term>
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
<listitem>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
This form adds a new <literal>PRIMARY KEY</literal> or <literal>UNIQUE</literal>
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
constraint to a table based on an existing unique index. All the
columns of the index will be included in the constraint.
</para>
<para>
The index cannot have expression columns nor be a partial index.
Also, it must be a b-tree index with default sort ordering. These
restrictions ensure that the index is equivalent to one that would be
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
built by a regular <literal>ADD PRIMARY KEY</literal> or <literal>ADD UNIQUE</literal>
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
command.
</para>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
If <literal>PRIMARY KEY</literal> is specified, and the index's columns are not
already marked <literal>NOT NULL</literal>, then this command will attempt to
do <literal>ALTER COLUMN SET NOT NULL</literal> against each such column.
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
That requires a full table scan to verify the column(s) contain no
nulls. In all other cases, this is a fast operation.
</para>
<para>
If a constraint name is provided then the index will be renamed to match
the constraint name. Otherwise the constraint will be named the same as
the index.
</para>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
After this command is executed, the index is <quote>owned</quote> by the
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
constraint, in the same way as if the index had been built by
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
a regular <literal>ADD PRIMARY KEY</literal> or <literal>ADD UNIQUE</literal>
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
command. In particular, dropping the constraint will make the index
disappear too.
</para>
Allow UNIQUE indexes on partitioned tables If we restrict unique constraints on partitioned tables so that they must always include the partition key, then our standard approach to unique indexes already works --- each unique key is forced to exist within a single partition, so enforcing the unique restriction in each index individually is enough to have it enforced globally. Therefore we can implement unique indexes on partitions by simply removing a few restrictions (and adding others.) Discussion: https://postgr.es/m/20171222212921.hi6hg6pem2w2t36z@alvherre.pgsql Discussion: https://postgr.es/m/20171229230607.3iib6b62fn3uaf47@alvherre.pgsql Reviewed-by: Simon Riggs, Jesper Pedersen, Peter Eisentraut, Jaime Casanova, Amit Langote
2018-02-19 20:59:37 +01:00
<para>
Adjust ALTER TABLE docs on partitioned constraints Move the "additional restrictions" comment to ALTER TABLE ADD CONSTRAINT instead of ADD CONSTRAINT USING INDEX; and in the latter instead indicate that partitioned tables are unsupported Noted by David G. Johnston Discussion: https://postgr.es/m/CAKFQuwY4Ld7ecxL_KAmaxwt0FUu5VcPPN2L4dh+3BeYbrdBa5g@mail.gmail.com
2018-02-20 16:08:55 +01:00
This form is not currently supported on partitioned tables.
Allow UNIQUE indexes on partitioned tables If we restrict unique constraints on partitioned tables so that they must always include the partition key, then our standard approach to unique indexes already works --- each unique key is forced to exist within a single partition, so enforcing the unique restriction in each index individually is enough to have it enforced globally. Therefore we can implement unique indexes on partitions by simply removing a few restrictions (and adding others.) Discussion: https://postgr.es/m/20171222212921.hi6hg6pem2w2t36z@alvherre.pgsql Discussion: https://postgr.es/m/20171229230607.3iib6b62fn3uaf47@alvherre.pgsql Reviewed-by: Simon Riggs, Jesper Pedersen, Peter Eisentraut, Jaime Casanova, Amit Langote
2018-02-19 20:59:37 +01:00
</para>
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
<note>
<para>
Adding a constraint using an existing index can be helpful in
situations where a new constraint needs to be added without blocking
table updates for a long time. To do that, create the index using
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<command>CREATE INDEX CONCURRENTLY</command>, and then install it as an
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
official constraint using this syntax. See the example below.
</para>
</note>
</listitem>
</varlistentry>
ALTER TABLE ... ALTER CONSTRAINT for FKs Allow constraint attributes to be altered, so the default setting of NOT DEFERRABLE can be altered to DEFERRABLE and back. Review by Abhijit Menon-Sen
2013-06-29 01:27:30 +02:00
<varlistentry>
<term><literal>ALTER CONSTRAINT</literal></term>
<listitem>
<para>
This form alters the attributes of a constraint that was previously
created. Currently only foreign key constraints may be altered.
</para>
</listitem>
</varlistentry>
Rework parsing of ConstraintAttributeSpec to improve NOT VALID handling. The initial commit of the ALTER TABLE ADD FOREIGN KEY NOT VALID feature failed to support labeling such constraints as deferrable. The best fix for this seems to be to fold NOT VALID into ConstraintAttributeSpec. That's a bit more general than the documented syntax, but it allows better-targeted syntax error messages. In addition, do some mostly-but-not-entirely-cosmetic code review for the whole NOT VALID patch.
2011-06-16 01:05:11 +02:00
<varlistentry>
<term><literal>VALIDATE CONSTRAINT</literal></term>
<listitem>
<para>
Enable CHECK constraints to be declared NOT VALID This means that they can initially be added to a large existing table without checking its initial contents, but new tuples must comply to them; a separate pass invoked by ALTER TABLE / VALIDATE can verify existing data and ensure it complies with the constraint, at which point it is marked validated and becomes a normal part of the table ecosystem. An non-validated CHECK constraint is ignored in the planner for constraint_exclusion purposes; when validated, cached plans are recomputed so that partitioning starts working right away. This patch also enables domains to have unvalidated CHECK constraints attached to them as well by way of ALTER DOMAIN / ADD CONSTRAINT / NOT VALID, which can later be validated with ALTER DOMAIN / VALIDATE CONSTRAINT. Thanks to Thom Brown, Dean Rasheed and Jaime Casanova for the various reviews, and Robert Hass for documentation wording improvement suggestions. This patch was sponsored by Enova Financial.
2011-06-02 00:43:50 +02:00
This form validates a foreign key or check constraint that was previously created
Rework parsing of ConstraintAttributeSpec to improve NOT VALID handling. The initial commit of the ALTER TABLE ADD FOREIGN KEY NOT VALID feature failed to support labeling such constraints as deferrable. The best fix for this seems to be to fold NOT VALID into ConstraintAttributeSpec. That's a bit more general than the documented syntax, but it allows better-targeted syntax error messages. In addition, do some mostly-but-not-entirely-cosmetic code review for the whole NOT VALID patch.
2011-06-16 01:05:11 +02:00
as <literal>NOT VALID</literal>, by scanning the table to ensure there
Enable CHECK constraints to be declared NOT VALID This means that they can initially be added to a large existing table without checking its initial contents, but new tuples must comply to them; a separate pass invoked by ALTER TABLE / VALIDATE can verify existing data and ensure it complies with the constraint, at which point it is marked validated and becomes a normal part of the table ecosystem. An non-validated CHECK constraint is ignored in the planner for constraint_exclusion purposes; when validated, cached plans are recomputed so that partitioning starts working right away. This patch also enables domains to have unvalidated CHECK constraints attached to them as well by way of ALTER DOMAIN / ADD CONSTRAINT / NOT VALID, which can later be validated with ALTER DOMAIN / VALIDATE CONSTRAINT. Thanks to Thom Brown, Dean Rasheed and Jaime Casanova for the various reviews, and Robert Hass for documentation wording improvement suggestions. This patch was sponsored by Enova Financial.
2011-06-02 00:43:50 +02:00
are no rows for which the constraint is not satisfied.
Nothing happens if the constraint is already marked valid.
Fix docs on lock level for ALTER TABLE VALIDATE ALTER TABLE .. VALIDATE CONSTRAINT previously gave incorrect details about lock levels and therefore incomplete reasons to use the option. Initial bug report and fix from Marko Tiikkaja Reworded by me to include comments by Kevin Grittner
2013-06-18 13:09:39 +02:00
</para>
<para>
Reduce lock levels of some ALTER TABLE cmds VALIDATE CONSTRAINT CLUSTER ON SET WITHOUT CLUSTER ALTER COLUMN SET STATISTICS ALTER COLUMN SET () ALTER COLUMN RESET () All other sub-commands use AccessExclusiveLock Simon Riggs and Noah Misch Reviews by Robert Haas and Andres Freund
2014-04-06 17:13:43 +02:00
Validation can be a long process on larger tables. The value of separating
Fix docs on lock level for ALTER TABLE VALIDATE ALTER TABLE .. VALIDATE CONSTRAINT previously gave incorrect details about lock levels and therefore incomplete reasons to use the option. Initial bug report and fix from Marko Tiikkaja Reworded by me to include comments by Kevin Grittner
2013-06-18 13:09:39 +02:00
validation from initial creation is that you can defer validation to less
busy times, or can be used to give additional time to correct pre-existing
Reduce lock levels of some ALTER TABLE cmds VALIDATE CONSTRAINT CLUSTER ON SET WITHOUT CLUSTER ALTER COLUMN SET STATISTICS ALTER COLUMN SET () ALTER COLUMN RESET () All other sub-commands use AccessExclusiveLock Simon Riggs and Noah Misch Reviews by Robert Haas and Andres Freund
2014-04-06 17:13:43 +02:00
errors while preventing new errors. Note also that validation on its own
does not prevent normal write commands against the table while it runs.
</para>
<para>
Validation acquires only a <literal>SHARE UPDATE EXCLUSIVE</literal> lock
on the table being altered. If the constraint is a foreign key then
a <literal>ROW SHARE</literal> lock is also required on
the table referenced by the constraint.
Rework parsing of ConstraintAttributeSpec to improve NOT VALID handling. The initial commit of the ALTER TABLE ADD FOREIGN KEY NOT VALID feature failed to support labeling such constraints as deferrable. The best fix for this seems to be to fold NOT VALID into ConstraintAttributeSpec. That's a bit more general than the documented syntax, but it allows better-targeted syntax error messages. In addition, do some mostly-but-not-entirely-cosmetic code review for the whole NOT VALID patch.
2011-06-16 01:05:11 +02:00
</para>
</listitem>
</varlistentry>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
<varlistentry>
DROP IF EXISTS for columns and constraints. Andres Freund.
2009-07-20 04:42:28 +02:00
<term><literal>DROP CONSTRAINT [ IF EXISTS ]</literal></term>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
<listitem>
<para>
Fully enforce uniqueness of constraint names. It's been true for a long time that we expect names of table and domain constraints to be unique among the constraints of that table or domain. However, the enforcement of that has been pretty haphazard, and it missed some corner cases such as creating a CHECK constraint and then an index constraint of the same name (as per recent report from André Hänsel). Also, due to the lack of an actual unique index enforcing this, duplicates could be created through race conditions. Moreover, the code that searches pg_constraint has been quite inconsistent about how to handle duplicate names if one did occur: some places checked and threw errors if there was more than one match, while others just processed the first match they came to. To fix, create a unique index on (conrelid, contypid, conname). Since either conrelid or contypid is zero, this will separately enforce uniqueness of constraint names among constraints of any one table and any one domain. (If we ever implement SQL assertions, and put them into this catalog, more thought might be needed. But it'd be at least as reasonable to put them into a new catalog; having overloaded this one catalog with two kinds of constraints was a mistake already IMO.) This index can replace the existing non-unique index on conrelid, though we need to keep the one on contypid for query performance reasons. Having done that, we can simplify the logic in various places that either coped with duplicates or neglected to, as well as potentially improve lookup performance when searching for a constraint by name. Also, as per our usual practice, install a preliminary check so that you get something more friendly than a unique-index violation report in the case complained of by André. And teach ChooseIndexName to avoid choosing autogenerated names that would draw such a failure. While it's not possible to make such a change in the back branches, it doesn't seem quite too late to put this into v11, so do so. Discussion: https://postgr.es/m/0c1001d4428f$0942b430$1bc81c90$@webkr.de
2018-09-04 19:45:35 +02:00
This form drops the specified constraint on a table, along with
any index underlying the constraint.
DROP IF EXISTS for columns and constraints. Andres Freund.
2009-07-20 04:42:28 +02:00
If <literal>IF EXISTS</literal> is specified and the constraint
does not exist, no error is thrown. In this case a notice is issued instead.
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
</para>
</listitem>
</varlistentry>
Add documentation for ALTER TABLE ENABLE/DISABLE TRIGGER.
2005-08-24 19:24:19 +02:00
<varlistentry>
Changes pg_trigger and extend pg_rewrite in order to allow triggers and rules to be defined with different, per session controllable, behaviors for replication purposes. This will allow replication systems like Slony-I and, as has been stated on pgsql-hackers, other products to control the firing mechanism of triggers and rewrite rules without modifying the system catalog directly. The firing mechanisms are controlled by a new superuser-only GUC variable, session_replication_role, together with a change to pg_trigger.tgenabled and a new column pg_rewrite.ev_enabled. Both columns are a single char data type now (tgenabled was a bool before). The possible values in these attributes are: 'O' - Trigger/Rule fires when session_replication_role is "origin" (default) or "local". This is the default behavior. 'D' - Trigger/Rule is disabled and fires never 'A' - Trigger/Rule fires always regardless of the setting of session_replication_role 'R' - Trigger/Rule fires when session_replication_role is "replica" The GUC variable can only be changed as long as the system does not have any cached query plans. This will prevent changing the session role and accidentally executing stored procedures or functions that have plans cached that expand to the wrong query set due to differences in the rule firing semantics. The SQL syntax for changing a triggers/rules firing semantics is ALTER TABLE <tabname> <when> TRIGGER|RULE <name>; <when> ::= ENABLE | ENABLE ALWAYS | ENABLE REPLICA | DISABLE psql's \d command as well as pg_dump are extended in a backward compatible fashion. Jan
2007-03-20 00:38:32 +01:00
<term><literal>DISABLE</literal>/<literal>ENABLE [ REPLICA | ALWAYS ] TRIGGER</literal></term>
Add documentation for ALTER TABLE ENABLE/DISABLE TRIGGER.
2005-08-24 19:24:19 +02:00
<listitem>
<para>
Changes pg_trigger and extend pg_rewrite in order to allow triggers and rules to be defined with different, per session controllable, behaviors for replication purposes. This will allow replication systems like Slony-I and, as has been stated on pgsql-hackers, other products to control the firing mechanism of triggers and rewrite rules without modifying the system catalog directly. The firing mechanisms are controlled by a new superuser-only GUC variable, session_replication_role, together with a change to pg_trigger.tgenabled and a new column pg_rewrite.ev_enabled. Both columns are a single char data type now (tgenabled was a bool before). The possible values in these attributes are: 'O' - Trigger/Rule fires when session_replication_role is "origin" (default) or "local". This is the default behavior. 'D' - Trigger/Rule is disabled and fires never 'A' - Trigger/Rule fires always regardless of the setting of session_replication_role 'R' - Trigger/Rule fires when session_replication_role is "replica" The GUC variable can only be changed as long as the system does not have any cached query plans. This will prevent changing the session role and accidentally executing stored procedures or functions that have plans cached that expand to the wrong query set due to differences in the rule firing semantics. The SQL syntax for changing a triggers/rules firing semantics is ALTER TABLE <tabname> <when> TRIGGER|RULE <name>; <when> ::= ENABLE | ENABLE ALWAYS | ENABLE REPLICA | DISABLE psql's \d command as well as pg_dump are extended in a backward compatible fashion. Jan
2007-03-20 00:38:32 +01:00
These forms configure the firing of trigger(s) belonging to the table.
Add documentation for ALTER TABLE ENABLE/DISABLE TRIGGER.
2005-08-24 19:24:19 +02:00
A disabled trigger is still known to the system, but is not executed
when its triggering event occurs. For a deferred trigger, the enable
status is checked when the event occurs, not when the trigger function
Update reference documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
is actually executed. One can disable or enable a single
Add documentation for ALTER TABLE ENABLE/DISABLE TRIGGER.
2005-08-24 19:24:19 +02:00
trigger specified by name, or all triggers on the table, or only
Update ALTER TABLE docs to account for exclusion and deferrable uniqueness constraints Dean Rasheed
2010-06-09 19:48:10 +02:00
user triggers (this option excludes internally generated constraint
triggers such as those that are used to implement foreign key
constraints or deferrable uniqueness and exclusion constraints).
Disabling or enabling internally generated constraint triggers
Add documentation for ALTER TABLE ENABLE/DISABLE TRIGGER.
2005-08-24 19:24:19 +02:00
requires superuser privileges; it should be done with caution since
of course the integrity of the constraint cannot be guaranteed if the
triggers are not executed.
doc: Expand documentation of session_replication_role
2018-01-18 15:34:51 +01:00
</para>
<para>
Remove tabs from SGML file.
2007-03-22 16:45:56 +01:00
The trigger firing mechanism is also affected by the configuration
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
variable <xref linkend="guc-session-replication-role"/>. Simply enabled
doc: Expand documentation of session_replication_role
2018-01-18 15:34:51 +01:00
triggers (the default) will fire when the replication role is <quote>origin</quote>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
(the default) or <quote>local</quote>. Triggers configured as <literal>ENABLE
REPLICA</literal> will only fire if the session is in <quote>replica</quote>
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
mode, and triggers configured as <literal>ENABLE ALWAYS</literal> will
doc: Expand documentation of session_replication_role
2018-01-18 15:34:51 +01:00
fire regardless of the current replication role.
</para>
<para>
The effect of this mechanism is that in the default configuration,
triggers do not fire on replicas. This is useful because if a trigger
is used on the origin to propagate data between tables, then the
replication system will also replicate the propagated data, and the
trigger should not fire a second time on the replica, because that would
lead to duplication. However, if a trigger is used for another purpose
such as creating external alerts, then it might be appropriate to set it
to <literal>ENABLE ALWAYS</literal> so that it is also fired on
replicas.
Changes pg_trigger and extend pg_rewrite in order to allow triggers and rules to be defined with different, per session controllable, behaviors for replication purposes. This will allow replication systems like Slony-I and, as has been stated on pgsql-hackers, other products to control the firing mechanism of triggers and rewrite rules without modifying the system catalog directly. The firing mechanisms are controlled by a new superuser-only GUC variable, session_replication_role, together with a change to pg_trigger.tgenabled and a new column pg_rewrite.ev_enabled. Both columns are a single char data type now (tgenabled was a bool before). The possible values in these attributes are: 'O' - Trigger/Rule fires when session_replication_role is "origin" (default) or "local". This is the default behavior. 'D' - Trigger/Rule is disabled and fires never 'A' - Trigger/Rule fires always regardless of the setting of session_replication_role 'R' - Trigger/Rule fires when session_replication_role is "replica" The GUC variable can only be changed as long as the system does not have any cached query plans. This will prevent changing the session role and accidentally executing stored procedures or functions that have plans cached that expand to the wrong query set due to differences in the rule firing semantics. The SQL syntax for changing a triggers/rules firing semantics is ALTER TABLE <tabname> <when> TRIGGER|RULE <name>; <when> ::= ENABLE | ENABLE ALWAYS | ENABLE REPLICA | DISABLE psql's \d command as well as pg_dump are extended in a backward compatible fashion. Jan
2007-03-20 00:38:32 +01:00
</para>
doc: Expand documentation of session_replication_role
2018-01-18 15:34:51 +01:00
Reduce lock levels of some trigger DDL and add FKs Reduce lock levels to ShareRowExclusive for the following SQL CREATE TRIGGER (but not DROP or ALTER) ALTER TABLE ENABLE TRIGGER ALTER TABLE DISABLE TRIGGER ALTER TABLE … ADD CONSTRAINT FOREIGN KEY Original work by Simon Riggs, extracted and refreshed by Andreas Karlsson New test cases added by Andreas Karlsson Reviewed by Noah Misch, Andres Freund, Michael Paquier and Simon Riggs
2015-04-05 17:37:08 +02:00
<para>
This command acquires a <literal>SHARE ROW EXCLUSIVE</literal> lock.
</para>
Changes pg_trigger and extend pg_rewrite in order to allow triggers and rules to be defined with different, per session controllable, behaviors for replication purposes. This will allow replication systems like Slony-I and, as has been stated on pgsql-hackers, other products to control the firing mechanism of triggers and rewrite rules without modifying the system catalog directly. The firing mechanisms are controlled by a new superuser-only GUC variable, session_replication_role, together with a change to pg_trigger.tgenabled and a new column pg_rewrite.ev_enabled. Both columns are a single char data type now (tgenabled was a bool before). The possible values in these attributes are: 'O' - Trigger/Rule fires when session_replication_role is "origin" (default) or "local". This is the default behavior. 'D' - Trigger/Rule is disabled and fires never 'A' - Trigger/Rule fires always regardless of the setting of session_replication_role 'R' - Trigger/Rule fires when session_replication_role is "replica" The GUC variable can only be changed as long as the system does not have any cached query plans. This will prevent changing the session role and accidentally executing stored procedures or functions that have plans cached that expand to the wrong query set due to differences in the rule firing semantics. The SQL syntax for changing a triggers/rules firing semantics is ALTER TABLE <tabname> <when> TRIGGER|RULE <name>; <when> ::= ENABLE | ENABLE ALWAYS | ENABLE REPLICA | DISABLE psql's \d command as well as pg_dump are extended in a backward compatible fashion. Jan
2007-03-20 00:38:32 +01:00
</listitem>
</varlistentry>
<varlistentry>
<term><literal>DISABLE</literal>/<literal>ENABLE [ REPLICA | ALWAYS ] RULE</literal></term>
<listitem>
<para>
These forms configure the firing of rewrite rules belonging to the table.
A disabled rule is still known to the system, but is not applied
Remove tabs from SGML file.
2007-03-22 16:45:56 +01:00
during query rewriting. The semantics are as for disabled/enabled
Tweaks for SGML markup.
2007-05-18 01:36:04 +02:00
triggers. This configuration is ignored for <literal>ON SELECT</literal> rules, which
Remove tabs from SGML file.
2007-03-22 16:45:56 +01:00
are always applied in order to keep views working even if the current
session is in a non-default replication role.
Add documentation for ALTER TABLE ENABLE/DISABLE TRIGGER.
2005-08-24 19:24:19 +02:00
</para>
doc: Expand documentation of session_replication_role
2018-01-18 15:34:51 +01:00
<para>
The rule firing mechanism is also affected by the configuration variable
<xref linkend="guc-session-replication-role"/>, analogous to triggers as
described above.
</para>
Add documentation for ALTER TABLE ENABLE/DISABLE TRIGGER.
2005-08-24 19:24:19 +02:00
</listitem>
</varlistentry>
Row-Level Security Policies (RLS) Building on the updatable security-barrier views work, add the ability to define policies on tables to limit the set of rows which are returned from a query and which are allowed to be added to a table. Expressions defined by the policy for filtering are added to the security barrier quals of the query, while expressions defined to check records being added to a table are added to the with-check options of the query. New top-level commands are CREATE/ALTER/DROP POLICY and are controlled by the table owner. Row Security is able to be enabled and disabled by the owner on a per-table basis using ALTER TABLE .. ENABLE/DISABLE ROW SECURITY. Per discussion, ROW SECURITY is disabled on tables by default and must be enabled for policies on the table to be used. If no policies exist on a table with ROW SECURITY enabled, a default-deny policy is used and no records will be visible. By default, row security is applied at all times except for the table owner and the superuser. A new GUC, row_security, is added which can be set to ON, OFF, or FORCE. When set to FORCE, row security will be applied even for the table owner and superusers. When set to OFF, row security will be disabled when allowed and an error will be thrown if the user does not have rights to bypass row security. Per discussion, pg_dump sets row_security = OFF by default to ensure that exports and backups will have all data in the table or will error if there are insufficient privileges to bypass row security. A new option has been added to pg_dump, --enable-row-security, to ask pg_dump to export with row security enabled. A new role capability, BYPASSRLS, which can only be set by the superuser, is added to allow other users to be able to bypass row security using row_security = OFF. Many thanks to the various individuals who have helped with the design, particularly Robert Haas for his feedback. Authors include Craig Ringer, KaiGai Kohei, Adam Brightwell, Dean Rasheed, with additional changes and rework by me. Reviewers have included all of the above, Greg Smith, Jeff McCormick, and Robert Haas.
2014-09-19 17:18:35 +02:00
<varlistentry>
<term><literal>DISABLE</literal>/<literal>ENABLE ROW LEVEL SECURITY</literal></term>
<listitem>
<para>
These forms control the application of row security policies belonging
to the table. If enabled and no policies exist for the table, then a
default-deny policy is applied. Note that policies can exist for a table
Code review for row security. Buildfarm member tick identified an issue where the policies in the relcache for a relation were were being replaced underneath a running query, leading to segfaults while processing the policies to be added to a query. Similar to how TupleDesc RuleLocks are handled, add in a equalRSDesc() function to check if the policies have actually changed and, if not, swap back the rsdesc field (using the original instead of the temporairly built one; the whole structure is swapped and then specific fields swapped back). This now passes a CLOBBER_CACHE_ALWAYS for me and should resolve the buildfarm error. In addition to addressing this, add a new chapter in Data Definition under Privileges which explains row security and provides examples of its usage, change \d to always list policies (even if row security is disabled- but note that it is disabled, or enabled with no policies), rework check_role_for_policy (it really didn't need the entire policy, but it did need to be using has_privs_of_role()), and change the field in pg_class to relrowsecurity from relhasrowsecurity, based on Heikki's suggestion. Also from Heikki, only issue SET ROW_SECURITY in pg_restore when talking to a 9.5+ server, list Bypass RLS in \du, and document --enable-row-security options for pg_dump and pg_restore. Lastly, fix a number of minor whitespace and typo issues from Heikki, Dimitri, add a missing #include, per Peter E, fix a few minor variable-assigned-but-not-used and resource leak issues from Coverity and add tab completion for role attribute bypassrls as well.
2014-09-24 22:32:22 +02:00
even if row level security is disabled - in this case, the policies will
Row-Level Security Policies (RLS) Building on the updatable security-barrier views work, add the ability to define policies on tables to limit the set of rows which are returned from a query and which are allowed to be added to a table. Expressions defined by the policy for filtering are added to the security barrier quals of the query, while expressions defined to check records being added to a table are added to the with-check options of the query. New top-level commands are CREATE/ALTER/DROP POLICY and are controlled by the table owner. Row Security is able to be enabled and disabled by the owner on a per-table basis using ALTER TABLE .. ENABLE/DISABLE ROW SECURITY. Per discussion, ROW SECURITY is disabled on tables by default and must be enabled for policies on the table to be used. If no policies exist on a table with ROW SECURITY enabled, a default-deny policy is used and no records will be visible. By default, row security is applied at all times except for the table owner and the superuser. A new GUC, row_security, is added which can be set to ON, OFF, or FORCE. When set to FORCE, row security will be applied even for the table owner and superusers. When set to OFF, row security will be disabled when allowed and an error will be thrown if the user does not have rights to bypass row security. Per discussion, pg_dump sets row_security = OFF by default to ensure that exports and backups will have all data in the table or will error if there are insufficient privileges to bypass row security. A new option has been added to pg_dump, --enable-row-security, to ask pg_dump to export with row security enabled. A new role capability, BYPASSRLS, which can only be set by the superuser, is added to allow other users to be able to bypass row security using row_security = OFF. Many thanks to the various individuals who have helped with the design, particularly Robert Haas for his feedback. Authors include Craig Ringer, KaiGai Kohei, Adam Brightwell, Dean Rasheed, with additional changes and rework by me. Reviewers have included all of the above, Greg Smith, Jeff McCormick, and Robert Haas.
2014-09-19 17:18:35 +02:00
NOT be applied and the policies will be ignored.
See also
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="sql-createpolicy"/>.
Row-Level Security Policies (RLS) Building on the updatable security-barrier views work, add the ability to define policies on tables to limit the set of rows which are returned from a query and which are allowed to be added to a table. Expressions defined by the policy for filtering are added to the security barrier quals of the query, while expressions defined to check records being added to a table are added to the with-check options of the query. New top-level commands are CREATE/ALTER/DROP POLICY and are controlled by the table owner. Row Security is able to be enabled and disabled by the owner on a per-table basis using ALTER TABLE .. ENABLE/DISABLE ROW SECURITY. Per discussion, ROW SECURITY is disabled on tables by default and must be enabled for policies on the table to be used. If no policies exist on a table with ROW SECURITY enabled, a default-deny policy is used and no records will be visible. By default, row security is applied at all times except for the table owner and the superuser. A new GUC, row_security, is added which can be set to ON, OFF, or FORCE. When set to FORCE, row security will be applied even for the table owner and superusers. When set to OFF, row security will be disabled when allowed and an error will be thrown if the user does not have rights to bypass row security. Per discussion, pg_dump sets row_security = OFF by default to ensure that exports and backups will have all data in the table or will error if there are insufficient privileges to bypass row security. A new option has been added to pg_dump, --enable-row-security, to ask pg_dump to export with row security enabled. A new role capability, BYPASSRLS, which can only be set by the superuser, is added to allow other users to be able to bypass row security using row_security = OFF. Many thanks to the various individuals who have helped with the design, particularly Robert Haas for his feedback. Authors include Craig Ringer, KaiGai Kohei, Adam Brightwell, Dean Rasheed, with additional changes and rework by me. Reviewers have included all of the above, Greg Smith, Jeff McCormick, and Robert Haas.
2014-09-19 17:18:35 +02:00
</para>
</listitem>
</varlistentry>
ALTER TABLE .. FORCE ROW LEVEL SECURITY To allow users to force RLS to always be applied, even for table owners, add ALTER TABLE .. FORCE ROW LEVEL SECURITY. row_security=off overrides FORCE ROW LEVEL SECURITY, to ensure pg_dump output is complete (by default). Also add SECURITY_NOFORCE_RLS context to avoid data corruption when ALTER TABLE .. FORCE ROW SECURITY is being used. The SECURITY_NOFORCE_RLS security context is used only during referential integrity checks and is only considered in check_enable_rls() after we have already checked that the current user is the owner of the relation (which should always be the case during referential integrity checks). Back-patch to 9.5 where RLS was added.
2015-10-05 03:05:08 +02:00
<varlistentry>
<term><literal>NO FORCE</literal>/<literal>FORCE ROW LEVEL SECURITY</literal></term>
<listitem>
<para>
These forms control the application of row security policies belonging
to the table when the user is the table owner. If enabled, row level
security policies will be applied when the user is the table owner. If
disabled (the default) then row level security will not be applied when
the user is the table owner.
See also
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="sql-createpolicy"/>.
ALTER TABLE .. FORCE ROW LEVEL SECURITY To allow users to force RLS to always be applied, even for table owners, add ALTER TABLE .. FORCE ROW LEVEL SECURITY. row_security=off overrides FORCE ROW LEVEL SECURITY, to ensure pg_dump output is complete (by default). Also add SECURITY_NOFORCE_RLS context to avoid data corruption when ALTER TABLE .. FORCE ROW SECURITY is being used. The SECURITY_NOFORCE_RLS security context is used only during referential integrity checks and is only considered in check_enable_rls() after we have already checked that the current user is the owner of the relation (which should always be the case during referential integrity checks). Back-patch to 9.5 where RLS was added.
2015-10-05 03:05:08 +02:00
</para>
</listitem>
</varlistentry>
ALTER TABLE SET TABLESPACE. Gavin Sherry, some rework by Tom Lane.
2004-07-12 01:13:58 +02:00
<varlistentry>
Adjust documentation of ALTER TABLE CLUSTER ON for more consistency. Josh Kupershmidt
2012-05-21 18:06:56 +02:00
<term><literal>CLUSTER ON</literal></term>
ALTER TABLE SET TABLESPACE. Gavin Sherry, some rework by Tom Lane.
2004-07-12 01:13:58 +02:00
<listitem>
<para>
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
This form selects the default index for future
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="sql-cluster"/>
ALTER TABLE SET TABLESPACE. Gavin Sherry, some rework by Tom Lane.
2004-07-12 01:13:58 +02:00
operations. It does not actually re-cluster the table.
</para>
Reduce lock levels of some ALTER TABLE cmds VALIDATE CONSTRAINT CLUSTER ON SET WITHOUT CLUSTER ALTER COLUMN SET STATISTICS ALTER COLUMN SET () ALTER COLUMN RESET () All other sub-commands use AccessExclusiveLock Simon Riggs and Noah Misch Reviews by Robert Haas and Andres Freund
2014-04-06 17:13:43 +02:00
<para>
Changing cluster options acquires a <literal>SHARE UPDATE EXCLUSIVE</literal> lock.
</para>
ALTER TABLE SET TABLESPACE. Gavin Sherry, some rework by Tom Lane.
2004-07-12 01:13:58 +02:00
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SET WITHOUT CLUSTER</literal></term>
<listitem>
<para>
This form removes the most recently used
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="sql-cluster"/>
ALTER TABLE SET TABLESPACE. Gavin Sherry, some rework by Tom Lane.
2004-07-12 01:13:58 +02:00
index specification from the table. This affects
future cluster operations that don't specify an index.
</para>
Reduce lock levels of some ALTER TABLE cmds VALIDATE CONSTRAINT CLUSTER ON SET WITHOUT CLUSTER ALTER COLUMN SET STATISTICS ALTER COLUMN SET () ALTER COLUMN RESET () All other sub-commands use AccessExclusiveLock Simon Riggs and Noah Misch Reviews by Robert Haas and Andres Freund
2014-04-06 17:13:43 +02:00
<para>
Changing cluster options acquires a <literal>SHARE UPDATE EXCLUSIVE</literal> lock.
</para>
ALTER TABLE SET TABLESPACE. Gavin Sherry, some rework by Tom Lane.
2004-07-12 01:13:58 +02:00
</listitem>
</varlistentry>
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
<varlistentry>
<term><literal>SET WITH OIDS</literal></term>
<listitem>
<para>
This form adds an <literal>oid</literal> system column to the
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
table (see <xref linkend="ddl-system-columns"/>).
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
It does nothing if the table already has OIDs.
</para>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
Note that this is not equivalent to <literal>ADD COLUMN oid oid</literal>;
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
that would add a normal column that happened to be named
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>oid</literal>, not a system column.
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
</para>
</listitem>
</varlistentry>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
<varlistentry>
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
<term><literal>SET WITHOUT OIDS</literal></term>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
<listitem>
<para>
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
This form removes the <literal>oid</literal> system column from the
table. This is exactly equivalent to
<literal>DROP COLUMN oid RESTRICT</literal>,
except that it will not complain if there is already no
<literal>oid</literal> column.
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
</para>
</listitem>
</varlistentry>
Implement ALTER TABLE .. SET LOGGED / UNLOGGED This enables changing permanent (logged) tables to unlogged and vice-versa. (Docs for ALTER TABLE / SET TABLESPACE got shuffled in an order that hopefully makes more sense than the original.) Author: Fabrízio de Royes Mello Reviewed by: Christoph Berg, Andres Freund, Thom Brown Some tweaking by Álvaro Herrera
2014-08-22 20:27:00 +02:00
<varlistentry>
<term><literal>SET TABLESPACE</literal></term>
<listitem>
<para>
This form changes the table's tablespace to the specified tablespace and
moves the data file(s) associated with the table to the new tablespace.
Indexes on the table, if any, are not moved; but they can be moved
separately with additional <literal>SET TABLESPACE</literal> commands.
All tables in the current database in a tablespace can be moved by using
the <literal>ALL IN TABLESPACE</literal> form, which will lock all tables
to be moved first and then move each one. This form also supports
<literal>OWNED BY</literal>, which will only move tables owned by the
roles specified. If the <literal>NOWAIT</literal> option is specified
then the command will fail if it is unable to acquire all of the locks
required immediately. Note that system catalogs are not moved by this
command, use <command>ALTER DATABASE</command> or explicit
<command>ALTER TABLE</command> invocations instead if desired. The
<literal>information_schema</literal> relations are not considered part
of the system catalogs and will be moved.
See also
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="sql-createtablespace"/>.
Implement ALTER TABLE .. SET LOGGED / UNLOGGED This enables changing permanent (logged) tables to unlogged and vice-versa. (Docs for ALTER TABLE / SET TABLESPACE got shuffled in an order that hopefully makes more sense than the original.) Author: Fabrízio de Royes Mello Reviewed by: Christoph Berg, Andres Freund, Thom Brown Some tweaking by Álvaro Herrera
2014-08-22 20:27:00 +02:00
</para>
</listitem>
</varlistentry>
<varlistentry>
Minor enhancement of readability of ALTER TABLE syntax in the doc. Fabrízio Mello
2015-05-22 14:42:15 +02:00
<term><literal>SET { LOGGED | UNLOGGED }</literal></term>
Implement ALTER TABLE .. SET LOGGED / UNLOGGED This enables changing permanent (logged) tables to unlogged and vice-versa. (Docs for ALTER TABLE / SET TABLESPACE got shuffled in an order that hopefully makes more sense than the original.) Author: Fabrízio de Royes Mello Reviewed by: Christoph Berg, Andres Freund, Thom Brown Some tweaking by Álvaro Herrera
2014-08-22 20:27:00 +02:00
<listitem>
<para>
This form changes the table from unlogged to logged or vice-versa
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
(see <xref linkend="sql-createtable-unlogged"/>). It cannot be applied
Implement ALTER TABLE .. SET LOGGED / UNLOGGED This enables changing permanent (logged) tables to unlogged and vice-versa. (Docs for ALTER TABLE / SET TABLESPACE got shuffled in an order that hopefully makes more sense than the original.) Author: Fabrízio de Royes Mello Reviewed by: Christoph Berg, Andres Freund, Thom Brown Some tweaking by Álvaro Herrera
2014-08-22 20:27:00 +02:00
to a temporary table.
</para>
</listitem>
</varlistentry>
ALTER TABLE ... ADD/DROPS INHERIT (actually INHERIT / NO INHERIT) Open items: There were a few tangentially related issues that have come up that I think are TODOs. I'm likely to tackle one or two of these next so I'm interested in hearing feedback on them as well. . Constraints currently do not know anything about inheritance. Tom suggested adding a coninhcount and conislocal like attributes have to track their inheritance status. . Foreign key constraints currently do not get copied to new children (and therefore my code doesn't verify them). I don't think it would be hard to add them and treat them like CHECK constraints. . No constraints at all are copied to tables defined with LIKE. That makes it hard to use LIKE to define new partitions. The standard defines LIKE and specifically says it does not copy constraints. But the standard already has an option called INCLUDING DEFAULTS; we could always define a non-standard extension LIKE table INCLUDING CONSTRAINTS that gives the user the option to request a copy including constraints. . Personally, I think the whole attislocal thing is bunk. The decision about whether to drop a column from children tables or not is something that should be up to the user and trying to DWIM based on whether there was ever a local definition or the column was acquired purely through inheritance is hardly ever going to match up with user expectations. . And of course there's the whole unique and primary key constraint issue. I think to get any traction at all on this you have a prerequisite of a real partitioned table implementation where the system knows what the partition key is so it can recognize when it's a leading part of an index key. Greg Stark
2006-07-02 03:58:36 +02:00
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><literal>SET ( <replaceable class="parameter">storage_parameter</replaceable> = <replaceable class="parameter">value</replaceable> [, ... ] )</literal></term>
ALTER TABLE ... ADD/DROPS INHERIT (actually INHERIT / NO INHERIT) Open items: There were a few tangentially related issues that have come up that I think are TODOs. I'm likely to tackle one or two of these next so I'm interested in hearing feedback on them as well. . Constraints currently do not know anything about inheritance. Tom suggested adding a coninhcount and conislocal like attributes have to track their inheritance status. . Foreign key constraints currently do not get copied to new children (and therefore my code doesn't verify them). I don't think it would be hard to add them and treat them like CHECK constraints. . No constraints at all are copied to tables defined with LIKE. That makes it hard to use LIKE to define new partitions. The standard defines LIKE and specifically says it does not copy constraints. But the standard already has an option called INCLUDING DEFAULTS; we could always define a non-standard extension LIKE table INCLUDING CONSTRAINTS that gives the user the option to request a copy including constraints. . Personally, I think the whole attislocal thing is bunk. The decision about whether to drop a column from children tables or not is something that should be up to the user and trying to DWIM based on whether there was ever a local definition or the column was acquired purely through inheritance is hardly ever going to match up with user expectations. . And of course there's the whole unique and primary key constraint issue. I think to get any traction at all on this you have a prerequisite of a real partitioned table implementation where the system knows what the partition key is so it can recognize when it's a leading part of an index key. Greg Stark
2006-07-02 03:58:36 +02:00
<listitem>
<para>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
This form changes one or more storage parameters for the table. See
Convert SGML IDs to lower case IDs in SGML are case insensitive, and we have accumulated a mix of upper and lower case IDs, including different variants of the same ID. In XML, these will be case sensitive, so we need to fix up those differences. Going to all lower case seems most straightforward, and the current build process already makes all anchors and lower case anyway during the SGML->XML conversion, so this doesn't create any difference in the output right now. A future XML-only build process would, however, maintain any mixed case ID spellings in the output, so that is another reason to clean this up beforehand. Author: Alexander Lakhin <exclusion@gmail.com>
2017-10-20 03:16:39 +02:00
<xref linkend="sql-createtable-storage-parameters"
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
endterm="sql-createtable-storage-parameters-title"/>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
for details on the available parameters. Note that the table contents
will not be modified immediately by this command; depending on the
Update reference documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
parameter you might need to rewrite the table to get the desired effects.
Convert SGML IDs to lower case IDs in SGML are case insensitive, and we have accumulated a mix of upper and lower case IDs, including different variants of the same ID. In XML, these will be case sensitive, so we need to fix up those differences. Going to all lower case seems most straightforward, and the current build process already makes all anchors and lower case anyway during the SGML->XML conversion, so this doesn't create any difference in the output right now. A future XML-only build process would, however, maintain any mixed case ID spellings in the output, so that is another reason to clean this up beforehand. Author: Alexander Lakhin <exclusion@gmail.com>
2017-10-20 03:16:39 +02:00
That can be done with <link linkend="sql-vacuum">VACUUM
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
FULL</link>, <xref linkend="sql-cluster"/> or one of the forms
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
of <command>ALTER TABLE</command> that forces a table rewrite.
Enhance docs for ALTER TABLE lock levels of storage parms As requested by Robert Haas
2017-03-06 12:18:12 +01:00
For planner related parameters, changes will take effect from the next
time the table is locked so currently executing queries will not be
affected.
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
</para>
Reduce lock levels for ALTER TABLE SET autovacuum storage options Reduce lock levels down to ShareUpdateExclusiveLock for all autovacuum-related relation options when setting them using ALTER TABLE. Add infrastructure to allow varying lock levels for relation options in later patches. Setting multiple options together uses the highest lock level required for any option. Works for both main and toast tables. Fabrízio Mello, reviewed by Michael Paquier, mild edit and additional regression tests from myself
2015-08-14 15:19:28 +02:00
<para>
Trim trailing whitespace
2017-06-12 15:51:18 +02:00
<literal>SHARE UPDATE EXCLUSIVE</literal> lock will be taken for
Parameter toast_tuple_target controls TOAST for new rows Specifies the point at which we try to move long column values into TOAST tables. No effect on existing rows. Discussion: https://postgr.es/m/CANP8+jKsVmw6CX6YP9z7zqkTzcKV1+Uzr3XjKcZW=2Ya00OyQQ@mail.gmail.com Author: Simon Riggs <simon@2ndQudrant.com> Reviewed-by: Andrew Dunstan <andrew.dunstan@2ndQuadrant.com>
2017-11-19 23:50:10 +01:00
fillfactor, toast and autovacuum storage parameters, as well as the
Enhance docs for ALTER TABLE lock levels of storage parms As requested by Robert Haas
2017-03-06 12:18:12 +01:00
following planner related parameters:
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<varname>effective_io_concurrency</varname>, <varname>parallel_workers</varname>, <varname>seq_page_cost</varname>,
<varname>random_page_cost</varname>, <varname>n_distinct</varname> and <varname>n_distinct_inherited</varname>.
Reduce lock levels for ALTER TABLE SET autovacuum storage options Reduce lock levels down to ShareUpdateExclusiveLock for all autovacuum-related relation options when setting them using ALTER TABLE. Add infrastructure to allow varying lock levels for relation options in later patches. Setting multiple options together uses the highest lock level required for any option. Works for both main and toast tables. Fabrízio Mello, reviewed by Michael Paquier, mild edit and additional regression tests from myself
2015-08-14 15:19:28 +02:00
</para>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
<note>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
While <command>CREATE TABLE</command> allows <literal>OIDS</literal> to be specified
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
in the <literal>WITH (<replaceable
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
class="parameter">storage_parameter</replaceable>)</literal> syntax,
<command>ALTER TABLE</command> does not treat <literal>OIDS</literal> as a
storage parameter. Instead use the <literal>SET WITH OIDS</literal>
and <literal>SET WITHOUT OIDS</literal> forms to change OID status.
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
</para>
</note>
</listitem>
</varlistentry>
ALTER TABLE ... ADD/DROPS INHERIT (actually INHERIT / NO INHERIT) Open items: There were a few tangentially related issues that have come up that I think are TODOs. I'm likely to tackle one or two of these next so I'm interested in hearing feedback on them as well. . Constraints currently do not know anything about inheritance. Tom suggested adding a coninhcount and conislocal like attributes have to track their inheritance status. . Foreign key constraints currently do not get copied to new children (and therefore my code doesn't verify them). I don't think it would be hard to add them and treat them like CHECK constraints. . No constraints at all are copied to tables defined with LIKE. That makes it hard to use LIKE to define new partitions. The standard defines LIKE and specifically says it does not copy constraints. But the standard already has an option called INCLUDING DEFAULTS; we could always define a non-standard extension LIKE table INCLUDING CONSTRAINTS that gives the user the option to request a copy including constraints. . Personally, I think the whole attislocal thing is bunk. The decision about whether to drop a column from children tables or not is something that should be up to the user and trying to DWIM based on whether there was ever a local definition or the column was acquired purely through inheritance is hardly ever going to match up with user expectations. . And of course there's the whole unique and primary key constraint issue. I think to get any traction at all on this you have a prerequisite of a real partitioned table implementation where the system knows what the partition key is so it can recognize when it's a leading part of an index key. Greg Stark
2006-07-02 03:58:36 +02:00
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><literal>RESET ( <replaceable class="parameter">storage_parameter</replaceable> [, ... ] )</literal></term>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
<listitem>
<para>
This form resets one or more storage parameters to their
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
defaults. As with <literal>SET</literal>, a table rewrite might be
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
needed to update the table entirely.
</para>
</listitem>
</varlistentry>
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><literal>INHERIT <replaceable class="parameter">parent_table</replaceable></literal></term>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
<listitem>
<para>
Code and docs review for ALTER TABLE INHERIT/NO INHERIT patch.
2006-10-13 23:43:19 +02:00
This form adds the target table as a new child of the specified parent
table. Subsequently, queries against the parent will include records
of the target table. To be added as a child, the target table must
already contain all the same columns as the parent (it could have
additional columns, too). The columns must have matching data types,
ALTER TABLE ... ADD/DROPS INHERIT (actually INHERIT / NO INHERIT) Open items: There were a few tangentially related issues that have come up that I think are TODOs. I'm likely to tackle one or two of these next so I'm interested in hearing feedback on them as well. . Constraints currently do not know anything about inheritance. Tom suggested adding a coninhcount and conislocal like attributes have to track their inheritance status. . Foreign key constraints currently do not get copied to new children (and therefore my code doesn't verify them). I don't think it would be hard to add them and treat them like CHECK constraints. . No constraints at all are copied to tables defined with LIKE. That makes it hard to use LIKE to define new partitions. The standard defines LIKE and specifically says it does not copy constraints. But the standard already has an option called INCLUDING DEFAULTS; we could always define a non-standard extension LIKE table INCLUDING CONSTRAINTS that gives the user the option to request a copy including constraints. . Personally, I think the whole attislocal thing is bunk. The decision about whether to drop a column from children tables or not is something that should be up to the user and trying to DWIM based on whether there was ever a local definition or the column was acquired purely through inheritance is hardly ever going to match up with user expectations. . And of course there's the whole unique and primary key constraint issue. I think to get any traction at all on this you have a prerequisite of a real partitioned table implementation where the system knows what the partition key is so it can recognize when it's a leading part of an index key. Greg Stark
2006-07-02 03:58:36 +02:00
and if they have <literal>NOT NULL</literal> constraints in the parent
then they must also have <literal>NOT NULL</literal> constraints in the
child.
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
</para>
ALTER TABLE ... ADD/DROPS INHERIT (actually INHERIT / NO INHERIT) Open items: There were a few tangentially related issues that have come up that I think are TODOs. I'm likely to tackle one or two of these next so I'm interested in hearing feedback on them as well. . Constraints currently do not know anything about inheritance. Tom suggested adding a coninhcount and conislocal like attributes have to track their inheritance status. . Foreign key constraints currently do not get copied to new children (and therefore my code doesn't verify them). I don't think it would be hard to add them and treat them like CHECK constraints. . No constraints at all are copied to tables defined with LIKE. That makes it hard to use LIKE to define new partitions. The standard defines LIKE and specifically says it does not copy constraints. But the standard already has an option called INCLUDING DEFAULTS; we could always define a non-standard extension LIKE table INCLUDING CONSTRAINTS that gives the user the option to request a copy including constraints. . Personally, I think the whole attislocal thing is bunk. The decision about whether to drop a column from children tables or not is something that should be up to the user and trying to DWIM based on whether there was ever a local definition or the column was acquired purely through inheritance is hardly ever going to match up with user expectations. . And of course there's the whole unique and primary key constraint issue. I think to get any traction at all on this you have a prerequisite of a real partitioned table implementation where the system knows what the partition key is so it can recognize when it's a leading part of an index key. Greg Stark
2006-07-02 03:58:36 +02:00
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
<para>
Code and docs review for ALTER TABLE INHERIT/NO INHERIT patch.
2006-10-13 23:43:19 +02:00
There must also be matching child-table constraints for all
Disallow merging ONLY constraints in children tables When creating a child table, or when attaching an existing table as child of another, we must not allow inheritable constraints to be merged with non-inheritable ones, because then grandchildren would not properly get the constraint. This would violate the grandparent's expectations. Bugs noted by Robert Haas. Author: Nikhil Sontakke
2012-01-16 23:19:42 +01:00
<literal>CHECK</literal> constraints of the parent, except those
Change syntax of new CHECK NO INHERIT constraints The initially implemented syntax, "CHECK NO INHERIT (expr)" was not deemed very good, so switch to "CHECK (expr) NO INHERIT" instead. This way it looks similar to SQL-standards compliant constraint attribute. Backport to 9.2 where the new syntax and feature was introduced. Per discussion.
2012-07-24 21:49:54 +02:00
marked non-inheritable (that is, created with <literal>ALTER TABLE ... ADD CONSTRAINT ... NO INHERIT</literal>)
Disallow merging ONLY constraints in children tables When creating a child table, or when attaching an existing table as child of another, we must not allow inheritable constraints to be merged with non-inheritable ones, because then grandchildren would not properly get the constraint. This would violate the grandparent's expectations. Bugs noted by Robert Haas. Author: Nikhil Sontakke
2012-01-16 23:19:42 +01:00
in the parent, which are ignored; all child-table constraints matched
must not be marked non-inheritable.
Currently
ALTER TABLE ... ADD/DROPS INHERIT (actually INHERIT / NO INHERIT) Open items: There were a few tangentially related issues that have come up that I think are TODOs. I'm likely to tackle one or two of these next so I'm interested in hearing feedback on them as well. . Constraints currently do not know anything about inheritance. Tom suggested adding a coninhcount and conislocal like attributes have to track their inheritance status. . Foreign key constraints currently do not get copied to new children (and therefore my code doesn't verify them). I don't think it would be hard to add them and treat them like CHECK constraints. . No constraints at all are copied to tables defined with LIKE. That makes it hard to use LIKE to define new partitions. The standard defines LIKE and specifically says it does not copy constraints. But the standard already has an option called INCLUDING DEFAULTS; we could always define a non-standard extension LIKE table INCLUDING CONSTRAINTS that gives the user the option to request a copy including constraints. . Personally, I think the whole attislocal thing is bunk. The decision about whether to drop a column from children tables or not is something that should be up to the user and trying to DWIM based on whether there was ever a local definition or the column was acquired purely through inheritance is hardly ever going to match up with user expectations. . And of course there's the whole unique and primary key constraint issue. I think to get any traction at all on this you have a prerequisite of a real partitioned table implementation where the system knows what the partition key is so it can recognize when it's a leading part of an index key. Greg Stark
2006-07-02 03:58:36 +02:00
<literal>UNIQUE</literal>, <literal>PRIMARY KEY</literal>, and
Code and docs review for ALTER TABLE INHERIT/NO INHERIT patch.
2006-10-13 23:43:19 +02:00
<literal>FOREIGN KEY</literal> constraints are not considered, but
Update reference documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
this might change in the future.
ALTER TABLE ... ADD/DROPS INHERIT (actually INHERIT / NO INHERIT) Open items: There were a few tangentially related issues that have come up that I think are TODOs. I'm likely to tackle one or two of these next so I'm interested in hearing feedback on them as well. . Constraints currently do not know anything about inheritance. Tom suggested adding a coninhcount and conislocal like attributes have to track their inheritance status. . Foreign key constraints currently do not get copied to new children (and therefore my code doesn't verify them). I don't think it would be hard to add them and treat them like CHECK constraints. . No constraints at all are copied to tables defined with LIKE. That makes it hard to use LIKE to define new partitions. The standard defines LIKE and specifically says it does not copy constraints. But the standard already has an option called INCLUDING DEFAULTS; we could always define a non-standard extension LIKE table INCLUDING CONSTRAINTS that gives the user the option to request a copy including constraints. . Personally, I think the whole attislocal thing is bunk. The decision about whether to drop a column from children tables or not is something that should be up to the user and trying to DWIM based on whether there was ever a local definition or the column was acquired purely through inheritance is hardly ever going to match up with user expectations. . And of course there's the whole unique and primary key constraint issue. I think to get any traction at all on this you have a prerequisite of a real partitioned table implementation where the system knows what the partition key is so it can recognize when it's a leading part of an index key. Greg Stark
2006-07-02 03:58:36 +02:00
</para>
</listitem>
</varlistentry>
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><literal>NO INHERIT <replaceable class="parameter">parent_table</replaceable></literal></term>
ALTER TABLE ... ADD/DROPS INHERIT (actually INHERIT / NO INHERIT) Open items: There were a few tangentially related issues that have come up that I think are TODOs. I'm likely to tackle one or two of these next so I'm interested in hearing feedback on them as well. . Constraints currently do not know anything about inheritance. Tom suggested adding a coninhcount and conislocal like attributes have to track their inheritance status. . Foreign key constraints currently do not get copied to new children (and therefore my code doesn't verify them). I don't think it would be hard to add them and treat them like CHECK constraints. . No constraints at all are copied to tables defined with LIKE. That makes it hard to use LIKE to define new partitions. The standard defines LIKE and specifically says it does not copy constraints. But the standard already has an option called INCLUDING DEFAULTS; we could always define a non-standard extension LIKE table INCLUDING CONSTRAINTS that gives the user the option to request a copy including constraints. . Personally, I think the whole attislocal thing is bunk. The decision about whether to drop a column from children tables or not is something that should be up to the user and trying to DWIM based on whether there was ever a local definition or the column was acquired purely through inheritance is hardly ever going to match up with user expectations. . And of course there's the whole unique and primary key constraint issue. I think to get any traction at all on this you have a prerequisite of a real partitioned table implementation where the system knows what the partition key is so it can recognize when it's a leading part of an index key. Greg Stark
2006-07-02 03:58:36 +02:00
<listitem>
<para>
Code and docs review for ALTER TABLE INHERIT/NO INHERIT patch.
2006-10-13 23:43:19 +02:00
This form removes the target table from the list of children of the
specified parent table.
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
Queries against the parent table will no longer include records drawn
from the target table.
ALTER TABLE ... ADD/DROPS INHERIT (actually INHERIT / NO INHERIT) Open items: There were a few tangentially related issues that have come up that I think are TODOs. I'm likely to tackle one or two of these next so I'm interested in hearing feedback on them as well. . Constraints currently do not know anything about inheritance. Tom suggested adding a coninhcount and conislocal like attributes have to track their inheritance status. . Foreign key constraints currently do not get copied to new children (and therefore my code doesn't verify them). I don't think it would be hard to add them and treat them like CHECK constraints. . No constraints at all are copied to tables defined with LIKE. That makes it hard to use LIKE to define new partitions. The standard defines LIKE and specifically says it does not copy constraints. But the standard already has an option called INCLUDING DEFAULTS; we could always define a non-standard extension LIKE table INCLUDING CONSTRAINTS that gives the user the option to request a copy including constraints. . Personally, I think the whole attislocal thing is bunk. The decision about whether to drop a column from children tables or not is something that should be up to the user and trying to DWIM based on whether there was ever a local definition or the column was acquired purely through inheritance is hardly ever going to match up with user expectations. . And of course there's the whole unique and primary key constraint issue. I think to get any traction at all on this you have a prerequisite of a real partitioned table implementation where the system knows what the partition key is so it can recognize when it's a leading part of an index key. Greg Stark
2006-07-02 03:58:36 +02:00
</para>
</listitem>
</varlistentry>
Allow ALTER TABLE name {OF type | NOT OF}. This syntax allows a standalone table to be made into a typed table, or a typed table to be made standalone. This is possibly a mildly useful feature in its own right, but the real motivation for this change is that we need it to make pg_upgrade work with typed tables. This doesn't actually fix that problem, but it's necessary infrastructure. Noah Misch
2011-04-21 03:35:15 +02:00
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><literal>OF <replaceable class="parameter">type_name</replaceable></literal></term>
Allow ALTER TABLE name {OF type | NOT OF}. This syntax allows a standalone table to be made into a typed table, or a typed table to be made standalone. This is possibly a mildly useful feature in its own right, but the real motivation for this change is that we need it to make pg_upgrade work with typed tables. This doesn't actually fix that problem, but it's necessary infrastructure. Noah Misch
2011-04-21 03:35:15 +02:00
<listitem>
<para>
This form links the table to a composite type as though <command>CREATE
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
TABLE OF</command> had formed it. The table's list of column names and types
Allow ALTER TABLE name {OF type | NOT OF}. This syntax allows a standalone table to be made into a typed table, or a typed table to be made standalone. This is possibly a mildly useful feature in its own right, but the real motivation for this change is that we need it to make pg_upgrade work with typed tables. This doesn't actually fix that problem, but it's necessary infrastructure. Noah Misch
2011-04-21 03:35:15 +02:00
must precisely match that of the composite type; the presence of
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
an <literal>oid</literal> system column is permitted to differ. The table must
Allow ALTER TABLE name {OF type | NOT OF}. This syntax allows a standalone table to be made into a typed table, or a typed table to be made standalone. This is possibly a mildly useful feature in its own right, but the real motivation for this change is that we need it to make pg_upgrade work with typed tables. This doesn't actually fix that problem, but it's necessary infrastructure. Noah Misch
2011-04-21 03:35:15 +02:00
not inherit from any other table. These restrictions ensure
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
that <command>CREATE TABLE OF</command> would permit an equivalent table
Allow ALTER TABLE name {OF type | NOT OF}. This syntax allows a standalone table to be made into a typed table, or a typed table to be made standalone. This is possibly a mildly useful feature in its own right, but the real motivation for this change is that we need it to make pg_upgrade work with typed tables. This doesn't actually fix that problem, but it's necessary infrastructure. Noah Misch
2011-04-21 03:35:15 +02:00
definition.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>NOT OF</literal></term>
<listitem>
<para>
This form dissociates a typed table from its type.
</para>
</listitem>
</varlistentry>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
<varlistentry>
Make OWNER TO subcommand mention consistent We say 'OWNER TO' in the synopsis; let's use that form elsewhere. There is a paragraph in the <note> section that refers to various subcommands very loosely (including OWNER); I didn't think it was an improvement to change that one. This is a fairly inconsequential change, so no backpatch. Author: Amit Langote Discussion: https://postgr.es/m/69ec7b51-03e5-f523-95ce-c070ee790e70@lab.ntt.co.jp
2017-10-18 13:29:16 +02:00
<term><literal>OWNER TO</literal></term>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
<listitem>
<para>
Update list of relation types on which ALTER TABLE RENAME/OWNER work. Etsuro Fujita
2014-04-14 16:43:53 +02:00
This form changes the owner of the table, sequence, view, materialized view,
or foreign table to the specified user.
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
</para>
</listitem>
</varlistentry>
Add ALTER TABLE <tablename> CLUSTER ON <indexname> Alvaro Herrera
2003-03-20 19:52:48 +01:00
Convert SGML IDs to lower case IDs in SGML are case insensitive, and we have accumulated a mix of upper and lower case IDs, including different variants of the same ID. In XML, these will be case sensitive, so we need to fix up those differences. Going to all lower case seems most straightforward, and the current build process already makes all anchors and lower case anyway during the SGML->XML conversion, so this doesn't create any difference in the output right now. A future XML-only build process would, however, maintain any mixed case ID spellings in the output, so that is another reason to clean this up beforehand. Author: Alexander Lakhin <exclusion@gmail.com>
2017-10-20 03:16:39 +02:00
<varlistentry id="sql-createtable-replica-identity">
Add the notion of REPLICA IDENTITY for a table. Pending patches for logical replication will use this to determine which columns of a tuple ought to be considered as its candidate key. Andres Freund, with minor, mostly cosmetic adjustments by me
2013-11-08 18:30:43 +01:00
<term><literal>REPLICA IDENTITY</literal></term>
<listitem>
<para>
This form changes the information which is written to the write-ahead log
to identify rows which are updated or deleted. This option has no effect
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
except when logical replication is in use. <literal>DEFAULT</literal>
Improve documentation about MVCC-unsafe utility commands. The table-rewriting forms of ALTER TABLE are MVCC-unsafe, in much the same way as TRUNCATE, because they replace all rows of the table with newly-made rows with a new xmin. (Ideally, concurrent transactions with old snapshots would continue to see the old table contents, but the data is not there anymore --- and if it were there, it would be inconsistent with the table's updated rowtype, so there would be serious implementation problems to fix.) This was nowhere documented though, and the problem was only documented for TRUNCATE in a note in the TRUNCATE reference page. Create a new "Caveats" section in the MVCC chapter that can be home to this and other limitations on serializable consistency. In passing, fix a mistaken statement that VACUUM and CLUSTER would reclaim space occupied by a dropped column. They don't reconstruct existing tuples so they couldn't do that. Back-patch to all supported branches.
2015-08-15 19:30:16 +02:00
(the default for non-system tables) records the
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
old values of the columns of the primary key, if any. <literal>USING INDEX</literal>
Add the notion of REPLICA IDENTITY for a table. Pending patches for logical replication will use this to determine which columns of a tuple ought to be considered as its candidate key. Andres Freund, with minor, mostly cosmetic adjustments by me
2013-11-08 18:30:43 +01:00
records the old values of the columns covered by the named index, which
must be unique, not partial, not deferrable, and include only columns marked
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>NOT NULL</literal>. <literal>FULL</literal> records the old values of all columns
in the row. <literal>NOTHING</literal> records no information about the old row.
psql: conditionally display oids and replication identity In psql \d+, display oids only when they exist, and display replication identity only when it is non-default. Also document the defaults for replication identity for system and non-system tables. Update regression output.
2014-04-15 19:28:54 +02:00
(This is the default for system tables.)
Add the notion of REPLICA IDENTITY for a table. Pending patches for logical replication will use this to determine which columns of a tuple ought to be considered as its candidate key. Andres Freund, with minor, mostly cosmetic adjustments by me
2013-11-08 18:30:43 +01:00
In all cases, no old values are logged unless at least one of the columns
that would be logged differs between the old and new versions of the row.
</para>
</listitem>
</varlistentry>
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
<varlistentry>
<term><literal>RENAME</literal></term>
<listitem>
<para>
The <literal>RENAME</literal> forms change the name of a table
Fully enforce uniqueness of constraint names. It's been true for a long time that we expect names of table and domain constraints to be unique among the constraints of that table or domain. However, the enforcement of that has been pretty haphazard, and it missed some corner cases such as creating a CHECK constraint and then an index constraint of the same name (as per recent report from André Hänsel). Also, due to the lack of an actual unique index enforcing this, duplicates could be created through race conditions. Moreover, the code that searches pg_constraint has been quite inconsistent about how to handle duplicate names if one did occur: some places checked and threw errors if there was more than one match, while others just processed the first match they came to. To fix, create a unique index on (conrelid, contypid, conname). Since either conrelid or contypid is zero, this will separately enforce uniqueness of constraint names among constraints of any one table and any one domain. (If we ever implement SQL assertions, and put them into this catalog, more thought might be needed. But it'd be at least as reasonable to put them into a new catalog; having overloaded this one catalog with two kinds of constraints was a mistake already IMO.) This index can replace the existing non-unique index on conrelid, though we need to keep the one on contypid for query performance reasons. Having done that, we can simplify the logic in various places that either coped with duplicates or neglected to, as well as potentially improve lookup performance when searching for a constraint by name. Also, as per our usual practice, install a preliminary check so that you get something more friendly than a unique-index violation report in the case complained of by André. And teach ChooseIndexName to avoid choosing autogenerated names that would draw such a failure. While it's not possible to make such a change in the back branches, it doesn't seem quite too late to put this into v11, so do so. Discussion: https://postgr.es/m/0c1001d4428f$0942b430$1bc81c90$@webkr.de
2018-09-04 19:45:35 +02:00
(or an index, sequence, view, materialized view, or foreign table), the
name of an individual column in a table, or the name of a constraint of
the table. When renaming a constraint that has an underlying index,
the index is renamed as well.
Update list of relation types on which ALTER TABLE RENAME/OWNER work. Etsuro Fujita
2014-04-14 16:43:53 +02:00
There is no effect on the stored data.
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
</para>
</listitem>
</varlistentry>
Documentation for ALTER object SET SCHEMA commands. Also some minor editorialization.
2005-08-01 18:11:14 +02:00
<varlistentry>
<term><literal>SET SCHEMA</literal></term>
<listitem>
<para>
This form moves the table into another schema. Associated indexes,
Fix all known problems with pg_dump's handling of serial sequences by abandoning the idea that it should say SERIAL in the dump. Instead, dump serial sequences and column defaults just like regular ones. Add a new backend command ALTER SEQUENCE OWNED BY to let pg_dump recreate the sequence-to-column dependency that was formerly created "behind the scenes" by SERIAL. This restores SERIAL to being truly "just a macro" consisting of component operations that can be stated explicitly in SQL. Furthermore, the new command allows sequence ownership to be reassigned, so that old mistakes can be cleaned up. Also, downgrade the OWNED-BY dependency from INTERNAL to AUTO, since there is no longer any very compelling argument why the sequence couldn't be dropped while keeping the column. (This forces initdb, to be sure the right kinds of dependencies are in there.) Along the way, add checks to prevent ALTER OWNER or SET SCHEMA on an owned sequence; you can now only do this indirectly by changing the owning table's owner or schema. This is an oversight in previous releases, but probably not worth back-patching.
2006-08-21 02:57:26 +02:00
constraints, and sequences owned by table columns are moved as well.
Documentation for ALTER object SET SCHEMA commands. Also some minor editorialization.
2005-08-01 18:11:14 +02:00
</para>
</listitem>
</varlistentry>
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><literal>ATTACH PARTITION <replaceable class="parameter">partition_name</replaceable> { FOR VALUES <replaceable class="parameter">partition_bound_spec</replaceable> | DEFAULT }</literal></term>
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
<listitem>
<para>
This form attaches an existing table (which might itself be partitioned)
Allow a partitioned table to have a default partition. Any tuples that don't route to any other partition will route to the default partition. Jeevan Ladhe, Beena Emerson, Ashutosh Bapat, Rahila Syed, and Robert Haas, with review and testing at various stages by (at least) Rushabh Lathia, Keith Fiske, Amit Langote, Amul Sul, Rajkumar Raghuanshi, Sven Kunze, Kyotaro Horiguchi, Thom Brown, Rafia Sabih, and Dilip Kumar. Discussion: http://postgr.es/m/CAH2L28tbN4SYyhS7YV1YBWcitkqbhSWfQCy0G=apRcC_PEO-bg@mail.gmail.com Discussion: http://postgr.es/m/CAOG9ApEYj34fWMcvBMBQ-YtqR9fTdXhdN82QEKG0SVZ6zeL1xg@mail.gmail.com
2017-09-08 23:28:04 +02:00
as a partition of the target table. The table can be attached
Allow UNIQUE indexes on partitioned tables If we restrict unique constraints on partitioned tables so that they must always include the partition key, then our standard approach to unique indexes already works --- each unique key is forced to exist within a single partition, so enforcing the unique restriction in each index individually is enough to have it enforced globally. Therefore we can implement unique indexes on partitions by simply removing a few restrictions (and adding others.) Discussion: https://postgr.es/m/20171222212921.hi6hg6pem2w2t36z@alvherre.pgsql Discussion: https://postgr.es/m/20171229230607.3iib6b62fn3uaf47@alvherre.pgsql Reviewed-by: Simon Riggs, Jesper Pedersen, Peter Eisentraut, Jaime Casanova, Amit Langote
2018-02-19 20:59:37 +01:00
as a partition for specific values using <literal>FOR VALUES</literal>
or as a default partition by using <literal>DEFAULT</literal>.
For each index in the target table, a corresponding
Local partitioned indexes When CREATE INDEX is run on a partitioned table, create catalog entries for an index on the partitioned table (which is just a placeholder since the table proper has no data of its own), and recurse to create actual indexes on the existing partitions; create them in future partitions also. As a convenience gadget, if the new index definition matches some existing index in partitions, these are picked up and used instead of creating new ones. Whichever way these indexes come about, they become attached to the index on the parent table and are dropped alongside it, and cannot be dropped on isolation unless they are detached first. To support pg_dump'ing these indexes, add commands CREATE INDEX ON ONLY <table> (which creates the index on the parent partitioned table, without recursing) and ALTER INDEX ATTACH PARTITION (which is used after the indexes have been created individually on each partition, to attach them to the parent index). These reconstruct prior database state exactly. Reviewed-by: (in alphabetical order) Peter Eisentraut, Robert Haas, Amit Langote, Jesper Pedersen, Simon Riggs, David Rowley Discussion: https://postgr.es/m/20171113170646.gzweigyrgg6pwsg4@alvherre.pgsql
2018-01-19 15:49:22 +01:00
one will be created in the attached table; or, if an equivalent
index already exists, will be attached to the target table's index,
as if <command>ALTER INDEX ATTACH PARTITION</command> had been executed.
Allow a partitioned table to have a default partition. Any tuples that don't route to any other partition will route to the default partition. Jeevan Ladhe, Beena Emerson, Ashutosh Bapat, Rahila Syed, and Robert Haas, with review and testing at various stages by (at least) Rushabh Lathia, Keith Fiske, Amit Langote, Amul Sul, Rajkumar Raghuanshi, Sven Kunze, Kyotaro Horiguchi, Thom Brown, Rafia Sabih, and Dilip Kumar. Discussion: http://postgr.es/m/CAH2L28tbN4SYyhS7YV1YBWcitkqbhSWfQCy0G=apRcC_PEO-bg@mail.gmail.com Discussion: http://postgr.es/m/CAOG9ApEYj34fWMcvBMBQ-YtqR9fTdXhdN82QEKG0SVZ6zeL1xg@mail.gmail.com
2017-09-08 23:28:04 +02:00
</para>
<para>
A partition using <literal>FOR VALUES</literal> uses same syntax for
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<replaceable class="parameter">partition_bound_spec</replaceable> as
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="sql-createtable"/>. The partition bound specification
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
must correspond to the partitioning strategy and partition key of the
target table. The table to be attached must have all the same columns
as the target table and no more; moreover, the column types must also
match. Also, it must have all the <literal>NOT NULL</literal> and
<literal>CHECK</literal> constraints of the target table. Currently
<literal>FOREIGN KEY</literal> constraints are not considered.
Allow UNIQUE indexes on partitioned tables If we restrict unique constraints on partitioned tables so that they must always include the partition key, then our standard approach to unique indexes already works --- each unique key is forced to exist within a single partition, so enforcing the unique restriction in each index individually is enough to have it enforced globally. Therefore we can implement unique indexes on partitions by simply removing a few restrictions (and adding others.) Discussion: https://postgr.es/m/20171222212921.hi6hg6pem2w2t36z@alvherre.pgsql Discussion: https://postgr.es/m/20171229230607.3iib6b62fn3uaf47@alvherre.pgsql Reviewed-by: Simon Riggs, Jesper Pedersen, Peter Eisentraut, Jaime Casanova, Amit Langote
2018-02-19 20:59:37 +01:00
<literal>UNIQUE</literal> and <literal>PRIMARY KEY</literal> constraints
from the parent table will be created in the partition, if they don't
already exist.
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
If any of the <literal>CHECK</literal> constraints of the table being
attached is marked <literal>NO INHERIT</literal>, the command will fail;
such a constraint must be recreated without the <literal>NO INHERIT</literal>
clause.
</para>
<para>
Document lack of validation when attaching foreign partitions. Ashutosh Bapat, revised a bit by me. Discussion: http://postgr.es/m/CAFjFpRdLaCa-1wJase0=YWG5o3cJnbuUt_vrqm2TDBKM_vQ_oA@mail.gmail.com
2017-03-09 19:09:48 +01:00
If the new partition is a regular table, a full table scan is performed
to check that no existing row in the table violates the partition
constraint. It is possible to avoid this scan by adding a valid
<literal>CHECK</literal> constraint to the table that would allow only
the rows satisfying the desired partition constraint before running this
command. It will be determined using such a constraint that the table
need not be scanned to validate the partition constraint. This does not
work, however, if any of the partition keys is an expression and the
partition does not accept <literal>NULL</literal> values. If attaching
a list partition that will not accept <literal>NULL</literal> values,
also add <literal>NOT NULL</literal> constraint to the partition key
column, unless it's an expression.
</para>
<para>
If the new partition is a foreign table, nothing is done to verify
that all the rows in the foreign table obey the partition constraint.
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
(See the discussion in <xref linkend="sql-createforeigntable"/> about
Document lack of validation when attaching foreign partitions. Ashutosh Bapat, revised a bit by me. Discussion: http://postgr.es/m/CAFjFpRdLaCa-1wJase0=YWG5o3cJnbuUt_vrqm2TDBKM_vQ_oA@mail.gmail.com
2017-03-09 19:09:48 +01:00
constraints on the foreign table.)
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
</para>
Allow a partitioned table to have a default partition. Any tuples that don't route to any other partition will route to the default partition. Jeevan Ladhe, Beena Emerson, Ashutosh Bapat, Rahila Syed, and Robert Haas, with review and testing at various stages by (at least) Rushabh Lathia, Keith Fiske, Amit Langote, Amul Sul, Rajkumar Raghuanshi, Sven Kunze, Kyotaro Horiguchi, Thom Brown, Rafia Sabih, and Dilip Kumar. Discussion: http://postgr.es/m/CAH2L28tbN4SYyhS7YV1YBWcitkqbhSWfQCy0G=apRcC_PEO-bg@mail.gmail.com Discussion: http://postgr.es/m/CAOG9ApEYj34fWMcvBMBQ-YtqR9fTdXhdN82QEKG0SVZ6zeL1xg@mail.gmail.com
2017-09-08 23:28:04 +02:00
<para>
When a table has a default partition, defining a new partition changes
the partition constraint for the default partition. The default
partition can't contain any rows that would need to be moved to the new
partition, and will be scanned to verify that none are present. This
scan, like the scan of the new partition, can be avoided if an
appropriate <literal>CHECK</literal> constraint is present. Also like
the scan of the new partition, it is always skipped when the default
partition is a foreign table.
</para>
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
</listitem>
</varlistentry>
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><literal>DETACH PARTITION</literal> <replaceable class="parameter">partition_name</replaceable></term>
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
<listitem>
<para>
This form detaches specified partition of the target table. The detached
partition continues to exist as a standalone table, but no longer has any
Local partitioned indexes When CREATE INDEX is run on a partitioned table, create catalog entries for an index on the partitioned table (which is just a placeholder since the table proper has no data of its own), and recurse to create actual indexes on the existing partitions; create them in future partitions also. As a convenience gadget, if the new index definition matches some existing index in partitions, these are picked up and used instead of creating new ones. Whichever way these indexes come about, they become attached to the index on the parent table and are dropped alongside it, and cannot be dropped on isolation unless they are detached first. To support pg_dump'ing these indexes, add commands CREATE INDEX ON ONLY <table> (which creates the index on the parent partitioned table, without recursing) and ALTER INDEX ATTACH PARTITION (which is used after the indexes have been created individually on each partition, to attach them to the parent index). These reconstruct prior database state exactly. Reviewed-by: (in alphabetical order) Peter Eisentraut, Robert Haas, Amit Langote, Jesper Pedersen, Simon Riggs, David Rowley Discussion: https://postgr.es/m/20171113170646.gzweigyrgg6pwsg4@alvherre.pgsql
2018-01-19 15:49:22 +01:00
ties to the table from which it was detached. Any indexes that were
attached to the target table's indexes are detached.
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
</para>
</listitem>
</varlistentry>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
</variablelist>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</para>
Update SQL-command reference pages for schema features.
2002-04-23 04:07:16 +02:00
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
<para>
Improve ALTER TABLE documentation The ALTER TABLE documentation wasn't terribly clear when it came to which commands could be combined together and what it meant when they were. In particular, SET TABLESPACE *can* be combined with other commands, when it's operating against a single table, but not when multiple tables are being moved with ALL IN TABLESPACE. Further, the actions are applied together but not really in 'parallel', at least today. Pointed out by: Amit Langote Improved wording from Tom. Back-patch to 9.4, where the ALL IN TABLESPACE option was added. Discussion: https://www.postgresql.org/message-id/14c535b4-13ef-0590-1b98-76af355a0763%40lab.ntt.co.jp
2016-12-21 21:03:32 +01:00
All the forms of ALTER TABLE that act on a single table, except
<literal>RENAME</literal>, <literal>SET SCHEMA</literal>,
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
<literal>ATTACH PARTITION</literal>, and
<literal>DETACH PARTITION</literal> can be combined into
Improve ALTER TABLE documentation The ALTER TABLE documentation wasn't terribly clear when it came to which commands could be combined together and what it meant when they were. In particular, SET TABLESPACE *can* be combined with other commands, when it's operating against a single table, but not when multiple tables are being moved with ALL IN TABLESPACE. Further, the actions are applied together but not really in 'parallel', at least today. Pointed out by: Amit Langote Improved wording from Tom. Back-patch to 9.4, where the ALL IN TABLESPACE option was added. Discussion: https://www.postgresql.org/message-id/14c535b4-13ef-0590-1b98-76af355a0763%40lab.ntt.co.jp
2016-12-21 21:03:32 +01:00
a list of multiple alterations to be applied together. For example, it
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
is possible to add several columns and/or alter the type of several
columns in a single command. This is particularly useful with large
tables, since only one pass over the table need be made.
</para>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
You must own the table to use <command>ALTER TABLE</command>.
Rework 'MOVE ALL' to 'ALTER .. ALL IN TABLESPACE' As 'ALTER TABLESPACE .. MOVE ALL' really didn't change the tablespace but instead changed objects inside tablespaces, it made sense to rework the syntax and supporting functions to operate under the 'ALTER (TABLE|INDEX|MATERIALIZED VIEW)' syntax and to be in tablecmds.c. Pointed out by Alvaro, who also suggested the new syntax. Back-patch to 9.4.
2014-08-22 01:06:17 +02:00
To change the schema or tablespace of a table, you must also have
<literal>CREATE</literal> privilege on the new schema or tablespace.
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
To add the table as a new child of a parent table, you must own the parent
table as well. Also, to attach a table as a new partition of the table,
you must own the table being attached.
Add documentation for ALTER TABLE ENABLE/DISABLE TRIGGER.
2005-08-24 19:24:19 +02:00
To alter the owner, you must also be a direct or indirect member of the new
owning role, and that role must have <literal>CREATE</literal> privilege on
the table's schema. (These restrictions enforce that altering the owner
doesn't do anything you couldn't do by dropping and recreating the table.
However, a superuser can alter ownership of any table anyway.)
Add support for privileges on types This adds support for the more or less SQL-conforming USAGE privilege on types and domains. The intent is to be able restrict which users can create dependencies on types, which restricts the way in which owners can alter types. reviewed by Yeb Havinga
2011-12-19 23:05:19 +01:00
To add a column or alter a column type or use the <literal>OF</literal>
clause, you must also have <literal>USAGE</literal> privilege on the data
type.
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</para>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
doc: Move ALTER TABLE IF EXISTS description to better place It was previously mixed in with the description of ALTER TABLE subcommands. Move it to the Parameters section, which is where it is on other reference pages. pointed out by Amit Langote
2015-04-24 19:22:18 +02:00
<varlistentry>
<term><literal>IF EXISTS</literal></term>
<listitem>
<para>
Do not throw an error if the table does not exist. A notice is issued
in this case.
</para>
</listitem>
</varlistentry>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">name</replaceable></term>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<listitem>
<para>
Provide adequate documentation of the "table_name *" notation. Somewhere along the line, somebody decided to remove all trace of this notation from the documentation text. It was still in the command syntax synopses, or at least some of them, but with no indication what it meant. This will not do, as evidenced by the confusion apparent in bug #7543; even if the notation is now unnecessary, people will find it in legacy SQL code and need to know what it does.
2012-09-17 20:59:31 +02:00
The name (optionally schema-qualified) of an existing table to
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
alter. If <literal>ONLY</literal> is specified before the table name, only
that table is altered. If <literal>ONLY</literal> is not specified, the table
Provide adequate documentation of the "table_name *" notation. Somewhere along the line, somebody decided to remove all trace of this notation from the documentation text. It was still in the command syntax synopses, or at least some of them, but with no indication what it meant. This will not do, as evidenced by the confusion apparent in bug #7543; even if the notation is now unnecessary, people will find it in legacy SQL code and need to know what it does.
2012-09-17 20:59:31 +02:00
and all its descendant tables (if any) are altered. Optionally,
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>*</literal> can be specified after the table name to explicitly
Provide adequate documentation of the "table_name *" notation. Somewhere along the line, somebody decided to remove all trace of this notation from the documentation text. It was still in the command syntax synopses, or at least some of them, but with no indication what it meant. This will not do, as evidenced by the confusion apparent in bug #7543; even if the notation is now unnecessary, people will find it in legacy SQL code and need to know what it does.
2012-09-17 20:59:31 +02:00
indicate that descendant tables are included.
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</para>
</listitem>
</varlistentry>
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">column_name</replaceable></term>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<listitem>
<para>
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
Name of a new or existing column.
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</para>
</listitem>
</varlistentry>
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">new_column_name</replaceable></term>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<listitem>
<para>
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
New name for an existing column.
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</para>
</listitem>
</varlistentry>
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">new_name</replaceable></term>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<listitem>
<para>
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
New name for the table.
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</para>
</listitem>
</varlistentry>
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">data_type</replaceable></term>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<listitem>
<para>
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
Data type of the new column, or new data type for an existing
column.
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</para>
</listitem>
</varlistentry>
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">table_constraint</replaceable></term>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<listitem>
<para>
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
New table constraint for the table.
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</para>
</listitem>
</varlistentry>
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">constraint_name</replaceable></term>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<listitem>
<para>
Correct description of constraint_name in ALTER TABLE documentation. Apparently, the old text was written at a time when the only use of constraint_name here was for a constraint to be dropped, but that's no longer true. Etsuro Fujita
2014-04-14 16:52:07 +02:00
Name of a new or existing constraint.
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</para>
</listitem>
</varlistentry>
<varlistentry>
ALTER TABLE SET TABLESPACE. Gavin Sherry, some rework by Tom Lane.
2004-07-12 01:13:58 +02:00
<term><literal>CASCADE</literal></term>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<listitem>
<para>
ALTER TABLE SET TABLESPACE. Gavin Sherry, some rework by Tom Lane.
2004-07-12 01:13:58 +02:00
Automatically drop objects that depend on the dropped column
Doc: clarify that DROP ... CASCADE is recursive. Apparently that's not obvious to everybody, so let's belabor the point. In passing, document that DROP POLICY has CASCADE/RESTRICT options (which it does, per gram.y) but they do nothing (I assume, anyway). Also update some long-obsolete commentary in gram.y. Discussion: <20160805104837.1412.84915@wrigleys.postgresql.org>
2016-08-13 00:45:18 +02:00
or constraint (for example, views referencing the column),
and in turn all objects that depend on those objects
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
(see <xref linkend="ddl-depend"/>).
ALTER TABLE SET TABLESPACE. Gavin Sherry, some rework by Tom Lane.
2004-07-12 01:13:58 +02:00
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
Refuse to drop the column or constraint if there are any dependent
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
objects. This is the default behavior.
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</para>
</listitem>
</varlistentry>
Add documentation for ALTER TABLE ENABLE/DISABLE TRIGGER.
2005-08-24 19:24:19 +02:00
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">trigger_name</replaceable></term>
Add documentation for ALTER TABLE ENABLE/DISABLE TRIGGER.
2005-08-24 19:24:19 +02:00
<listitem>
<para>
Name of a single trigger to disable or enable.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ALL</literal></term>
<listitem>
<para>
Disable or enable all triggers belonging to the table.
Update ALTER TABLE docs to account for exclusion and deferrable uniqueness constraints Dean Rasheed
2010-06-09 19:48:10 +02:00
(This requires superuser privilege if any of the triggers are
internally generated constraint triggers such as those that are used
to implement foreign key constraints or deferrable uniqueness and
exclusion constraints.)
Add documentation for ALTER TABLE ENABLE/DISABLE TRIGGER.
2005-08-24 19:24:19 +02:00
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>USER</literal></term>
<listitem>
<para>
Disable or enable all triggers belonging to the table except for
Update ALTER TABLE docs to account for exclusion and deferrable uniqueness constraints Dean Rasheed
2010-06-09 19:48:10 +02:00
internally generated constraint triggers such as those that are used
to implement foreign key constraints or deferrable uniqueness and
exclusion constraints.
Add documentation for ALTER TABLE ENABLE/DISABLE TRIGGER.
2005-08-24 19:24:19 +02:00
</para>
</listitem>
</varlistentry>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">index_name</replaceable></term>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<listitem>
<para>
Minor fixes for ALTER TABLE documentation. Etsuro Fujita
2014-04-28 16:10:51 +02:00
The name of an existing index.
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</para>
</listitem>
</varlistentry>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">storage_parameter</replaceable></term>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
<listitem>
<para>
The name of a table storage parameter.
</para>
</listitem>
</varlistentry>
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">value</replaceable></term>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
<listitem>
<para>
The new value for a table storage parameter.
This might be a number or a word depending on the parameter.
</para>
</listitem>
</varlistentry>
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">parent_table</replaceable></term>
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
2006-07-04 20:07:24 +02:00
<listitem>
<para>
A parent table to associate or de-associate with this table.
</para>
</listitem>
</varlistentry>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">new_owner</replaceable></term>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<listitem>
<para>
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
The user name of the new owner of the table.
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</para>
</listitem>
</varlistentry>
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">new_tablespace</replaceable></term>
Documentation for ALTER object SET SCHEMA commands. Also some minor editorialization.
2005-08-01 18:11:14 +02:00
<listitem>
<para>
The name of the tablespace to which the table will be moved.
</para>
</listitem>
</varlistentry>
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">new_schema</replaceable></term>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<listitem>
<para>
Documentation for ALTER object SET SCHEMA commands. Also some minor editorialization.
2005-08-01 18:11:14 +02:00
The name of the schema to which the table will be moved.
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</para>
</listitem>
</varlistentry>
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">partition_name</replaceable></term>
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
<listitem>
<para>
The name of the table to attach as a new partition or to detach from this table.
</para>
</listitem>
</varlistentry>
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">partition_bound_spec</replaceable></term>
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
<listitem>
<para>
The partition bound specification for a new partition. Refer to
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="sql-createtable"/> for more details on the syntax of the same.
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
</para>
</listitem>
</varlistentry>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<para>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
The key word <literal>COLUMN</literal> is noise and can be omitted.
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</para>
First files for reference pages.
1998-05-13 07:34:00 +02:00
Complete merge of all old man page information. ecpg reference page still needs formatting.
1999-07-22 17:09:15 +02:00
<para>
Fast ALTER TABLE ADD COLUMN with a non-NULL default Currently adding a column to a table with a non-NULL default results in a rewrite of the table. For large tables this can be both expensive and disruptive. This patch removes the need for the rewrite as long as the default value is not volatile. The default expression is evaluated at the time of the ALTER TABLE and the result stored in a new column (attmissingval) in pg_attribute, and a new column (atthasmissing) is set to true. Any existing row when fetched will be supplied with the attmissingval. New rows will have the supplied value or the default and so will never need the attmissingval. Any time the table is rewritten all the atthasmissing and attmissingval settings for the attributes are cleared, as they are no longer needed. The most visible code change from this is in heap_attisnull, which acquires a third TupleDesc argument, allowing it to detect a missing value if there is one. In many cases where it is known that there will not be any (e.g. catalog relations) NULL can be passed for this argument. Andrew Dunstan, heavily modified from an original patch from Serge Rielau. Reviewed by Tom Lane, Andres Freund, Tomas Vondra and David Rowley. Discussion: https://postgr.es/m/31e2e921-7002-4c27-59f5-51f08404c858@2ndQuadrant.com
2018-03-28 02:13:52 +02:00
When a column is added with <literal>ADD COLUMN</literal> and a
non-volatile <literal>DEFAULT</literal> is specified, the default is
evaluated at the time of the statement and the result stored in the
table's metadata. That value will be used for the column for all existing
rows. If no <literal>DEFAULT</literal> is specified, NULL is used. In
neither case is a rewrite of the table required.
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
</para>
<para>
Fast ALTER TABLE ADD COLUMN with a non-NULL default Currently adding a column to a table with a non-NULL default results in a rewrite of the table. For large tables this can be both expensive and disruptive. This patch removes the need for the rewrite as long as the default value is not volatile. The default expression is evaluated at the time of the ALTER TABLE and the result stored in a new column (attmissingval) in pg_attribute, and a new column (atthasmissing) is set to true. Any existing row when fetched will be supplied with the attmissingval. New rows will have the supplied value or the default and so will never need the attmissingval. Any time the table is rewritten all the atthasmissing and attmissingval settings for the attributes are cleared, as they are no longer needed. The most visible code change from this is in heap_attisnull, which acquires a third TupleDesc argument, allowing it to detect a missing value if there is one. In many cases where it is known that there will not be any (e.g. catalog relations) NULL can be passed for this argument. Andrew Dunstan, heavily modified from an original patch from Serge Rielau. Reviewed by Tom Lane, Andres Freund, Tomas Vondra and David Rowley. Discussion: https://postgr.es/m/31e2e921-7002-4c27-59f5-51f08404c858@2ndQuadrant.com
2018-03-28 02:13:52 +02:00
Adding a column with a volatile <literal>DEFAULT</literal> or
changing the type of an existing column will require the entire table and
its indexes to be rewritten. As an exception, when changing the type of an
existing column, if the <literal>USING</literal> clause does not change
the column contents and the old type is either binary coercible to the new
type or an unconstrained domain over the new type, a table rewrite is not
needed; but any indexes on the affected columns must still be rebuilt.
Adding or removing a system <literal>oid</literal> column also requires
rewriting the entire table. Table and/or index rebuilds may take a
significant amount of time for a large table; and will temporarily require
as much as double the disk space.
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
</para>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
Adding a <literal>CHECK</literal> or <literal>NOT NULL</literal> constraint requires
Improve documentation about MVCC-unsafe utility commands. The table-rewriting forms of ALTER TABLE are MVCC-unsafe, in much the same way as TRUNCATE, because they replace all rows of the table with newly-made rows with a new xmin. (Ideally, concurrent transactions with old snapshots would continue to see the old table contents, but the data is not there anymore --- and if it were there, it would be inconsistent with the table's updated rowtype, so there would be serious implementation problems to fix.) This was nowhere documented though, and the problem was only documented for TRUNCATE in a note in the TRUNCATE reference page. Create a new "Caveats" section in the MVCC chapter that can be home to this and other limitations on serializable consistency. In passing, fix a mistaken statement that VACUUM and CLUSTER would reclaim space occupied by a dropped column. They don't reconstruct existing tuples so they couldn't do that. Back-patch to all supported branches.
2015-08-15 19:30:16 +02:00
scanning the table to verify that existing rows meet the constraint,
but does not require a table rewrite.
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
</para>
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
<para>
Similarly, when attaching a new partition it may be scanned to verify that
existing rows meet the partition constraint.
</para>
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
<para>
The main reason for providing the option to specify multiple changes
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
in a single <command>ALTER TABLE</command> is that multiple table scans or
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
rewrites can thereby be combined into a single pass over the table.
Complete merge of all old man page information. ecpg reference page still needs formatting.
1999-07-22 17:09:15 +02:00
</para>
ALTER TABLE DROP COLUMN works. Patch by Christopher Kings-Lynne, code review by Tom Lane. Remaining issues: functions that take or return tuple types are likely to break if one drops (or adds!) a column in the table defining the type. Need to think about what to do here. Along the way: some code review for recent COPY changes; mark system columns attnotnull = true where appropriate, per discussion a month ago.
2002-08-02 20:15:10 +02:00
<para>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
The <literal>DROP COLUMN</literal> form does not physically remove
ALTER TABLE DROP COLUMN works. Patch by Christopher Kings-Lynne, code review by Tom Lane. Remaining issues: functions that take or return tuple types are likely to break if one drops (or adds!) a column in the table defining the type. Need to think about what to do here. Along the way: some code review for recent COPY changes; mark system columns attnotnull = true where appropriate, per discussion a month ago.
2002-08-02 20:15:10 +02:00
the column, but simply makes it invisible to SQL operations. Subsequent
Recommend ALTER TABLE ... TYPE as the best way to reclaim space occupied by deleted columns. The old method involving UPDATE and VACUUM FULL will be considerably less efficient.
2004-05-27 05:30:11 +02:00
insert and update operations in the table will store a null value for the
column. Thus, dropping a column is quick but it will not immediately
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
reduce the on-disk size of your table, as the space occupied
ALTER TABLE DROP COLUMN works. Patch by Christopher Kings-Lynne, code review by Tom Lane. Remaining issues: functions that take or return tuple types are likely to break if one drops (or adds!) a column in the table defining the type. Need to think about what to do here. Along the way: some code review for recent COPY changes; mark system columns attnotnull = true where appropriate, per discussion a month ago.
2002-08-02 20:15:10 +02:00
by the dropped column is not reclaimed. The space will be
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
reclaimed over time as existing rows are updated. (These statements do
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
not apply when dropping the system <literal>oid</literal> column; that is done
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
with an immediate rewrite.)
Recommend ALTER TABLE ... TYPE as the best way to reclaim space occupied by deleted columns. The old method involving UPDATE and VACUUM FULL will be considerably less efficient.
2004-05-27 05:30:11 +02:00
</para>
<para>
Improve documentation about MVCC-unsafe utility commands. The table-rewriting forms of ALTER TABLE are MVCC-unsafe, in much the same way as TRUNCATE, because they replace all rows of the table with newly-made rows with a new xmin. (Ideally, concurrent transactions with old snapshots would continue to see the old table contents, but the data is not there anymore --- and if it were there, it would be inconsistent with the table's updated rowtype, so there would be serious implementation problems to fix.) This was nowhere documented though, and the problem was only documented for TRUNCATE in a note in the TRUNCATE reference page. Create a new "Caveats" section in the MVCC chapter that can be home to this and other limitations on serializable consistency. In passing, fix a mistaken statement that VACUUM and CLUSTER would reclaim space occupied by a dropped column. They don't reconstruct existing tuples so they couldn't do that. Back-patch to all supported branches.
2015-08-15 19:30:16 +02:00
To force immediate reclamation of space occupied by a dropped column,
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
you can execute one of the forms of <command>ALTER TABLE</command> that
Improve documentation about MVCC-unsafe utility commands. The table-rewriting forms of ALTER TABLE are MVCC-unsafe, in much the same way as TRUNCATE, because they replace all rows of the table with newly-made rows with a new xmin. (Ideally, concurrent transactions with old snapshots would continue to see the old table contents, but the data is not there anymore --- and if it were there, it would be inconsistent with the table's updated rowtype, so there would be serious implementation problems to fix.) This was nowhere documented though, and the problem was only documented for TRUNCATE in a note in the TRUNCATE reference page. Create a new "Caveats" section in the MVCC chapter that can be home to this and other limitations on serializable consistency. In passing, fix a mistaken statement that VACUUM and CLUSTER would reclaim space occupied by a dropped column. They don't reconstruct existing tuples so they couldn't do that. Back-patch to all supported branches.
2015-08-15 19:30:16 +02:00
performs a rewrite of the whole table. This results in reconstructing
each row with the dropped column replaced by a null value.
</para>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The rewriting forms of <command>ALTER TABLE</command> are not MVCC-safe.
Improve documentation about MVCC-unsafe utility commands. The table-rewriting forms of ALTER TABLE are MVCC-unsafe, in much the same way as TRUNCATE, because they replace all rows of the table with newly-made rows with a new xmin. (Ideally, concurrent transactions with old snapshots would continue to see the old table contents, but the data is not there anymore --- and if it were there, it would be inconsistent with the table's updated rowtype, so there would be serious implementation problems to fix.) This was nowhere documented though, and the problem was only documented for TRUNCATE in a note in the TRUNCATE reference page. Create a new "Caveats" section in the MVCC chapter that can be home to this and other limitations on serializable consistency. In passing, fix a mistaken statement that VACUUM and CLUSTER would reclaim space occupied by a dropped column. They don't reconstruct existing tuples so they couldn't do that. Back-patch to all supported branches.
2015-08-15 19:30:16 +02:00
After a table rewrite, the table will appear empty to concurrent
transactions, if they are using a snapshot taken before the rewrite
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
occurred. See <xref linkend="mvcc-caveats"/> for more details.
ALTER TABLE DROP COLUMN works. Patch by Christopher Kings-Lynne, code review by Tom Lane. Remaining issues: functions that take or return tuple types are likely to break if one drops (or adds!) a column in the table defining the type. Need to think about what to do here. Along the way: some code review for recent COPY changes; mark system columns attnotnull = true where appropriate, per discussion a month ago.
2002-08-02 20:15:10 +02:00
</para>
In ALTER COLUMN TYPE, strip any implicit coercion operations appearing at the top level of the column's old default expression before adding an implicit coercion to the new column type. This seems to satisfy the principle of least surprise, as per discussion of bug #1290.
2004-10-22 19:20:05 +02:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The <literal>USING</literal> option of <literal>SET DATA TYPE</literal> can actually
In ALTER COLUMN TYPE, strip any implicit coercion operations appearing at the top level of the column's old default expression before adding an implicit coercion to the new column type. This seems to satisfy the principle of least surprise, as per discussion of bug #1290.
2004-10-22 19:20:05 +02:00
specify any expression involving the old values of the row; that is, it
can refer to other columns as well as the one being converted. This allows
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
very general conversions to be done with the <literal>SET DATA TYPE</literal>
In ALTER COLUMN TYPE, strip any implicit coercion operations appearing at the top level of the column's old default expression before adding an implicit coercion to the new column type. This seems to satisfy the principle of least surprise, as per discussion of bug #1290.
2004-10-22 19:20:05 +02:00
syntax. Because of this flexibility, the <literal>USING</literal>
expression is not applied to the column's default value (if any); the
result might not be a constant expression as required for a default.
This means that when there is no implicit or assignment cast from old to
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
new type, <literal>SET DATA TYPE</literal> might fail to convert the default even
In ALTER COLUMN TYPE, strip any implicit coercion operations appearing at the top level of the column's old default expression before adding an implicit coercion to the new column type. This seems to satisfy the principle of least surprise, as per discussion of bug #1290.
2004-10-22 19:20:05 +02:00
though a <literal>USING</literal> clause is supplied. In such cases,
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
drop the default with <literal>DROP DEFAULT</literal>, perform the <literal>ALTER
TYPE</literal>, and then use <literal>SET DEFAULT</literal> to add a suitable new
More minor updates and copy-editing.
2005-01-04 01:39:53 +01:00
default. Similar considerations apply to indexes and constraints involving
the column.
In ALTER COLUMN TYPE, strip any implicit coercion operations appearing at the top level of the column's old default expression before adding an implicit coercion to the new column type. This seems to satisfy the principle of least surprise, as per discussion of bug #1290.
2004-10-22 19:20:05 +02:00
</para>
Fix incomplete definition of ALTER TABLE ADD/DROP CONSTRAINT syntax. Add some verbiage about recent tweaks to behavior of ADD and DROP COLUMN when there are descendant tables.
2002-10-20 00:51:45 +02:00
<para>
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
If a table has any descendant tables, it is not permitted to add,
Clarify policy on marking inherited constraints as valid. Amit Langote and Robert Haas
2016-09-15 23:24:54 +02:00
rename, or change the type of a column in the parent table without doing
Fully enforce uniqueness of constraint names. It's been true for a long time that we expect names of table and domain constraints to be unique among the constraints of that table or domain. However, the enforcement of that has been pretty haphazard, and it missed some corner cases such as creating a CHECK constraint and then an index constraint of the same name (as per recent report from André Hänsel). Also, due to the lack of an actual unique index enforcing this, duplicates could be created through race conditions. Moreover, the code that searches pg_constraint has been quite inconsistent about how to handle duplicate names if one did occur: some places checked and threw errors if there was more than one match, while others just processed the first match they came to. To fix, create a unique index on (conrelid, contypid, conname). Since either conrelid or contypid is zero, this will separately enforce uniqueness of constraint names among constraints of any one table and any one domain. (If we ever implement SQL assertions, and put them into this catalog, more thought might be needed. But it'd be at least as reasonable to put them into a new catalog; having overloaded this one catalog with two kinds of constraints was a mistake already IMO.) This index can replace the existing non-unique index on conrelid, though we need to keep the one on contypid for query performance reasons. Having done that, we can simplify the logic in various places that either coped with duplicates or neglected to, as well as potentially improve lookup performance when searching for a constraint by name. Also, as per our usual practice, install a preliminary check so that you get something more friendly than a unique-index violation report in the case complained of by André. And teach ChooseIndexName to avoid choosing autogenerated names that would draw such a failure. While it's not possible to make such a change in the back branches, it doesn't seem quite too late to put this into v11, so do so. Discussion: https://postgr.es/m/0c1001d4428f$0942b430$1bc81c90$@webkr.de
2018-09-04 19:45:35 +02:00
the same to the descendants. This ensures that the descendants always
have columns matching the parent. Similarly, a <literal>CHECK</literal>
constraint cannot be renamed in the parent without also renaming it in
all descendants, so that <literal>CHECK</literal> constraints also match
between the parent and its descendants. (That restriction does not apply
to index-based constraints, however.)
Spellcheck: s/descendent/descendant/g I got a little annoyed by reading documentation paragraphs containing both spellings within a few lines of each other. My dictionary says "descendant" is the preferred spelling, and it's certainly the majority usage in our tree, so standardize on that. For one usage in parallel.sgml, I thought it better to rewrite to avoid the term altogether.
2016-12-23 17:53:35 +01:00
Also, because selecting from the parent also selects from its descendants,
Clarify policy on marking inherited constraints as valid. Amit Langote and Robert Haas
2016-09-15 23:24:54 +02:00
a constraint on the parent cannot be marked valid unless it is also marked
Spellcheck: s/descendent/descendant/g I got a little annoyed by reading documentation paragraphs containing both spellings within a few lines of each other. My dictionary says "descendant" is the preferred spelling, and it's certainly the majority usage in our tree, so standardize on that. For one usage in parallel.sgml, I thought it better to rewrite to avoid the term altogether.
2016-12-23 17:53:35 +01:00
valid for those descendants. In all of these cases, <command>ALTER TABLE
doc: Remove some trailing whitespace Per discussion, we will not at this time remove trailing whitespace in psql output displays where it is part of the actual psql output. From: Vladimir Rusinov <vrusinov@google.com>
2016-12-17 18:00:00 +01:00
ONLY</command> will be rejected.
Fix incomplete definition of ALTER TABLE ADD/DROP CONSTRAINT syntax. Add some verbiage about recent tweaks to behavior of ADD and DROP COLUMN when there are descendant tables.
2002-10-20 00:51:45 +02:00
</para>
<para>
This patch makes the following changes to the documentation: - more work from the SGML police - some grammar improvements: rewriting a paragraph or two, replacing contractions where (IMHO) appropriate - fix missing utility commands in lock mode docs - improve CLUSTER, REINDEX, SET SESSION AUTHORIZATION ref pages Neil Conway
2003-02-19 05:06:28 +01:00
A recursive <literal>DROP COLUMN</literal> operation will remove a
descendant table's column only if the descendant does not inherit
that column from any other parents and never had an independent
definition of the column. A nonrecursive <literal>DROP
COLUMN</literal> (i.e., <command>ALTER TABLE ONLY ... DROP
COLUMN</command>) never removes any descendant columns, but
instead marks them as independently defined rather than inherited.
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
A nonrecursive <literal>DROP COLUMN</literal> command will fail for a
partitioned table, because all partitions of a table must have the same
columns as the partitioning root.
Fix incomplete definition of ALTER TABLE ADD/DROP CONSTRAINT syntax. Add some verbiage about recent tweaks to behavior of ADD and DROP COLUMN when there are descendant tables.
2002-10-20 00:51:45 +02:00
</para>
Add documentation for ALTER TABLE ENABLE/DISABLE TRIGGER.
2005-08-24 19:24:19 +02:00
<para>
Identity columns This is the SQL standard-conforming variant of PostgreSQL's serial columns. It fixes a few usability issues that serial columns have: - CREATE TABLE / LIKE copies default but refers to same sequence - cannot add/drop serialness with ALTER TABLE - dropping default does not drop sequence - need to grant separate privileges to sequence - other slight weirdnesses because serial is some kind of special macro Reviewed-by: Vitaly Burovoy <vitaly.burovoy@gmail.com>
2017-04-06 14:33:16 +02:00
The actions for identity columns (<literal>ADD
GENERATED</literal>, <literal>SET</literal> etc., <literal>DROP
IDENTITY</literal>), as well as the actions
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>TRIGGER</literal>, <literal>CLUSTER</literal>, <literal>OWNER</literal>,
and <literal>TABLESPACE</literal> never recurse to descendant tables;
that is, they always act as though <literal>ONLY</literal> were specified.
Adding a constraint recurses only for <literal>CHECK</literal> constraints
that are not marked <literal>NO INHERIT</literal>.
Add documentation for ALTER TABLE ENABLE/DISABLE TRIGGER.
2005-08-24 19:24:19 +02:00
</para>
Complete merge of all old man page information. ecpg reference page still needs formatting.
1999-07-22 17:09:15 +02:00
<para>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
Changing any part of a system catalog table is not permitted.
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</para>
First files for reference pages.
1998-05-13 07:34:00 +02:00
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<para>
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
Refer to <xref linkend="sql-createtable"/> for a further description of valid
parameters. <xref linkend="ddl"/> has further information on
This patch includes a lot of minor cleanups to the SGML documentation, including: - replacing all the appropriate usages of <citetitle>PostgreSQL ...</citetitle> with &cite-user;, &cite-admin;, and so on - fix an omission in the EXECUTE documentation - add some more text to the EXPLAIN documentation - improve the PL/PgSQL RETURN NEXT documentation (more work to do here) - minor markup fixes Neil Conway
2003-01-19 01:13:31 +01:00
inheritance.
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</para>
</refsect1>
First files for reference pages.
1998-05-13 07:34:00 +02:00
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<refsect1>
<title>Examples</title>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<para>
Spell-check and markup police
2002-01-20 23:19:57 +01:00
To add a column of type <type>varchar</type> to a table:
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<programlisting>
ALTER TABLE distributors ADD COLUMN address varchar(30);
</programlisting>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</para>
First files for reference pages.
1998-05-13 07:34:00 +02:00
ALTER TABLE DROP COLUMN works. Patch by Christopher Kings-Lynne, code review by Tom Lane. Remaining issues: functions that take or return tuple types are likely to break if one drops (or adds!) a column in the table defining the type. Need to think about what to do here. Along the way: some code review for recent COPY changes; mark system columns attnotnull = true where appropriate, per discussion a month ago.
2002-08-02 20:15:10 +02:00
<para>
To drop a column from a table:
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<programlisting>
ALTER TABLE DROP COLUMN works. Patch by Christopher Kings-Lynne, code review by Tom Lane. Remaining issues: functions that take or return tuple types are likely to break if one drops (or adds!) a column in the table defining the type. Need to think about what to do here. Along the way: some code review for recent COPY changes; mark system columns attnotnull = true where appropriate, per discussion a month ago.
2002-08-02 20:15:10 +02:00
ALTER TABLE distributors DROP COLUMN address RESTRICT;
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</programlisting>
ALTER TABLE DROP COLUMN works. Patch by Christopher Kings-Lynne, code review by Tom Lane. Remaining issues: functions that take or return tuple types are likely to break if one drops (or adds!) a column in the table defining the type. Need to think about what to do here. Along the way: some code review for recent COPY changes; mark system columns attnotnull = true where appropriate, per discussion a month ago.
2002-08-02 20:15:10 +02:00
</para>
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
<para>
To change the types of two existing columns in one operation:
<programlisting>
ALTER TABLE distributors
ALTER COLUMN address TYPE varchar(80),
ALTER COLUMN name TYPE varchar(100);
</programlisting>
</para>
Incorporate examples and doc patches from Mark Kirkwood and David Fetter.
2005-01-14 02:16:52 +01:00
<para>
doc: Spell checking
2015-09-11 03:22:21 +02:00
To change an integer column containing Unix timestamps to <type>timestamp
Incorporate examples and doc patches from Mark Kirkwood and David Fetter.
2005-01-14 02:16:52 +01:00
with time zone</type> via a <literal>USING</literal> clause:
<programlisting>
ALTER TABLE foo
Allow SQL:2008 syntax ALTER TABLE ... ALTER COLUMN ... SET DATA TYPE alongside our traditional syntax.
2008-10-21 10:38:16 +02:00
ALTER COLUMN foo_timestamp SET DATA TYPE timestamp with time zone
Incorporate examples and doc patches from Mark Kirkwood and David Fetter.
2005-01-14 02:16:52 +01:00
USING
timestamp with time zone 'epoch' + foo_timestamp * interval '1 second';
</programlisting>
</para>
Cause ALTER TABLE to perform ALTER COLUMN DROP DEFAULT operations during the DROP pass rather than the ADD_CONSTR pass. On examining the code I think this was just an oversight rather than intentional, and it seems to satisfy the principle of least surprise better than the alternative solution that was discussed. Add an example to the ref page showing how to do ALTER TYPE and update the default in one command. Per gripe from Markus Bertheau that that wasn't possible.
2006-08-03 22:57:06 +02:00
<para>
The same, when the column has a default expression that won't automatically
Spellchecking and such
2006-10-23 20:10:32 +02:00
cast to the new data type:
Cause ALTER TABLE to perform ALTER COLUMN DROP DEFAULT operations during the DROP pass rather than the ADD_CONSTR pass. On examining the code I think this was just an oversight rather than intentional, and it seems to satisfy the principle of least surprise better than the alternative solution that was discussed. Add an example to the ref page showing how to do ALTER TYPE and update the default in one command. Per gripe from Markus Bertheau that that wasn't possible.
2006-08-03 22:57:06 +02:00
<programlisting>
ALTER TABLE foo
ALTER COLUMN foo_timestamp DROP DEFAULT,
ALTER COLUMN foo_timestamp TYPE timestamp with time zone
USING
timestamp with time zone 'epoch' + foo_timestamp * interval '1 second',
ALTER COLUMN foo_timestamp SET DEFAULT now();
</programlisting>
</para>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<para>
First files for reference pages.
1998-05-13 07:34:00 +02:00
To rename an existing column:
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<programlisting>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
ALTER TABLE distributors RENAME COLUMN address TO city;
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</programlisting>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</para>
First files for reference pages.
1998-05-13 07:34:00 +02:00
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<para>
First files for reference pages.
1998-05-13 07:34:00 +02:00
To rename an existing table:
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<programlisting>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
ALTER TABLE distributors RENAME TO suppliers;
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</programlisting>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</para>
ALTER TABLE SET/DROP NOT NULL, from Christopher Kings-Lynne.
2002-04-01 06:35:40 +02:00
Add support for renaming constraints reviewed by Josh Berkus and Dimitri Fontaine
2012-03-10 19:19:13 +01:00
<para>
To rename an existing constraint:
<programlisting>
ALTER TABLE distributors RENAME CONSTRAINT zipchk TO zip_check;
</programlisting>
</para>
ALTER TABLE SET/DROP NOT NULL, from Christopher Kings-Lynne.
2002-04-01 06:35:40 +02:00
<para>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
To add a not-null constraint to a column:
<programlisting>
ALTER TABLE SET/DROP NOT NULL, from Christopher Kings-Lynne.
2002-04-01 06:35:40 +02:00
ALTER TABLE distributors ALTER COLUMN street SET NOT NULL;
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</programlisting>
To remove a not-null constraint from a column:
<programlisting>
ALTER TABLE SET/DROP NOT NULL, from Christopher Kings-Lynne.
2002-04-01 06:35:40 +02:00
ALTER TABLE distributors ALTER COLUMN street DROP NOT NULL;
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</programlisting>
ALTER TABLE SET/DROP NOT NULL, from Christopher Kings-Lynne.
2002-04-01 06:35:40 +02:00
</para>
Attached is are diffs for CREATE/ALTER table doc I've forgotten in my mailbox (sorry). Haven't tried to apply and since I don't have working sgml stuff cannot check. Jan
2000-04-11 16:43:54 +02:00
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
<para>
Change the rules for inherited CHECK constraints to be essentially the same as those for inherited columns; that is, it's no longer allowed for a child table to not have a check constraint matching one that exists on a parent. This satisfies the principle of least surprise (rows selected from the parent will always appear to meet its check constraints) and eliminates some longstanding bogosity in pg_dump, which formerly had to guess about whether check constraints were really inherited or not. The implementation involves adding conislocal and coninhcount columns to pg_constraint (paralleling attislocal and attinhcount in pg_attribute) and refactoring various ALTER TABLE actions to be more like those for columns. Alex Hunsaker, Nikhil Sontakke, Tom Lane
2008-05-10 01:32:05 +02:00
To add a check constraint to a table and all its children:
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<programlisting>
Fix typo (add ;)
2001-09-12 04:13:25 +02:00
ALTER TABLE distributors ADD CONSTRAINT zipchk CHECK (char_length(zipcode) = 5);
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</programlisting>
If it's true that the ALTER TABLE x ADD CONSTRAINT x CHECK (x) syntax is supported in 7.1.1, here is a patch to that alter_table.sgml that documents it. Christopher Kings-Lynne
2001-05-09 15:27:15 +02:00
</para>
Allow CHECK constraints to be declared ONLY This makes them enforceable only on the parent table, not on children tables. This is useful in various situations, per discussion involving people bitten by the restrictive behavior introduced in 8.4. Message-Id: 8762mp93iw.fsf@comcast.net CAFaPBrSMMpubkGf4zcRL_YL-AERUbYF_-ZNNYfb3CVwwEqc9TQ@mail.gmail.com Authors: Nikhil Sontakke, Alex Hunsaker Reviewed by Robert Haas and myself
2011-12-05 19:10:18 +01:00
<para>
To add a check constraint only to a table and not to its children:
<programlisting>
Change syntax of new CHECK NO INHERIT constraints The initially implemented syntax, "CHECK NO INHERIT (expr)" was not deemed very good, so switch to "CHECK (expr) NO INHERIT" instead. This way it looks similar to SQL-standards compliant constraint attribute. Backport to 9.2 where the new syntax and feature was introduced. Per discussion.
2012-07-24 21:49:54 +02:00
ALTER TABLE distributors ADD CONSTRAINT zipchk CHECK (char_length(zipcode) = 5) NO INHERIT;
Allow CHECK constraints to be declared ONLY This makes them enforceable only on the parent table, not on children tables. This is useful in various situations, per discussion involving people bitten by the restrictive behavior introduced in 8.4. Message-Id: 8762mp93iw.fsf@comcast.net CAFaPBrSMMpubkGf4zcRL_YL-AERUbYF_-ZNNYfb3CVwwEqc9TQ@mail.gmail.com Authors: Nikhil Sontakke, Alex Hunsaker Reviewed by Robert Haas and myself
2011-12-05 19:10:18 +01:00
</programlisting>
(The check constraint will not be inherited by future children, either.)
</para>
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
<para>
This is a docs patch to go with my DROP CONSTRAINT patch. Christopher Kings
2001-05-30 15:01:08 +02:00
To remove a check constraint from a table and all its children:
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<programlisting>
Second phase of committing Rod Taylor's pg_depend/pg_constraint patch. pg_relcheck is gone; CHECK, UNIQUE, PRIMARY KEY, and FOREIGN KEY constraints all have real live entries in pg_constraint. pg_depend exists, and RESTRICT/CASCADE options work on most kinds of DROP; however, pg_depend is not yet very well populated with dependencies. (Most of the ones that are present at this point just replace formerly hardwired associations, such as the implicit drop of a relation's pg_type entry when the relation is dropped.) Need to add more logic to create dependency entries, improve pg_dump to dump constraints in place of indexes and triggers, and add some regression tests.
2002-07-12 20:43:19 +02:00
ALTER TABLE distributors DROP CONSTRAINT zipchk;
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</programlisting>
This is a docs patch to go with my DROP CONSTRAINT patch. Christopher Kings
2001-05-30 15:01:08 +02:00
</para>
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
<para>
Provide adequate documentation of the "table_name *" notation. Somewhere along the line, somebody decided to remove all trace of this notation from the documentation text. It was still in the command syntax synopses, or at least some of them, but with no indication what it meant. This will not do, as evidenced by the confusion apparent in bug #7543; even if the notation is now unnecessary, people will find it in legacy SQL code and need to know what it does.
2012-09-17 20:59:31 +02:00
To remove a check constraint from one table only:
Change the rules for inherited CHECK constraints to be essentially the same as those for inherited columns; that is, it's no longer allowed for a child table to not have a check constraint matching one that exists on a parent. This satisfies the principle of least surprise (rows selected from the parent will always appear to meet its check constraints) and eliminates some longstanding bogosity in pg_dump, which formerly had to guess about whether check constraints were really inherited or not. The implementation involves adding conislocal and coninhcount columns to pg_constraint (paralleling attislocal and attinhcount in pg_attribute) and refactoring various ALTER TABLE actions to be more like those for columns. Alex Hunsaker, Nikhil Sontakke, Tom Lane
2008-05-10 01:32:05 +02:00
<programlisting>
ALTER TABLE ONLY distributors DROP CONSTRAINT zipchk;
</programlisting>
(The check constraint remains in place for any child tables.)
</para>
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
<para>
Attached is are diffs for CREATE/ALTER table doc I've forgotten in my mailbox (sorry). Haven't tried to apply and since I don't have working sgml stuff cannot check. Jan
2000-04-11 16:43:54 +02:00
To add a foreign key constraint to a table:
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<programlisting>
Remove unnecessary MATCH FULL specification in example. Reported by Grzegorz Szpetkowski.
2011-09-10 15:24:05 +02:00
ALTER TABLE distributors ADD CONSTRAINT distfk FOREIGN KEY (address) REFERENCES addresses (address);
Reduce lock levels of some ALTER TABLE cmds VALIDATE CONSTRAINT CLUSTER ON SET WITHOUT CLUSTER ALTER COLUMN SET STATISTICS ALTER COLUMN SET () ALTER COLUMN RESET () All other sub-commands use AccessExclusiveLock Simon Riggs and Noah Misch Reviews by Robert Haas and Andres Freund
2014-04-06 17:13:43 +02:00
</programlisting>
</para>
<para>
To add a foreign key constraint to a table with the least impact on other work:
<programlisting>
ALTER TABLE distributors ADD CONSTRAINT distfk FOREIGN KEY (address) REFERENCES addresses (address) NOT VALID;
ALTER TABLE distributors VALIDATE CONSTRAINT distfk;
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</programlisting>
Attached is are diffs for CREATE/ALTER table doc I've forgotten in my mailbox (sorry). Haven't tried to apply and since I don't have working sgml stuff cannot check. Jan
2000-04-11 16:43:54 +02:00
</para>
Here is my much-promised patch to let people add UNIQUE constraints after table creation time. Big deal you say - but this patch is the basis of the next thing which is adding PRIMARY KEYs after table creation time. (Which is currently impossible without twiddling catalogs) Rundown ------- * I have made the makeObjectName function of analyze.c non-static, and exported it in analyze.h * I have included analyze.h and defrem.h into command.c, to support makingObjectNames and creating indices * I removed the 'case CONSTR_PRIMARY' clause so that it properly fails and says you can't add primary keys, rather than just doing nothing and reporting nothing!!! * I have modified the docs. Algorithm --------- * If name specified is null, search for a new valid constraint name. I'm not sure if I should "lock" my generated name somehow tho - should I open the relation before doing this step? * Open relation in access exclusive mode * Check that the constraint does not already exist * Define the new index * Warn if they're doubling up on an existing index Christopher Kings-Lynne
2001-09-07 23:57:53 +02:00
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
<para>
Spell-check and markup police
2002-01-20 23:19:57 +01:00
To add a (multicolumn) unique constraint to a table:
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<programlisting>
Fix typo (add ;)
2001-09-12 04:13:25 +02:00
ALTER TABLE distributors ADD CONSTRAINT dist_id_zipcode_key UNIQUE (dist_id, zipcode);
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</programlisting>
I think it's important that it's actually documented that they can add primary keys after the fact! Also, we need to add regression tests for alter table / add primary key and alter table / drop constraint. These shouldn't be added until 7.3 tho methinks... Chris
2002-02-17 12:50:09 +01:00
</para>
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
<para>
I think it's important that it's actually documented that they can add primary keys after the fact! Also, we need to add regression tests for alter table / add primary key and alter table / drop constraint. These shouldn't be added until 7.3 tho methinks... Chris
2002-02-17 12:50:09 +01:00
To add an automatically named primary key constraint to a table, noting
that a table can only ever have one primary key:
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<programlisting>
I think it's important that it's actually documented that they can add primary keys after the fact! Also, we need to add regression tests for alter table / add primary key and alter table / drop constraint. These shouldn't be added until 7.3 tho methinks... Chris
2002-02-17 12:50:09 +01:00
ALTER TABLE distributors ADD PRIMARY KEY (dist_id);
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</programlisting>
Here is my much-promised patch to let people add UNIQUE constraints after table creation time. Big deal you say - but this patch is the basis of the next thing which is adding PRIMARY KEYs after table creation time. (Which is currently impossible without twiddling catalogs) Rundown ------- * I have made the makeObjectName function of analyze.c non-static, and exported it in analyze.h * I have included analyze.h and defrem.h into command.c, to support makingObjectNames and creating indices * I removed the 'case CONSTR_PRIMARY' clause so that it properly fails and says you can't add primary keys, rather than just doing nothing and reporting nothing!!! * I have modified the docs. Algorithm --------- * If name specified is null, search for a new valid constraint name. I'm not sure if I should "lock" my generated name somehow tho - should I open the relation before doing this step? * Open relation in access exclusive mode * Check that the constraint does not already exist * Define the new index * Warn if they're doubling up on an existing index Christopher Kings-Lynne
2001-09-07 23:57:53 +02:00
</para>
ALTER TABLE SET TABLESPACE. Gavin Sherry, some rework by Tom Lane.
2004-07-12 01:13:58 +02:00
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
<para>
Documentation for ALTER object SET SCHEMA commands. Also some minor editorialization.
2005-08-01 18:11:14 +02:00
To move a table to a different tablespace:
ALTER TABLE SET TABLESPACE. Gavin Sherry, some rework by Tom Lane.
2004-07-12 01:13:58 +02:00
<programlisting>
ALTER TABLE distributors SET TABLESPACE fasttablespace;
Documentation for ALTER object SET SCHEMA commands. Also some minor editorialization.
2005-08-01 18:11:14 +02:00
</programlisting>
</para>
Change ALTER TABLE SET WITHOUT OIDS to rewrite the whole table to physically get rid of the OID column. This eliminates the problem discovered by Heikki back in November that 8.4's suppression of "unnecessary" junk filtering in INSERT/SELECT could lead to an Assert failure, or storing of oids into a table that shouldn't have them if Asserts are off. While that particular problem could have been solved in other ways, it seems likely to be just a forerunner of things to come if we continue to allow tables to contain rows that disagree with the pg_class.relhasoids setting. It's better to make this operation slow than to sacrifice performance or risk bugs in more common code paths. Also, add ALTER TABLE SET WITH OIDS to rewrite the table to add oids. This was a bit more controversial, but in view of the very small amount of extra code needed given the current ALTER TABLE infrastructure, it seems best to eliminate the asymmetry in features.
2009-02-11 22:11:16 +01:00
<para>
Documentation for ALTER object SET SCHEMA commands. Also some minor editorialization.
2005-08-01 18:11:14 +02:00
To move a table to a different schema:
<programlisting>
ALTER TABLE myschema.distributors SET SCHEMA yourschema;
ALTER TABLE SET TABLESPACE. Gavin Sherry, some rework by Tom Lane.
2004-07-12 01:13:58 +02:00
</programlisting>
</para>
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
<para>
To recreate a primary key constraint, without blocking updates while the
index is rebuilt:
<programlisting>
Make 'on' uppercase in a sql example.
2011-01-26 14:35:01 +01:00
CREATE UNIQUE INDEX CONCURRENTLY dist_id_temp_idx ON distributors (dist_id);
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
ALTER TABLE distributors DROP CONSTRAINT distributors_pkey,
ADD CONSTRAINT distributors_pkey PRIMARY KEY USING INDEX dist_id_temp_idx;
Fix a whitespace issue with the man pages There is what may actually be a mistake in our markup. The problem is in a situation like <para> <command>FOO</command> is ... there is strictly speaking a line break before "FOO". In the HTML output, this does not appear to be a problem, but in the man page output, this shows up, so you get double blank lines at odd places. So far, we have attempted to work around this with an XSL hack, but that causes other problems, such as creating run-ins in places like <acronym>SQL</acronym> <command>COPY</command> So fix the problem properly by removing the extra whitespace. I only fixed the problems that affect the man page output, not all the places.
2011-08-07 09:49:45 +02:00
</programlisting></para>
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
<para>
Fully enforce uniqueness of constraint names. It's been true for a long time that we expect names of table and domain constraints to be unique among the constraints of that table or domain. However, the enforcement of that has been pretty haphazard, and it missed some corner cases such as creating a CHECK constraint and then an index constraint of the same name (as per recent report from André Hänsel). Also, due to the lack of an actual unique index enforcing this, duplicates could be created through race conditions. Moreover, the code that searches pg_constraint has been quite inconsistent about how to handle duplicate names if one did occur: some places checked and threw errors if there was more than one match, while others just processed the first match they came to. To fix, create a unique index on (conrelid, contypid, conname). Since either conrelid or contypid is zero, this will separately enforce uniqueness of constraint names among constraints of any one table and any one domain. (If we ever implement SQL assertions, and put them into this catalog, more thought might be needed. But it'd be at least as reasonable to put them into a new catalog; having overloaded this one catalog with two kinds of constraints was a mistake already IMO.) This index can replace the existing non-unique index on conrelid, though we need to keep the one on contypid for query performance reasons. Having done that, we can simplify the logic in various places that either coped with duplicates or neglected to, as well as potentially improve lookup performance when searching for a constraint by name. Also, as per our usual practice, install a preliminary check so that you get something more friendly than a unique-index violation report in the case complained of by André. And teach ChooseIndexName to avoid choosing autogenerated names that would draw such a failure. While it's not possible to make such a change in the back branches, it doesn't seem quite too late to put this into v11, so do so. Discussion: https://postgr.es/m/0c1001d4428f$0942b430$1bc81c90$@webkr.de
2018-09-04 19:45:35 +02:00
To attach a partition to a range-partitioned table:
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
<programlisting>
ALTER TABLE measurement
ATTACH PARTITION measurement_y2016m07 FOR VALUES FROM ('2016-07-01') TO ('2016-08-01');
</programlisting></para>
<para>
Fully enforce uniqueness of constraint names. It's been true for a long time that we expect names of table and domain constraints to be unique among the constraints of that table or domain. However, the enforcement of that has been pretty haphazard, and it missed some corner cases such as creating a CHECK constraint and then an index constraint of the same name (as per recent report from André Hänsel). Also, due to the lack of an actual unique index enforcing this, duplicates could be created through race conditions. Moreover, the code that searches pg_constraint has been quite inconsistent about how to handle duplicate names if one did occur: some places checked and threw errors if there was more than one match, while others just processed the first match they came to. To fix, create a unique index on (conrelid, contypid, conname). Since either conrelid or contypid is zero, this will separately enforce uniqueness of constraint names among constraints of any one table and any one domain. (If we ever implement SQL assertions, and put them into this catalog, more thought might be needed. But it'd be at least as reasonable to put them into a new catalog; having overloaded this one catalog with two kinds of constraints was a mistake already IMO.) This index can replace the existing non-unique index on conrelid, though we need to keep the one on contypid for query performance reasons. Having done that, we can simplify the logic in various places that either coped with duplicates or neglected to, as well as potentially improve lookup performance when searching for a constraint by name. Also, as per our usual practice, install a preliminary check so that you get something more friendly than a unique-index violation report in the case complained of by André. And teach ChooseIndexName to avoid choosing autogenerated names that would draw such a failure. While it's not possible to make such a change in the back branches, it doesn't seem quite too late to put this into v11, so do so. Discussion: https://postgr.es/m/0c1001d4428f$0942b430$1bc81c90$@webkr.de
2018-09-04 19:45:35 +02:00
To attach a partition to a list-partitioned table:
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
<programlisting>
ALTER TABLE cities
doc: Improve documentation related to table partitioning feature. Commit f0e44751d7175fa3394da2c8f85e3ceb3cdbfe63 implemented table partitioning, but failed to mention the "no row movement" restriction in the documentation. Fix that and a few other issues. Amit Langote, with some additional wordsmithing by me.
2016-12-13 14:18:00 +01:00
ATTACH PARTITION cities_ab FOR VALUES IN ('a', 'b');
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
</programlisting></para>
Allow a partitioned table to have a default partition. Any tuples that don't route to any other partition will route to the default partition. Jeevan Ladhe, Beena Emerson, Ashutosh Bapat, Rahila Syed, and Robert Haas, with review and testing at various stages by (at least) Rushabh Lathia, Keith Fiske, Amit Langote, Amul Sul, Rajkumar Raghuanshi, Sven Kunze, Kyotaro Horiguchi, Thom Brown, Rafia Sabih, and Dilip Kumar. Discussion: http://postgr.es/m/CAH2L28tbN4SYyhS7YV1YBWcitkqbhSWfQCy0G=apRcC_PEO-bg@mail.gmail.com Discussion: http://postgr.es/m/CAOG9ApEYj34fWMcvBMBQ-YtqR9fTdXhdN82QEKG0SVZ6zeL1xg@mail.gmail.com
2017-09-08 23:28:04 +02:00
<para>
Fully enforce uniqueness of constraint names. It's been true for a long time that we expect names of table and domain constraints to be unique among the constraints of that table or domain. However, the enforcement of that has been pretty haphazard, and it missed some corner cases such as creating a CHECK constraint and then an index constraint of the same name (as per recent report from André Hänsel). Also, due to the lack of an actual unique index enforcing this, duplicates could be created through race conditions. Moreover, the code that searches pg_constraint has been quite inconsistent about how to handle duplicate names if one did occur: some places checked and threw errors if there was more than one match, while others just processed the first match they came to. To fix, create a unique index on (conrelid, contypid, conname). Since either conrelid or contypid is zero, this will separately enforce uniqueness of constraint names among constraints of any one table and any one domain. (If we ever implement SQL assertions, and put them into this catalog, more thought might be needed. But it'd be at least as reasonable to put them into a new catalog; having overloaded this one catalog with two kinds of constraints was a mistake already IMO.) This index can replace the existing non-unique index on conrelid, though we need to keep the one on contypid for query performance reasons. Having done that, we can simplify the logic in various places that either coped with duplicates or neglected to, as well as potentially improve lookup performance when searching for a constraint by name. Also, as per our usual practice, install a preliminary check so that you get something more friendly than a unique-index violation report in the case complained of by André. And teach ChooseIndexName to avoid choosing autogenerated names that would draw such a failure. While it's not possible to make such a change in the back branches, it doesn't seem quite too late to put this into v11, so do so. Discussion: https://postgr.es/m/0c1001d4428f$0942b430$1bc81c90$@webkr.de
2018-09-04 19:45:35 +02:00
To attach a partition to a hash-partitioned table:
Allow a partitioned table to have a default partition. Any tuples that don't route to any other partition will route to the default partition. Jeevan Ladhe, Beena Emerson, Ashutosh Bapat, Rahila Syed, and Robert Haas, with review and testing at various stages by (at least) Rushabh Lathia, Keith Fiske, Amit Langote, Amul Sul, Rajkumar Raghuanshi, Sven Kunze, Kyotaro Horiguchi, Thom Brown, Rafia Sabih, and Dilip Kumar. Discussion: http://postgr.es/m/CAH2L28tbN4SYyhS7YV1YBWcitkqbhSWfQCy0G=apRcC_PEO-bg@mail.gmail.com Discussion: http://postgr.es/m/CAOG9ApEYj34fWMcvBMBQ-YtqR9fTdXhdN82QEKG0SVZ6zeL1xg@mail.gmail.com
2017-09-08 23:28:04 +02:00
<programlisting>
Fully enforce uniqueness of constraint names. It's been true for a long time that we expect names of table and domain constraints to be unique among the constraints of that table or domain. However, the enforcement of that has been pretty haphazard, and it missed some corner cases such as creating a CHECK constraint and then an index constraint of the same name (as per recent report from André Hänsel). Also, due to the lack of an actual unique index enforcing this, duplicates could be created through race conditions. Moreover, the code that searches pg_constraint has been quite inconsistent about how to handle duplicate names if one did occur: some places checked and threw errors if there was more than one match, while others just processed the first match they came to. To fix, create a unique index on (conrelid, contypid, conname). Since either conrelid or contypid is zero, this will separately enforce uniqueness of constraint names among constraints of any one table and any one domain. (If we ever implement SQL assertions, and put them into this catalog, more thought might be needed. But it'd be at least as reasonable to put them into a new catalog; having overloaded this one catalog with two kinds of constraints was a mistake already IMO.) This index can replace the existing non-unique index on conrelid, though we need to keep the one on contypid for query performance reasons. Having done that, we can simplify the logic in various places that either coped with duplicates or neglected to, as well as potentially improve lookup performance when searching for a constraint by name. Also, as per our usual practice, install a preliminary check so that you get something more friendly than a unique-index violation report in the case complained of by André. And teach ChooseIndexName to avoid choosing autogenerated names that would draw such a failure. While it's not possible to make such a change in the back branches, it doesn't seem quite too late to put this into v11, so do so. Discussion: https://postgr.es/m/0c1001d4428f$0942b430$1bc81c90$@webkr.de
2018-09-04 19:45:35 +02:00
ALTER TABLE orders
ATTACH PARTITION orders_p4 FOR VALUES WITH (MODULUS 4, REMAINDER 3);
Allow a partitioned table to have a default partition. Any tuples that don't route to any other partition will route to the default partition. Jeevan Ladhe, Beena Emerson, Ashutosh Bapat, Rahila Syed, and Robert Haas, with review and testing at various stages by (at least) Rushabh Lathia, Keith Fiske, Amit Langote, Amul Sul, Rajkumar Raghuanshi, Sven Kunze, Kyotaro Horiguchi, Thom Brown, Rafia Sabih, and Dilip Kumar. Discussion: http://postgr.es/m/CAH2L28tbN4SYyhS7YV1YBWcitkqbhSWfQCy0G=apRcC_PEO-bg@mail.gmail.com Discussion: http://postgr.es/m/CAOG9ApEYj34fWMcvBMBQ-YtqR9fTdXhdN82QEKG0SVZ6zeL1xg@mail.gmail.com
2017-09-08 23:28:04 +02:00
</programlisting></para>
Add hash partitioning. Hash partitioning is useful when you want to partition a growing data set evenly. This can be useful to keep table sizes reasonable, which makes maintenance operations such as VACUUM faster, or to enable partition-wise join. At present, we still depend on constraint exclusion for partitioning pruning, and the shape of the partition constraints for hash partitioning is such that that doesn't work. Work is underway to fix that, which should both improve performance and make partitioning pruning work with hash partitioning. Amul Sul, reviewed and tested by Dilip Kumar, Ashutosh Bapat, Yugo Nagata, Rajkumar Raghuwanshi, Jesper Pedersen, and by me. A few final tweaks also by me. Discussion: http://postgr.es/m/CAAJ_b96fhpJAP=ALbETmeLk1Uni_GFZD938zgenhF49qgDTjaQ@mail.gmail.com
2017-11-10 00:07:25 +01:00
<para>
Fully enforce uniqueness of constraint names. It's been true for a long time that we expect names of table and domain constraints to be unique among the constraints of that table or domain. However, the enforcement of that has been pretty haphazard, and it missed some corner cases such as creating a CHECK constraint and then an index constraint of the same name (as per recent report from André Hänsel). Also, due to the lack of an actual unique index enforcing this, duplicates could be created through race conditions. Moreover, the code that searches pg_constraint has been quite inconsistent about how to handle duplicate names if one did occur: some places checked and threw errors if there was more than one match, while others just processed the first match they came to. To fix, create a unique index on (conrelid, contypid, conname). Since either conrelid or contypid is zero, this will separately enforce uniqueness of constraint names among constraints of any one table and any one domain. (If we ever implement SQL assertions, and put them into this catalog, more thought might be needed. But it'd be at least as reasonable to put them into a new catalog; having overloaded this one catalog with two kinds of constraints was a mistake already IMO.) This index can replace the existing non-unique index on conrelid, though we need to keep the one on contypid for query performance reasons. Having done that, we can simplify the logic in various places that either coped with duplicates or neglected to, as well as potentially improve lookup performance when searching for a constraint by name. Also, as per our usual practice, install a preliminary check so that you get something more friendly than a unique-index violation report in the case complained of by André. And teach ChooseIndexName to avoid choosing autogenerated names that would draw such a failure. While it's not possible to make such a change in the back branches, it doesn't seem quite too late to put this into v11, so do so. Discussion: https://postgr.es/m/0c1001d4428f$0942b430$1bc81c90$@webkr.de
2018-09-04 19:45:35 +02:00
To attach a default partition to a partitioned table:
Add hash partitioning. Hash partitioning is useful when you want to partition a growing data set evenly. This can be useful to keep table sizes reasonable, which makes maintenance operations such as VACUUM faster, or to enable partition-wise join. At present, we still depend on constraint exclusion for partitioning pruning, and the shape of the partition constraints for hash partitioning is such that that doesn't work. Work is underway to fix that, which should both improve performance and make partitioning pruning work with hash partitioning. Amul Sul, reviewed and tested by Dilip Kumar, Ashutosh Bapat, Yugo Nagata, Rajkumar Raghuwanshi, Jesper Pedersen, and by me. A few final tweaks also by me. Discussion: http://postgr.es/m/CAAJ_b96fhpJAP=ALbETmeLk1Uni_GFZD938zgenhF49qgDTjaQ@mail.gmail.com
2017-11-10 00:07:25 +01:00
<programlisting>
Fully enforce uniqueness of constraint names. It's been true for a long time that we expect names of table and domain constraints to be unique among the constraints of that table or domain. However, the enforcement of that has been pretty haphazard, and it missed some corner cases such as creating a CHECK constraint and then an index constraint of the same name (as per recent report from André Hänsel). Also, due to the lack of an actual unique index enforcing this, duplicates could be created through race conditions. Moreover, the code that searches pg_constraint has been quite inconsistent about how to handle duplicate names if one did occur: some places checked and threw errors if there was more than one match, while others just processed the first match they came to. To fix, create a unique index on (conrelid, contypid, conname). Since either conrelid or contypid is zero, this will separately enforce uniqueness of constraint names among constraints of any one table and any one domain. (If we ever implement SQL assertions, and put them into this catalog, more thought might be needed. But it'd be at least as reasonable to put them into a new catalog; having overloaded this one catalog with two kinds of constraints was a mistake already IMO.) This index can replace the existing non-unique index on conrelid, though we need to keep the one on contypid for query performance reasons. Having done that, we can simplify the logic in various places that either coped with duplicates or neglected to, as well as potentially improve lookup performance when searching for a constraint by name. Also, as per our usual practice, install a preliminary check so that you get something more friendly than a unique-index violation report in the case complained of by André. And teach ChooseIndexName to avoid choosing autogenerated names that would draw such a failure. While it's not possible to make such a change in the back branches, it doesn't seem quite too late to put this into v11, so do so. Discussion: https://postgr.es/m/0c1001d4428f$0942b430$1bc81c90$@webkr.de
2018-09-04 19:45:35 +02:00
ALTER TABLE cities
ATTACH PARTITION cities_partdef DEFAULT;
Add hash partitioning. Hash partitioning is useful when you want to partition a growing data set evenly. This can be useful to keep table sizes reasonable, which makes maintenance operations such as VACUUM faster, or to enable partition-wise join. At present, we still depend on constraint exclusion for partitioning pruning, and the shape of the partition constraints for hash partitioning is such that that doesn't work. Work is underway to fix that, which should both improve performance and make partitioning pruning work with hash partitioning. Amul Sul, reviewed and tested by Dilip Kumar, Ashutosh Bapat, Yugo Nagata, Rajkumar Raghuwanshi, Jesper Pedersen, and by me. A few final tweaks also by me. Discussion: http://postgr.es/m/CAAJ_b96fhpJAP=ALbETmeLk1Uni_GFZD938zgenhF49qgDTjaQ@mail.gmail.com
2017-11-10 00:07:25 +01:00
</programlisting></para>
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
<para>
Fully enforce uniqueness of constraint names. It's been true for a long time that we expect names of table and domain constraints to be unique among the constraints of that table or domain. However, the enforcement of that has been pretty haphazard, and it missed some corner cases such as creating a CHECK constraint and then an index constraint of the same name (as per recent report from André Hänsel). Also, due to the lack of an actual unique index enforcing this, duplicates could be created through race conditions. Moreover, the code that searches pg_constraint has been quite inconsistent about how to handle duplicate names if one did occur: some places checked and threw errors if there was more than one match, while others just processed the first match they came to. To fix, create a unique index on (conrelid, contypid, conname). Since either conrelid or contypid is zero, this will separately enforce uniqueness of constraint names among constraints of any one table and any one domain. (If we ever implement SQL assertions, and put them into this catalog, more thought might be needed. But it'd be at least as reasonable to put them into a new catalog; having overloaded this one catalog with two kinds of constraints was a mistake already IMO.) This index can replace the existing non-unique index on conrelid, though we need to keep the one on contypid for query performance reasons. Having done that, we can simplify the logic in various places that either coped with duplicates or neglected to, as well as potentially improve lookup performance when searching for a constraint by name. Also, as per our usual practice, install a preliminary check so that you get something more friendly than a unique-index violation report in the case complained of by André. And teach ChooseIndexName to avoid choosing autogenerated names that would draw such a failure. While it's not possible to make such a change in the back branches, it doesn't seem quite too late to put this into v11, so do so. Discussion: https://postgr.es/m/0c1001d4428f$0942b430$1bc81c90$@webkr.de
2018-09-04 19:45:35 +02:00
To detach a partition from a partitioned table:
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
<programlisting>
Fix ALTER TABLE doc examples. Patch by Yugo Nagata <nagata@sraoss.co.jp>. Confirmed by Amit Langote, who is the original author of the document part.
2017-06-12 07:49:25 +02:00
ALTER TABLE measurement
Implement table partitioning. Table partitioning is like table inheritance and reuses much of the existing infrastructure, but there are some important differences. The parent is called a partitioned table and is always empty; it may not have indexes or non-inherited constraints, since those make no sense for a relation with no data of its own. The children are called partitions and contain all of the actual data. Each partition has an implicit partitioning constraint. Multiple inheritance is not allowed, and partitioning and inheritance can't be mixed. Partitions can't have extra columns and may not allow nulls unless the parent does. Tuples inserted into the parent are automatically routed to the correct partition, so tuple-routing ON INSERT triggers are not needed. Tuple routing isn't yet supported for partitions which are foreign tables, and it doesn't handle updates that cross partition boundaries. Currently, tables can be range-partitioned or list-partitioned. List partitioning is limited to a single column, but range partitioning can involve multiple columns. A partitioning "column" can be an expression. Because table partitioning is less general than table inheritance, it is hoped that it will be easier to reason about properties of partitions, and therefore that this will serve as a better foundation for a variety of possible optimizations, including query planner optimizations. The tuple routing based which this patch does based on the implicit partitioning constraints is an example of this, but it seems likely that many other useful optimizations are also possible. Amit Langote, reviewed and tested by Robert Haas, Ashutosh Bapat, Amit Kapila, Rajkumar Raghuwanshi, Corey Huinker, Jaime Casanova, Rushabh Lathia, Erik Rijkers, among others. Minor revisions by me.
2016-12-07 19:17:43 +01:00
DETACH PARTITION measurement_y2015m12;
</programlisting></para>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</refsect1>
First files for reference pages.
1998-05-13 07:34:00 +02:00
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<refsect1>
<title>Compatibility</title>
Markup and editing adjustments...
1998-09-16 16:43:12 +02:00
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<para>
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
The forms <literal>ADD</literal> (without <literal>USING INDEX</literal>),
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>DROP [COLUMN]</literal>, <literal>DROP IDENTITY</literal>, <literal>RESTART</literal>,
<literal>SET DEFAULT</literal>, <literal>SET DATA TYPE</literal> (without <literal>USING</literal>),
Identity columns This is the SQL standard-conforming variant of PostgreSQL's serial columns. It fixes a few usability issues that serial columns have: - CREATE TABLE / LIKE copies default but refers to same sequence - cannot add/drop serialness with ALTER TABLE - dropping default does not drop sequence - need to grant separate privileges to sequence - other slight weirdnesses because serial is some kind of special macro Reviewed-by: Vitaly Burovoy <vitaly.burovoy@gmail.com>
2017-04-06 14:33:16 +02:00
<literal>SET GENERATED</literal>, and <literal>SET <replaceable>sequence_option</replaceable></literal>
Allow SQL:2008 syntax ALTER TABLE ... ALTER COLUMN ... SET DATA TYPE alongside our traditional syntax.
2008-10-21 10:38:16 +02:00
conform with the SQL standard. The other forms are
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<productname>PostgreSQL</productname> extensions of the SQL standard.
ALTER TABLE rewrite. New cool stuff: * ALTER ... ADD COLUMN with defaults and NOT NULL constraints works per SQL spec. A default is implemented by rewriting the table with the new value stored in each row. * ALTER COLUMN TYPE. You can change a column's datatype to anything you want, so long as you can specify how to convert the old value. Rewrites the table. (Possible future improvement: optimize no-op conversions such as varchar(N) to varchar(N+1).) * Multiple ALTER actions in a single ALTER TABLE command. You can perform any number of column additions, type changes, and constraint additions with only one pass over the table contents. Basic documentation provided in ALTER TABLE ref page, but some more docs work is needed. Original patch from Rod Taylor, additional work from Tom Lane.
2004-05-05 06:48:48 +02:00
Also, the ability to specify more than one manipulation in a single
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<command>ALTER TABLE</command> command is an extension.
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</para>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<command>ALTER TABLE DROP COLUMN</command> can be used to drop the only
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
column of a table, leaving a zero-column table. This is an
extension of SQL, which disallows zero-column tables.
</para>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</refsect1>
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
<refsect1>
<title>See Also</title>
<simplelist type="inline">
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<member><xref linkend="sql-createtable"/></member>
Implement ALTER TABLE ADD UNIQUE/PRIMARY KEY USING INDEX. This feature allows a unique or pkey constraint to be created using an already-existing unique index. While the constraint isn't very functionally different from the bare index, it's nice to be able to do that for documentation purposes. The main advantage over just issuing a plain ALTER TABLE ADD UNIQUE/PRIMARY KEY is that the index can be created with CREATE INDEX CONCURRENTLY, so that there is not a long interval where the table is locked against updates. On the way, refactor some of the code in DefineIndex() and index_create() so that we don't have to pass through those functions in order to create the index constraint's catalog entries. Also, in parse_utilcmd.c, pass around the ParseState pointer in struct CreateStmtContext to save on notation, and add error location pointers to some error reports that didn't have one before. Gurjeet Singh, reviewed by Steve Singer and Tom Lane
2011-01-25 21:42:03 +01:00
</simplelist>
</refsect1>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</refentry>