DDL command handling matrix v5

The following table describes the utility or DDL commands that are allowed, the ones that are replicated, and the type of global lock they take when they're replicated.

For some more complex statements like ALTER TABLE, these can differ depending on the subcommands executed. Every such command has detailed explanation under the following table.

Command matrix

CommandAllowedReplicatedLock
ALTER AGGREGATEYYDDL
ALTER CASTYYDDL
ALTER COLLATIONYYDDL
ALTER CONVERSIONYYDDL
ALTER DATABASEYNN
ALTER DATABASE LINKYYDDL
ALTER DEFAULT PRIVILEGESYYDDL
ALTER DIRECTORYYYDDL
ALTER DOMAINYYDDL
ALTER EVENT TRIGGERYYDDL
ALTER EXTENSIONYYDDL
ALTER FOREIGN DATA WRAPPERYYDDL
ALTER FOREIGN TABLEYYDDL
ALTER FUNCTIONYYDDL
ALTER INDEXYYDDL
ALTER LANGUAGEYYDDL
ALTER LARGE OBJECTNNN
ALTER MATERIALIZED VIEWYNN
ALTER OPERATORYYDDL
ALTER OPERATOR CLASSYYDDL
ALTER OPERATOR FAMILYYYDDL
ALTER PACKAGEYYDDL
ALTER POLICYYYDDL
ALTER PROCEDUREYYDDL
ALTER PROFILEYYDetails
ALTER PUBLICATIONYYDDL
ALTER QUEUEYYDDL
ALTER QUEUE TABLEYYDDL
ALTER REDACTION POLICYYYDDL
ALTER RESOURCE GROUPYNN
ALTER ROLEYYDDL
ALTER ROUTINEYYDDL
ALTER RULEYYDDL
ALTER SCHEMAYYDDL
ALTER SEQUENCEDetailsYDML
ALTER SERVERYYDDL
ALTER SESSIONYNN
ALTER STATISTICSYYDDL
ALTER SUBSCRIPTIONYYDDL
ALTER SYNONYMYYDDL
ALTER SYSTEMYNN
ALTER TABLEDetailsYDetails
ALTER TABLESPACEYNN
ALTER TEXT SEARCH CONFIGURATIONYYDDL
ALTER TEXT SEARCH DICTIONARYYYDDL
ALTER TEXT SEARCH PARSERYYDDL
ALTER TEXT SEARCH TEMPLATEYYDDL
ALTER TRIGGERYYDDL
ALTER TYPEYYDDL
ALTER USER MAPPINGYYDDL
ALTER VIEWYYDDL
ANALYZEYNN
BEGINYNN
CHECKPOINTYNN
CLOSEYNN
CLOSE CURSORYNN
CLOSE CURSOR ALLYNN
CLUSTERYNN
COMMENTYDetailsDDL
COMMITYNN
COMMIT PREPAREDYNN
COPYYNN
COPY FROMYNN
CREATE ACCESS METHODYYDDL
CREATE AGGREGATEYYDDL
CREATE CASTYYDDL
CREATE COLLATIONYYDDL
CREATE CONSTRAINTYYDDL
CREATE CONVERSIONYYDDL
CREATE DATABASEYNN
CREATE DATABASE LINKYYDDL
CREATE DIRECTORYYYDDL
CREATE DOMAINYYDDL
CREATE EVENT TRIGGERYYDDL
CREATE EXTENSIONYYDDL
CREATE FOREIGN DATA WRAPPERYYDDL
CREATE FOREIGN TABLEYYDDL
CREATE FUNCTIONYYDDL
CREATE INDEXYYDML
CREATE LANGUAGEYYDDL
CREATE MATERIALIZED VIEWYNN
CREATE OPERATORYYDDL
CREATE OPERATOR CLASSYYDDL
CREATE OPERATOR FAMILYYYDDL
CREATE PACKAGEYYDDL
CREATE PACKAGE BODYYYDDL
CREATE POLICYYYDML
CREATE PROCEDUREYYDDL
CREATE PROFILEYYDetails
CREATE PUBLICATIONYYDDL
CREATE QUEUEYYDDL
CREATE QUEUE TABLEYYDDL
CREATE REDACTION POLICYYYDDL
CREATE RESOURCE GROUPYNN
CREATE ROLEYYDDL
CREATE ROUTINEYYDDL
CREATE RULEYYDDL
CREATE SCHEMAYYDDL
CREATE SEQUENCEDetailsYDDL
CREATE SERVERYYDDL
CREATE STATISTICSYYDDL
CREATE SUBSCRIPTIONYYDDL
CREATE SYNONYMYYDDL
CREATE TABLEDetailsYDDL
CREATE TABLE ASDetailsYDDL
CREATE TABLESPACEYNN
CREATE TEXT SEARCH CONFIGURATIONYYDDL
CREATE TEXT SEARCH DICTIONARYYYDDL
CREATE TEXT SEARCH PARSERYYDDL
CREATE TEXT SEARCH TEMPLATEYYDDL
CREATE TRANSFORMYYDDL
CREATE TRIGGERYYDDL
CREATE TYPEYYDDL
CREATE TYPE BODYYYDDL
CREATE USER MAPPINGYYDDL
CREATE VIEWYYDDL
DEALLOCATEYNN
DEALLOCATE ALLYNN
DECLARE CURSORYNN
DISCARDYNN
DISCARD ALLYNN
DISCARD PLANSYNN
DISCARD SEQUENCESYNN
DISCARD TEMPYNN
DOYNN
DROP ACCESS METHODYYDDL
DROP AGGREGATEYYDDL
DROP CASTYYDDL
DROP COLLATIONYYDDL
DROP CONSTRAINTYYDDL
DROP CONVERSIONYYDDL
DROP DATABASEYNN
DROP DATABASE LINKYYDDL
DROP DIRECTORYYYDDL
DROP DOMAINYYDDL
DROP EVENT TRIGGERYYDDL
DROP EXTENSIONYYDDL
DROP FOREIGN DATA WRAPPERYYDDL
DROP FOREIGN TABLEYYDDL
DROP FUNCTIONYYDDL
DROP INDEXYYDDL
DROP LANGUAGEYYDDL
DROP MATERIALIZED VIEWYNN
DROP OPERATORYYDDL
DROP OPERATOR CLASSYYDDL
DROP OPERATOR FAMILYYYDDL
DROP OWNEDYYDDL
DROP PACKAGEYYDDL
DROP PACKAGE BODYYYDDL
DROP POLICYYYDDL
DROP PROCEDUREYYDDL
DROP PROFILEYYDDL
DROP PUBLICATIONYYDDL
DROP QUEUEYYDDL
DROP QUEUE TABLEYYDDL
DROP REDACTION POLICYYYDDL
DROP RESOURCE GROUPYNN
DROP ROLEYYDDL
DROP ROUTINEYYDDL
DROP RULEYYDDL
DROP SCHEMAYYDDL
DROP SEQUENCEYYDDL
DROP SERVERYYDDL
DROP STATISTICSYYDDL
DROP SUBSCRIPTIONYYDDL
DROP SYNONYMYYDDL
DROP TABLEYYDML
DROP TABLESPACEYNN
DROP TEXT SEARCH CONFIGURATIONYYDDL
DROP TEXT SEARCH DICTIONARYYYDDL
DROP TEXT SEARCH PARSERYYDDL
DROP TEXT SEARCH TEMPLATEYYDDL
DROP TRANSFORMYYDDL
DROP TRIGGERYYDDL
DROP TYPEYYDDL
DROP TYPE BODYYYDDL
DROP USER MAPPINGYYDDL
DROP VIEWYYDDL
EXECUTEYNN
EXPLAINYDetailsDetails
FETCHYNN
GRANTYDetailsDDL
GRANT ROLEYYDDL
IMPORT FOREIGN SCHEMAYYDDL
LISTENYNN
LOADYNN
LOAD ROW DATAYYDDL
LOCK TABLEYNDetails
MOVEYNN
NOTIFYYNN
PREPAREYNN
PREPARE TRANSACTIONYNN
REASSIGN OWNEDYYDDL
REFRESH MATERIALIZED VIEWYNN
REINDEXYNN
RELEASEYNN
RESETYNN
REVOKEYDetailsDDL
REVOKE ROLEYYDDL
ROLLBACKYNN
ROLLBACK PREPAREDYNN
SAVEPOINTYNN
SECURITY LABELYDetailsDDL
SELECT INTODetailsYDDL
SETYNN
SET CONSTRAINTSYNN
SHOWYNN
START TRANSACTIONYNN
TRUNCATE TABLEYDetailsDetails
UNLISTENYNN
VACUUMYNN

Command Notes

ALTER SEQUENCE

Generally ALTER SEQUENCE is supported, but when using global sequences, some options have no effect.

ALTER SEQUENCE ... RENAME isn't supported on galloc sequences (only). ALTER SEQUENCE ... SET SCHEMA isn't supported on galloc sequences (only).

ALTER TABLE

Generally, ALTER TABLE commands are allowed. However, several subcommands aren't supported.

ALTER TABLE disallowed commands

Some variants of ALTER TABLE currently aren't allowed on a PGD node:

  • ADD COLUMN ... DEFAULT (non-immutable expression) This is not allowed because it currently results in different data on different nodes. See Adding a column for a suggested workaround.
  • ADD CONSTRAINT ... EXCLUDE Exclusion constraints are not supported. Exclusion constraints are a way to ensure that no two rows in a table have overlapping ranges. This is useful in a synchronous system where you can ensure that the constraint is enforced on all nodes at the same time. But in an asynchronous system, you can't ensure that the constraint is enforced on all nodes at the same time. This can lead to data inconsistency and changes that can't be replayed; therefore, exclusion constraints aren't supported.
  • ALTER TABLE ... SET WITH[OUT] OIDS Isn't supported for the same reasons as in CREATE TABLE.
  • ALTER COLUMN ... SET STORAGE external Is rejected if the column is one of the columns of the replica identity for the table.
  • RENAME Can't rename an Autopartitioned table.
  • SET SCHEMA Can't set the schema of an Autopartitioned table.
  • ALTER COLUMN ... TYPE Changing a column's type isn't supported if the command causes the whole table to be rewritten, which occurs when the change isn't binary coercible. Binary coercible changes might be allowed only one way. For example, the change from VARCHAR(128) to VARCHAR(256) is binary coercible and therefore allowed, whereas the change VARCHAR(256) to VARCHAR(128) isn't binary coercible and therefore normally disallowed. Nonreplicated ALTER COLUMN ... TYPE, can be allowed if the column is automatically castable to the new type (it doesn't contain the USING clause). An example follows. Table rewrites hold an AccessExclusiveLock for extended periods on larger tables, so such commands are likely to be infeasible on highly available databases in any case. See Changing a column's type for a suggested workaround.
  • ALTER TABLE ... ADD FOREIGN KEY Isn't supported if current user doesn't have permission to read the referenced table or if the referenced table has RLS restrictions enabled that the current user can't bypass.

The following example fails because it tries to add a constant value of type timestamp onto a column of type timestamptz. The cast between timestamp and timestamptz relies on the time zone of the session and so isn't immutable.

ALTER TABLE foo
  ADD expiry_date timestamptz DEFAULT timestamp '2100-01-01 00:00:00' NOT NULL;

Starting in PGD 3.7.4, you can add certain types of constraints, such as CHECK and FOREIGN KEY constraints, without taking a DML lock. But this requires a two-step process of first creating a NOT VALID constraint and then validating the constraint in a separate transaction with the ALTER TABLE ... VALIDATE CONSTRAINT command. See Adding a CONSTRAINT for more details.

ALTER TABLE locking

The following variants of ALTER TABLE take only DDL lock and not a DML lock:

  • ALTER TABLE ... ADD COLUMN ... (immutable) DEFAULT
  • ALTER TABLE ... ALTER COLUMN ... SET DEFAULT expression
  • ALTER TABLE ... ALTER COLUMN ... DROP DEFAULT
  • ALTER TABLE ... ALTER COLUMN ... TYPE if it doesn't require rewrite
  • ALTER TABLE ... ALTER COLUMN ... SET STATISTICS
  • ALTER TABLE ... VALIDATE CONSTRAINT
  • ALTER TABLE ... ATTACH PARTITION
  • ALTER TABLE ... DETACH PARTITION
  • ALTER TABLE ... ENABLE TRIGGER (ENABLE REPLICA TRIGGER still takes a DML lock)
  • ALTER TABLE ... CLUSTER ON
  • ALTER TABLE ... SET WITHOUT CLUSTER
  • ALTER TABLE ... SET ( storage_parameter = value [, ... ] )
  • ALTER TABLE ... RESET ( storage_parameter = [, ... ] )
  • ALTER TABLE ... OWNER TO

All other variants of ALTER TABLE take a DML lock on the table being modified. Some variants of ALTER TABLE have restrictions, noted below.

ALTER TABLE examples

This next example works because the type change is binary coercible and so doesn't cause a table rewrite. It executes as a catalog-only change.

CREATE TABLE foo (id BIGINT PRIMARY KEY, description VARCHAR(20));
ALTER TABLE foo ALTER COLUMN description TYPE VARCHAR(128);

However, making this change to reverse the command isn't possible because the change from VARCHAR(128) to VARCHAR(20) isn't binary coercible.

ALTER TABLE foo ALTER COLUMN description TYPE VARCHAR(20);

For workarounds, see Restricted DDL workarounds.

It's useful to provide context for different types of ALTER TABLE ... ALTER COLUMN TYPE (ATCT) operations that are possible in general and in nonreplicated environments.

Some ATCT operations update only the metadata of the underlying column type and don't require a rewrite of the underlying table data. This is typically the case when the existing column type and the target type are binary coercible. For example:

CREATE TABLE sample (col1 BIGINT PRIMARY KEY, col2 VARCHAR(128), col3 INT);
ALTER TABLE sample ALTER COLUMN col2 TYPE VARCHAR(256);

You can also change the column type to VARCHAR or TEXT data types because of binary coercibility. Again, this is just a metadata update of the underlying column type.

ALTER TABLE sample ALTER COLUMN col2 TYPE VARCHAR;
ALTER TABLE sample ALTER COLUMN col2 TYPE TEXT;

However, if you want to reduce the size of col2, then that leads to a rewrite of the underlying table data. Rewrite of a table is normally restricted.

ALTER TABLE sample ALTER COLUMN col2 TYPE VARCHAR(64);
ERROR:  ALTER TABLE ... ALTER COLUMN TYPE that rewrites table data may not affect replicated tables on a PGD node

To give an example with nontext types, consider col3 above with type INTEGER. An ATCT operation that tries to convert to SMALLINT or BIGINT fails in a similar manner as above.

ALTER TABLE sample ALTER COLUMN col3 TYPE bigint;
ERROR:  ALTER TABLE ... ALTER COLUMN TYPE that rewrites table data may not affect replicated tables on a PGD node

In both of these failing cases, there's an automatic assignment cast from the current types to the target types. However, there's no binary coercibility, which ends up causing a rewrite of the underlying table data.

In such cases, in controlled DBA environments, you can change the type of a column to an automatically castable one by adopting a rolling upgrade for the type of this column in a nonreplicated environment on all the nodes, one by one. Suppose the DDL isn't replicated and the change of the column type is to an automatically castable one. You can then allow the rewrite locally on the node performing the alter, along with concurrent activity on other nodes on this same table. You can then repeat this nonreplicated ATCT operation on all the nodes one by one to bring about the desired change of the column type across the entire EDB Postgres Distributed cluster. Because this involves a rewrite, the activity still takes the DML lock for a brief period and thus requires that the whole cluster is available. With these specifics in place, you can carry out the rolling upgrade of the nonreplicated alter activity like this:

-- foreach node in EDB Postgres Distributed cluster do:
SET bdr.ddl_replication TO FALSE;
ALTER TABLE sample ALTER COLUMN col2 TYPE VARCHAR(64);
ALTER TABLE sample ALTER COLUMN col3 TYPE BIGINT;
RESET bdr.ddl_replication;
-- done

Due to automatic assignment casts being available for many data types, this local nonreplicated ATCT operation supports a wide variety of conversions. Also, ATCT operations that use a USING clause are likely to fail because of the lack of automatic assignment casts. This example shows a few common conversions with automatic assignment casts:

-- foreach node in EDB Postgres Distributed cluster do:
SET bdr.ddl_replication TO FALSE;
ATCT operations to-from {INTEGER, SMALLINT, BIGINT}
ATCT operations to-from {CHAR(n), VARCHAR(n), VARCHAR, TEXT}
ATCT operations from numeric types to text types
RESET bdr.ddl_replication;
-- done

This example isn't an exhaustive list of possibly allowable ATCT operations in a nonreplicated environment. Not all ATCT operations work. The cases where no automatic assignment is possible fail even if you disable DDL replication. So, while conversion from numeric types to text types works in a nonreplicated environment, conversion back from text type to numeric types fails.

SET bdr.ddl_replication TO FALSE;
-- conversion from BIGINT to TEXT works
ALTER TABLE sample ALTER COLUMN col3 TYPE TEXT;
-- conversion from TEXT back to BIGINT fails
ALTER TABLE sample ALTER COLUMN col3 TYPE BIGINT;
ERROR:  ALTER TABLE ... ALTER COLUMN TYPE which cannot be automatically cast to new type may not affect replicated tables on a PGD node
RESET bdr.ddl_replication;

While the ATCT operations in nonreplicated environments support a variety of type conversions, the rewrite can still fail if the underlying table data contains values that you can't assign to the new data type. For example, suppose the current type for a column is VARCHAR(256) and you try a nonreplicated ATCT operation to convert it into VARCHAR(128). If there's any existing data in the table that's wider than 128 bytes, then the rewrite operation fails locally.

INSERT INTO sample VALUES (1, repeat('a', 200), 10);
SET bdr.ddl_replication TO FALSE;
ALTER TABLE sample ALTER COLUMN col2 TYPE VARCHAR(128);
INFO:  in rewrite
ERROR:  value too long for type character varying(128)

If underlying table data meets the characteristics of the new type, then the rewrite succeeds. However, replication might fail if other nodes that haven't yet performed the nonreplicated rolling data type upgrade introduce new data that is wider than 128 bytes concurrently to this local ATCT operation. This brings replication to a halt in the cluster. So be aware of the data type restrictions and characteristics at the database and application levels while performing these nonreplicated rolling data type upgrade operations. We strongly recommend that you perform and test such ATCT operations in controlled and fully aware DBA environments. These ATCT operations are asymmetric, and backing out certain changes that fail can lead to table rewrites that take a long time.

Also, you can't perform the implicit castable ALTER activity in transaction blocks.

ALTER TYPE

ALTER TYPE is replicated, but a global DML lock isn't applied to all tables that use that data type, since PostgreSQL doesn't record those dependencies. See Restricted DDL workarounds.

COMMENT ON

All variants of COMMENT ON are allowed, but COMMENT ON TABLESPACE/DATABASE/LARGE OBJECT isn't replicated.

CREATE PROFILE or ALTER PROFILE

The PASSWORD_VERIFY_FUNCTION associated with the profile should be IMMUTABLE if the function is SECURITY DEFINER. Such a CREATE PROFILE or ALTER PROFILE command will be replicated but subsequent CREATE USER or ALTER USER commands using this profile will break the replication due to the writer worker throwing the error: cannot change current role within security-restricted operation.

CREATE SEQUENCE

Generally CREATE SEQUENCE is supported, but when using global sequences, some options have no effect.

CREATE TABLE

Generally CREATE TABLE is supported, but CREATE TABLE WITH OIDS isn't allowed on a PGD node.

CREATE TABLE AS and SELECT INTO

CREATE TABLE AS and SELECT INTO are allowed only if all subcommands are also allowed.

EXPLAIN

Generally EXPLAIN is allowed, but because EXPLAIN ANALYZE can have side effects on the database, there are some restrictions on it.

EXPLAIN ANALYZE Replication

EXPLAIN ANALYZE follows replication rules of the analyzed statement.

EXPLAIN ANALYZE Locking

EXPLAIN ANALYZE follows locking rules of the analyzed statement.

GRANT and REVOKE

Generally GRANT and REVOKE statements are supported, however GRANT/REVOKE ON TABLESPACE/LARGE OBJECT aren't replicated.

LOCK TABLE

LOCK TABLE isn't replicated, but it might acquire the global DML lock when bdr.lock_table_locking is set on.

You can also use The bdr.global_lock_table() function to explicitly request a global DML lock.

SECURITY LABEL

All variants of SECURITY LABEL are allowed, but SECURITY LABEL ON TABLESPACE/DATABASE/LARGE OBJECT isn't replicated.

TRUNCATE Replication

TRUNCATE command is replicated as DML, not as a DDL statement. Whether the TRUNCATE on table is replicated depends on replication settings for each affected table.

TRUNCATE Locking

Even though TRUNCATE isn't replicated the same way as other DDL, it can acquire the global DML lock when bdr.truncate_locking is set to on.