Advanced Objects on DPG — Declarative PG

Full-Text Search

Mon, 01 Jan 0001 00:00:00 +0000

TEXT SEARCH CONFIGURATION

SCHEMA public {
 TEXT SEARCH CONFIGURATION english_unaccented (COPY = pg_catalog.english) {
 MAPPING FOR hword, hword_part, word
 WITH unaccent, english_stem;
 }
}

-- emits
CREATE TEXT SEARCH CONFIGURATION "public"."english_unaccented"
 (COPY = pg_catalog.english);

ALTER TEXT SEARCH CONFIGURATION "public"."english_unaccented"
 ALTER MAPPING FOR hword, hword_part, word
 WITH unaccent, english_stem;

TEXT SEARCH DICTIONARY

SCHEMA public {
 TEXT SEARCH DICTIONARY english_ispell (
 TEMPLATE = ispell,
 DictFile = english,
 AffFile = english,
 StopWords = english
 );
}

-- emits
CREATE TEXT SEARCH DICTIONARY "public"."english_ispell" (
 TEMPLATE = ispell,
 DictFile = english,
 AffFile = english,
 StopWords = english
);

TEXT SEARCH PARSER

SCHEMA public {
 TEXT SEARCH PARSER my_parser (
 START = prsd_start,
 GETTOKEN = prsd_nexttoken,
 END = prsd_end,
 LEXTYPES = prsd_lextype,
 HEADLINE = prsd_headline
 );
}

-- emits
CREATE TEXT SEARCH PARSER "public"."my_parser" (
 START = prsd_start,
 GETTOKEN = prsd_nexttoken,
 END = prsd_end,
 LEXTYPES = prsd_lextype,
 HEADLINE = prsd_headline
);

TEXT SEARCH TEMPLATE

SCHEMA public {
 TEXT SEARCH TEMPLATE ispell_template (
 LEXIZE = dispell_lexize,
 INIT = dispell_init
 );
}

-- emits
CREATE TEXT SEARCH TEMPLATE "public"."ispell_template" (
 LEXIZE = dispell_lexize,
 INIT = dispell_init
);

Diffing behaviour

Object	Change	SQL	Safety
Configuration	Add/change mapping	`ALTER TEXT SEARCH CONFIGURATION ALTER MAPPING`	`SAFE`
Configuration	Change template (`COPY`)	`DROP` + `CREATE`	`DESTRUCTIVE`
Dictionary	Any option change	`ALTER TEXT SEARCH DICTIONARY`	`SAFE`
Parser / Template	Any change	`DROP` + `CREATE`	`DESTRUCTIVE`

Logical Replication

Mon, 01 Jan 0001 00:00:00 +0000

PUBLICATION — specific tables

PUBLICATION user_data
 FOR TABLE users, profiles
 WITH (publish = 'insert, update, delete') {
 COMMENT 'Primary replication stream for user data';
}

-- emits
CREATE PUBLICATION "user_data"
 FOR TABLE "public"."users", "public"."profiles"
 WITH (publish = 'insert, update, delete');

COMMENT ON PUBLICATION "user_data" IS 'Primary replication stream for user data';

PUBLICATION — all tables

PUBLICATION all_tables FOR ALL TABLES;

-- emits
CREATE PUBLICATION "all_tables" FOR ALL TABLES;

PUBLICATION — filtered (column list + row filter)

PUBLICATION filtered_orders
 FOR TABLE orders (id, customer_id, status, total)
 WHERE (status != 'draft');

-- emits
CREATE PUBLICATION "filtered_orders"
 FOR TABLE "public"."orders" ("id", "customer_id", "status", "total")
 WHERE (status != 'draft');

SUBSCRIPTION

SUBSCRIPTION replica_users
 CONNECTION 'host=primary.db.internal dbname=myapp user=replicator'
 PUBLICATION user_data
 WITH (enabled = true, copy_data = true);

-- emits
CREATE SUBSCRIPTION "replica_users"
 CONNECTION 'host=primary.db.internal dbname=myapp user=replicator'
 PUBLICATION "user_data"
 WITH (enabled = true, copy_data = true);

Diffing behaviour

Change	SQL	Safety
Add table to publication	`ALTER PUBLICATION ADD TABLE`	`SAFE`
Remove table from publication	`ALTER PUBLICATION DROP TABLE`	`SAFE`
Change `WITH` options	`ALTER PUBLICATION SET`	`SAFE`
Publication owner changed	`ALTER PUBLICATION OWNER TO`	`SAFE`
Publication renamed (`RENAMED FROM`)	`ALTER PUBLICATION RENAME TO`	`CAUTION`
Remove publication	`DROP PUBLICATION`	`DESTRUCTIVE`
Change subscription connection/publication	`DROP SUBSCRIPTION` + `CREATE SUBSCRIPTION`	`DESTRUCTIVE`
Subscription owner changed	`ALTER SUBSCRIPTION OWNER TO`	`SAFE`
Subscription renamed (`RENAMED FROM`)	`ALTER SUBSCRIPTION RENAME TO`	`CAUTION`
Remove subscription	`DROP SUBSCRIPTION`	`DESTRUCTIVE`

Event Triggers

Mon, 01 Jan 0001 00:00:00 +0000

Event triggers are database-level (not cluster-level) and fire on DDL events. They are declared at the top level of a .dpg file (not inside a schema block).

Basic event trigger

EVENT TRIGGER prevent_drop_table
 ON sql_drop
 WHEN TAG IN ('DROP TABLE', 'DROP SCHEMA')
 EXECUTE FUNCTION abort_drop();

-- emits
CREATE EVENT TRIGGER "prevent_drop_table"
 ON sql_drop
 WHEN TAG IN ('DROP TABLE', 'DROP SCHEMA')
 EXECUTE FUNCTION abort_drop();

ddl_command_start trigger

EVENT TRIGGER audit_ddl
 ON ddl_command_start
 EXECUTE FUNCTION log_ddl_start();

-- emits
CREATE EVENT TRIGGER "audit_ddl"
 ON ddl_command_start
 EXECUTE FUNCTION log_ddl_start();

Available events

Event	Fires when
`ddl_command_start`	Before any DDL command executes
`ddl_command_end`	After any DDL command completes
`sql_drop`	Before objects are dropped
`table_rewrite`	Before a table is rewritten
`login` (PostgreSQL 17+)	Once per authenticated connection, before the session’s first query — `WHEN TAG IN (...)` doesn’t apply (no command tag to filter on)

Diffing behaviour

Change	SQL	Safety
New event trigger	`CREATE EVENT TRIGGER`	`SAFE`
Event/`WHEN TAG IN`/function changed	`DROP EVENT TRIGGER` + `CREATE EVENT TRIGGER`	`SAFE` (no data involved)
Enable state changed only	`ALTER EVENT TRIGGER ENABLE/DISABLE` (or `ENABLE REPLICA`/`ENABLE ALWAYS`)	`SAFE`
Owner changed	`ALTER EVENT TRIGGER OWNER TO`	`SAFE`
Renamed (`RENAMED FROM`)	`ALTER EVENT TRIGGER RENAME TO`	`CAUTION`
Removed event trigger	`DROP EVENT TRIGGER`	`SAFE`

Collations

Mon, 01 Jan 0001 00:00:00 +0000

ICU collation (non-deterministic)

Non-deterministic collations allow case-insensitive and accent-insensitive comparisons.

SCHEMA public {
 COLLATION case_insensitive (
 PROVIDER = icu,
 LOCALE = 'und-u-ks-level2',
 DETERMINISTIC = false
 );
}

-- emits
CREATE COLLATION "public"."case_insensitive" (
 PROVIDER = icu,
 LOCALE = 'und-u-ks-level2',
 DETERMINISTIC = false
);

Standard libc collation

SCHEMA public {
 COLLATION custom_en (
 PROVIDER = libc,
 LOCALE = 'en_US.UTF-8'
 );
}

-- emits
CREATE COLLATION "public"."custom_en" (
 PROVIDER = libc,
 LOCALE = 'en_US.UTF-8'
);

Collation copy

SCHEMA public {
 COLLATION my_collation (COPY = pg_catalog."default");
}

-- emits
CREATE COLLATION "public"."my_collation" (COPY = pg_catalog."default");

Diffing behaviour

Change	SQL	Safety
Owner changed	`ALTER COLLATION OWNER TO`	`SAFE`
Renamed (`RENAMED FROM`)	`ALTER COLLATION RENAME TO` (+ `SET SCHEMA` if schema-qualified)	`CAUTION`
`REFRESH VERSION` present in source	`ALTER COLLATION REFRESH VERSION` (re-emitted every apply while present)	`CAUTION`
Any other property change (`LOCALE`/`PROVIDER`/`RULES`/`FROM` target/etc.)	`DROP COLLATION` + `CREATE COLLATION`	`DESTRUCTIVE`

Columns using the collation must be re-indexed after a drop-and-recreate.

Operators

Mon, 01 Jan 0001 00:00:00 +0000

OPERATOR

SCHEMA public {
 OPERATOR === (
 LEFTARG = complex,
 RIGHTARG = complex,
 PROCEDURE = complex_eq,
 COMMUTATOR = ===,
 NEGATOR = !==,
 RESTRICT = eqsel,
 JOIN = eqjoinsel,
 HASHES,
 MERGES
 );
}

-- emits
CREATE OPERATOR "public".=== (
 LEFTARG = complex,
 RIGHTARG = complex,
 PROCEDURE = complex_eq,
 COMMUTATOR = ===,
 NEGATOR = !==,
 RESTRICT = eqsel,
 JOIN = eqjoinsel,
 HASHES,
 MERGES
);

Diffing behaviour — OPERATOR

Identity is (schema, symbol, leftarg_type, rightarg_type).

Casts

Mon, 01 Jan 0001 00:00:00 +0000

Implicit cast

SCHEMA public {
 CAST (mytype AS TEXT)
 WITH FUNCTION mytype_to_text(mytype)
 AS IMPLICIT;
}

-- emits
CREATE CAST (mytype AS text)
 WITH FUNCTION mytype_to_text(mytype)
 AS IMPLICIT;

Assignment cast

SCHEMA public {
 CAST (TEXT AS mytype)
 WITH FUNCTION text_to_mytype(TEXT)
 AS ASSIGNMENT;
}

-- emits
CREATE CAST (text AS mytype)
 WITH FUNCTION text_to_mytype(text)
 AS ASSIGNMENT;

Explicit cast (default)

SCHEMA public {
 CAST (mytype AS INTEGER)
 WITH FUNCTION mytype_to_int(mytype);
}

-- emits
CREATE CAST (mytype AS integer)
 WITH FUNCTION mytype_to_int(mytype);

INOUT cast

SCHEMA public {
 CAST (mytype AS TEXT) WITH INOUT;
}

-- emits
CREATE CAST (mytype AS text) WITH INOUT;

Diffing behaviour

Cast identity is (source_type, target_type). There is no ALTER CAST in PostgreSQL. Any property change emits DROP CAST + CREATE CAST — DESTRUCTIVE. Dependents are checked before the drop.

Statistics Objects

Mon, 01 Jan 0001 00:00:00 +0000

Extended statistics objects give the PostgreSQL planner information about correlations between columns that single-column statistics cannot capture.

Basic statistics object

SCHEMA public {
 STATISTICS orders_stats (dependencies, ndistinct, mcv)
 ON customer_id, created_at
 FROM orders;
}

-- emits
CREATE STATISTICS "public"."orders_stats" (dependencies, ndistinct, mcv)
 ON "customer_id", "created_at"
 FROM "public"."orders";

Statistics kinds reference

Kind	Description
`dependencies`	Functional dependency between columns
`ndistinct`	Multi-column distinct value count
`mcv`	Most common value combinations

Altering statistics target

SCHEMA public {
 STATISTICS orders_stats (dependencies, ndistinct, mcv)
 ON customer_id, created_at
 FROM orders {
 STATISTICS 200;
 }
}

-- emits
ALTER STATISTICS "public"."orders_stats" SET STATISTICS 200;

STATISTICS DEFAULT resets the target (emitted as SET STATISTICS -1).

Foreign Data

Mon, 01 Jan 0001 00:00:00 +0000

FOREIGN DATA WRAPPER

In the common case, FDWs are installed via extension (EXTENSION postgres_fdw;). The explicit declaration is reserved for custom C-implemented FDWs. Place in the cluster objects directory.

FOREIGN DATA WRAPPER myfdw
 HANDLER myfdw_handler
 VALIDATOR myfdw_validator;

-- emits
CREATE FOREIGN DATA WRAPPER myfdw
 HANDLER myfdw_handler
 VALIDATOR myfdw_validator;

SERVER

Servers are database-level objects that reference a foreign data wrapper.

SERVER analytics_warehouse
 FOREIGN DATA WRAPPER postgres_fdw
 OPTIONS (host 'warehouse.internal', dbname 'analytics', port '5432');

-- emits
CREATE SERVER "analytics_warehouse"
 FOREIGN DATA WRAPPER postgres_fdw
 OPTIONS (host 'warehouse.internal', dbname 'analytics', port '5432');

USER MAPPING

USER MAPPING FOR app_service
 SERVER analytics_warehouse
 OPTIONS (user 'fdw_user', password '{{vault:secret/fdw/analytics#password}}');

-- emits
CREATE USER MAPPING FOR "app_service"
 SERVER "analytics_warehouse"
 OPTIONS (user 'fdw_user', password '<resolved-at-apply-time>');

FOREIGN TABLE

SERVER and OPTIONS are PG SQL clauses on the CREATE FOREIGN TABLE signature — they stay in Part 1 per the two-part syntax rules.

Tablespaces

Mon, 01 Jan 0001 00:00:00 +0000

Tablespaces are cluster-level objects. Declare them in the cluster objects directory (e.g. production/cluster/tablespaces.dpg). See Project Structure.

Basic tablespace

TABLESPACE fast_ssd LOCATION '/mnt/nvme/pg_data';
TABLESPACE archive LOCATION '/mnt/hdd/pg_archive';

-- emits
CREATE TABLESPACE "fast_ssd" LOCATION '/mnt/nvme/pg_data';
CREATE TABLESPACE "archive" LOCATION '/mnt/hdd/pg_archive';

Tablespace with owner

OWNER sits inline in the native CREATE TABLESPACE clause, matching real PostgreSQL’s own grammar exactly — it is not a { } block directive here (unlike Table/View/etc., where OWNER has no place in the native CREATE statement).