Tables on DPG — Declarative PG

Overview

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

Tables follow the two-part syntax exactly: the ( ) column list is Part 1 (pure PostgreSQL CREATE TABLE syntax); the { } block is Part 2 (indexes, policies, triggers, grants, column attributes, lifecycle directives).

Minimal table

TABLE users (
 id BIGINT GENERATED ALWAYS AS IDENTITY,
 email TEXT NOT NULL,
 CONSTRAINT pk_users PRIMARY KEY (id),
 CONSTRAINT uq_users_email UNIQUE (email)
);

-- emits
CREATE TABLE "public"."users" (
 "id" bigint GENERATED ALWAYS AS IDENTITY,
 "email" text NOT NULL,
 CONSTRAINT "pk_users" PRIMARY KEY ("id"),
 CONSTRAINT "uq_users_email" UNIQUE ("email")
);

Full table with all sub-objects

TABLE users (
 id BIGINT GENERATED ALWAYS AS IDENTITY,
 email TEXT NOT NULL,
 status user_status NOT NULL DEFAULT 'active',
 created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
 CONSTRAINT pk_users PRIMARY KEY (id),
 CONSTRAINT uq_users_email UNIQUE (email)
)
{
 COMMENT 'Primary identity store';
 OWNER app_role;

 COLUMN email {
 COMMENT "Verified email address";
 STATISTICS 300;
 GRANTS { SELECT TO reporting_role; }
 }

 INDEXES {
 idx_email (email);
 idx_status (status) WHERE (status != 'deleted');
 }

 ENABLE ROW LEVEL SECURITY;

 POLICIES {
 view_self FOR SELECT USING (id = auth.uid());
 }

 TRIGGERS {
 after_email_change AFTER UPDATE OF email
 FOR EACH ROW
 WHEN (OLD.email IS DISTINCT FROM NEW.email)
 EXECUTE FUNCTION notify_email_change();
 }

 GRANTS {
 SELECT, INSERT, UPDATE TO app_service;
 SELECT TO app_readonly;
 }

 REVOKES {
 ALL PRIVILEGES FROM PUBLIC;
 }
}

-- emits
CREATE TABLE "public"."users" (
 "id" bigint GENERATED ALWAYS AS IDENTITY,
 "email" text NOT NULL,
 "status" user_status NOT NULL DEFAULT 'active',
 "created_at" timestamptz NOT NULL DEFAULT now(),
 CONSTRAINT "pk_users" PRIMARY KEY ("id"),
 CONSTRAINT "uq_users_email" UNIQUE ("email")
);

COMMENT ON TABLE "public"."users" IS 'Primary identity store';
COMMENT ON COLUMN "public"."users"."email" IS 'Verified email address';
ALTER TABLE "public"."users" OWNER TO "app_role";
ALTER TABLE "public"."users" ALTER COLUMN "email" SET STATISTICS 300;
ALTER TABLE "public"."users" ENABLE ROW LEVEL SECURITY;

CREATE POLICY "view_self" ON "public"."users"
 FOR SELECT USING (id = auth.uid());

CREATE TRIGGER "after_email_change"
 AFTER UPDATE OF "email" ON "public"."users"
 FOR EACH ROW
 WHEN (OLD.email IS DISTINCT FROM NEW.email)
 EXECUTE FUNCTION notify_email_change();

GRANT SELECT (email) ON TABLE "public"."users" TO "reporting_role";
GRANT SELECT, INSERT, UPDATE ON TABLE "public"."users" TO "app_service";
GRANT SELECT ON TABLE "public"."users" TO "app_readonly";
REVOKE ALL PRIVILEGES ON TABLE "public"."users" FROM PUBLIC;

CREATE INDEX "idx_email" ON "public"."users" ("email");
CREATE INDEX "idx_status" ON "public"."users" ("status") WHERE (status != 'deleted');

Both indexes are declared alongside the table’s own creation, so they’re emitted inside the same transaction, non-concurrently — PostgreSQL rejects CREATE INDEX CONCURRENTLY inside a transaction block.

Columns

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

Column definitions live in the ( ) list (Part 1). Per-column attributes that PostgreSQL expresses as ALTER TABLE ... ALTER COLUMN statements go in the COLUMN name { } block inside the table’s { } (Part 2).

Standard column types

TABLE products (
 id BIGINT GENERATED ALWAYS AS IDENTITY,
 sku TEXT NOT NULL,
 price NUMERIC(10,2) NOT NULL DEFAULT 0,
 tags TEXT[] NOT NULL DEFAULT '{}',
 metadata JSONB,
 created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
 CONSTRAINT pk_products PRIMARY KEY (id)
);

-- emits
CREATE TABLE "public"."products" (
 "id" bigint GENERATED ALWAYS AS IDENTITY,
 "sku" text NOT NULL,
 "price" numeric(10,2) NOT NULL DEFAULT 0,
 "tags" text[] NOT NULL DEFAULT '{}',
 "metadata" jsonb,
 "created_at" timestamptz NOT NULL DEFAULT now(),
 CONSTRAINT "pk_products" PRIMARY KEY ("id")
);

GENERATED ALWAYS AS (computed column)

TABLE order_items (
 quantity INTEGER NOT NULL,
 unit_price NUMERIC(10,2) NOT NULL,
 total NUMERIC(12,2) GENERATED ALWAYS AS (quantity * unit_price) STORED,
 CONSTRAINT pk_order_items PRIMARY KEY (order_item_id)
);

-- emits
CREATE TABLE "public"."order_items" (
 "quantity" integer NOT NULL,
 "unit_price" numeric(10,2) NOT NULL,
 "total" numeric(12,2) GENERATED ALWAYS AS (quantity * unit_price) STORED,
 CONSTRAINT "pk_order_items" PRIMARY KEY ("order_item_id")
);

GENERATED … AS IDENTITY (sequence-backed)

TABLE users (
 id_always BIGINT GENERATED ALWAYS AS IDENTITY,
 id_default BIGINT GENERATED BY DEFAULT AS IDENTITY (START WITH 1000 INCREMENT BY 1),
 CONSTRAINT pk PRIMARY KEY (id_always)
);

-- emits
CREATE TABLE "public"."users" (
 "id_always" bigint GENERATED ALWAYS AS IDENTITY,
 "id_default" bigint GENERATED BY DEFAULT AS IDENTITY (START WITH 1000 INCREMENT BY 1),
 CONSTRAINT "pk" PRIMARY KEY ("id_always")
);

COLUMN reference block

COLUMN name { } inside the table’s { } block holds attributes that PG expresses as ALTER TABLE ALTER COLUMN statements.

Constraints

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

Constraints may appear inline in the ( ) list or inside the { } block via a CONSTRAINT entry. Both placements are merged by name into one logical set before compilation.

Inline constraints

TABLE accounts (
 id UUID NOT NULL DEFAULT gen_random_uuid() CONSTRAINT pk_accounts PRIMARY KEY,
 slug TEXT NOT NULL CONSTRAINT uq_accounts_slug UNIQUE,
 org UUID NOT NULL CONSTRAINT fk_accounts_org REFERENCES organisations (id) ON DELETE CASCADE,
 CONSTRAINT ck_slug_len CHECK (length(slug) >= 3)
);

-- emits
CREATE TABLE "public"."accounts" (
 "id" uuid NOT NULL DEFAULT gen_random_uuid() CONSTRAINT "pk_accounts" PRIMARY KEY,
 "slug" text NOT NULL CONSTRAINT "uq_accounts_slug" UNIQUE,
 "org" uuid NOT NULL CONSTRAINT "fk_accounts_org"
 REFERENCES "public"."organisations" ("id") ON DELETE CASCADE,
 CONSTRAINT "ck_slug_len" CHECK (length(slug) >= 3)
);

Multi-column constraints (table-level only)

TABLE order_items (
 order_id BIGINT NOT NULL,
 product_id BIGINT NOT NULL,
 quantity INTEGER NOT NULL DEFAULT 1,
 CONSTRAINT pk_order_items PRIMARY KEY (order_id, product_id),
 CONSTRAINT uq_order_product UNIQUE (order_id, product_id)
);

-- emits
CREATE TABLE "public"."order_items" (
 "order_id" bigint NOT NULL,
 "product_id" bigint NOT NULL,
 "quantity" integer NOT NULL DEFAULT 1,
 CONSTRAINT "pk_order_items" PRIMARY KEY ("order_id", "product_id"),
 CONSTRAINT "uq_order_product" UNIQUE ("order_id", "product_id")
);

Constraint in `{ }` block

Constraints in the { } block are merged with those in ( ) by name.

Indexes

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

Indexes are declared in the INDEXES { } block inside a table’s { }. By default, DPG emits plain CREATE INDEX for additions on existing tables. Write CONCURRENTLY on an individual index to make it CREATE INDEX CONCURRENTLY instead — emitted as a non-transactional step after COMMIT.

UNIQUE and CONCURRENTLY are both prefix keywords, written before the index name — mirroring real PostgreSQL’s own CREATE UNIQUE INDEX CONCURRENTLY name ON table order exactly. CONCURRENTLY is a bare presence keyword, same as in real PostgreSQL: there is no CONCURRENTLY false and no project-wide setting that changes the default — writing the keyword is the only way an index is ever created concurrently.

Row Level Security

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

Enable RLS

TABLE orders ( ... )
{
 ENABLE ROW LEVEL SECURITY;
}

-- emits
ALTER TABLE "public"."orders" ENABLE ROW LEVEL SECURITY;

Force RLS (applies to table owner too)

TABLE orders ( ... )
{
 ENABLE ROW LEVEL SECURITY;
 FORCE ROW LEVEL SECURITY;
}

-- emits
ALTER TABLE "public"."orders" ENABLE ROW LEVEL SECURITY;
ALTER TABLE "public"."orders" FORCE ROW LEVEL SECURITY;

SELECT policy

TABLE orders ( ... )
{
 ENABLE ROW LEVEL SECURITY;
 POLICIES {
 view_own FOR SELECT USING (user_id = auth.uid());
 }
}

-- emits
ALTER TABLE "public"."orders" ENABLE ROW LEVEL SECURITY;
CREATE POLICY "view_own" ON "public"."orders"
 FOR SELECT USING (user_id = auth.uid());

INSERT policy

POLICIES {
 insert_own FOR INSERT WITH CHECK (user_id = auth.uid());
}

CREATE POLICY "insert_own" ON "public"."orders"
 FOR INSERT WITH CHECK (user_id = auth.uid());

UPDATE policy (USING + WITH CHECK)

POLICIES {
 update_own FOR UPDATE
 USING (user_id = auth.uid())
 WITH CHECK (user_id = auth.uid() AND status != 'locked');
}

CREATE POLICY "update_own" ON "public"."orders"
 FOR UPDATE
 USING (user_id = auth.uid())
 WITH CHECK (user_id = auth.uid() AND status != 'locked');

RESTRICTIVE policy

POLICIES {
 restrict_deleted AS RESTRICTIVE FOR ALL USING (deleted_at IS NULL);
}

CREATE POLICY "restrict_deleted" ON "public"."orders"
 AS RESTRICTIVE FOR ALL USING (deleted_at IS NULL);

Policy scoped to specific roles

POLICIES {
 admin_all FOR ALL
 TO admin_role
 USING (true);

 service_read FOR SELECT
 TO service_role, readonly_role
 USING (true);
}

CREATE POLICY "admin_all" ON "public"."orders"
 FOR ALL TO "admin_role" USING (true);

CREATE POLICY "service_read" ON "public"."orders"
 FOR SELECT TO "service_role", "readonly_role" USING (true);

Policy change behaviour

Adding a policy: CREATE POLICY — SAFE.
Changing a policy’s TO, USING, or WITH CHECK: ALTER POLICY — SAFE.
Changing a policy’s FOR command or AS PERMISSIVE/RESTRICTIVE: DROP POLICY + CREATE POLICY — CAUTION.
Removing a permissive policy: DROP POLICY — SAFE (it only narrows access).
Removing a restrictive policy: DROP POLICY — CAUTION (it widens access).
Enabling/disabling RLS: ALTER TABLE ENABLE/DISABLE ROW LEVEL SECURITY — CAUTION.

Triggers

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

Triggers are declared in the TRIGGERS { } block inside a table’s { }.

BEFORE INSERT row trigger

TABLE users ( ... )
{
 TRIGGERS {
 before_insert BEFORE INSERT
 FOR EACH ROW
 EXECUTE FUNCTION set_defaults();
 }
}

-- emits
CREATE TRIGGER "before_insert"
 BEFORE INSERT ON "public"."users"
 FOR EACH ROW
 EXECUTE FUNCTION set_defaults();

AFTER UPDATE OF specific columns

TRIGGERS {
 after_email_change AFTER UPDATE OF email
 FOR EACH ROW
 WHEN (OLD.email IS DISTINCT FROM NEW.email)
 EXECUTE FUNCTION notify_email_change();
}

CREATE TRIGGER "after_email_change"
 AFTER UPDATE OF "email" ON "public"."users"
 FOR EACH ROW
 WHEN (OLD.email IS DISTINCT FROM NEW.email)
 EXECUTE FUNCTION notify_email_change();

Statement-level trigger with transition tables

TRIGGERS {
 audit_changes AFTER INSERT OR UPDATE OR DELETE
 REFERENCING OLD TABLE AS old_rows NEW TABLE AS new_rows
 FOR EACH STATEMENT
 EXECUTE FUNCTION audit_table_changes();
}

CREATE TRIGGER "audit_changes"
 AFTER INSERT OR UPDATE OR DELETE ON "public"."users"
 REFERENCING OLD TABLE AS old_rows NEW TABLE AS new_rows
 FOR EACH STATEMENT
 EXECUTE FUNCTION audit_table_changes();

CONSTRAINT trigger

TRIGGERS {
 check_ref CONSTRAINT AFTER INSERT OR UPDATE
 FROM orders
 DEFERRABLE INITIALLY DEFERRED
 FOR EACH ROW
 EXECUTE FUNCTION check_ref_integrity();
}

CREATE CONSTRAINT TRIGGER "check_ref"
 AFTER INSERT OR UPDATE ON "public"."users"
 FROM "orders"
 DEFERRABLE INITIALLY DEFERRED
 FOR EACH ROW
 EXECUTE FUNCTION check_ref_integrity();

Trigger change behaviour

Adding a trigger: CREATE TRIGGER — SAFE.
Changing any trigger property: DROP TRIGGER + CREATE TRIGGER — CAUTION.
Removing a trigger: DROP TRIGGER — CAUTION (whatever the trigger enforced stops).

Partitioning

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

RANGE partitioned table

TABLE events (
 id BIGINT GENERATED ALWAYS AS IDENTITY,
 tenant_id UUID NOT NULL,
 event_type TEXT NOT NULL,
 payload JSONB,
 created_at TIMESTAMPTZ NOT NULL DEFAULT now()
) PARTITION BY RANGE (created_at)
{
 PARTITIONS {
 events_2024_q1 FOR VALUES FROM ('2024-01-01') TO ('2024-04-01');
 events_2024_q2 FOR VALUES FROM ('2024-04-01') TO ('2024-07-01');
 events_2024_q3 FOR VALUES FROM ('2024-07-01') TO ('2024-10-01');
 events_2024_q4 FOR VALUES FROM ('2024-10-01') TO ('2025-01-01');
 events_default DEFAULT;
 }
}

-- emits
CREATE TABLE "public"."events" (
 "id" bigint GENERATED ALWAYS AS IDENTITY,
 "tenant_id" uuid NOT NULL,
 "event_type" text NOT NULL,
 "payload" jsonb,
 "created_at" timestamptz NOT NULL DEFAULT now()
) PARTITION BY RANGE ("created_at");

CREATE TABLE "public"."events_2024_q1"
 PARTITION OF "public"."events"
 FOR VALUES FROM ('2024-01-01') TO ('2024-04-01');

CREATE TABLE "public"."events_2024_q2"
 PARTITION OF "public"."events"
 FOR VALUES FROM ('2024-04-01') TO ('2024-07-01');

CREATE TABLE "public"."events_2024_q3"
 PARTITION OF "public"."events"
 FOR VALUES FROM ('2024-07-01') TO ('2024-10-01');

CREATE TABLE "public"."events_2024_q4"
 PARTITION OF "public"."events"
 FOR VALUES FROM ('2024-10-01') TO ('2025-01-01');

CREATE TABLE "public"."events_default"
 PARTITION OF "public"."events" DEFAULT;

LIST partitioned table

TABLE orders_by_region (
 id BIGINT GENERATED ALWAYS AS IDENTITY,
 region TEXT NOT NULL
) PARTITION BY LIST (region)
{
 PARTITIONS {
 orders_north FOR VALUES IN ('NYC', 'BOS', 'PHI');
 orders_south FOR VALUES IN ('MIA', 'ATL', 'DAL');
 }
}

-- emits
CREATE TABLE "public"."orders_by_region" (
 "id" bigint GENERATED ALWAYS AS IDENTITY,
 "region" text NOT NULL
) PARTITION BY LIST ("region");

CREATE TABLE "public"."orders_north"
 PARTITION OF "public"."orders_by_region"
 FOR VALUES IN ('NYC', 'BOS', 'PHI');

CREATE TABLE "public"."orders_south"
 PARTITION OF "public"."orders_by_region"
 FOR VALUES IN ('MIA', 'ATL', 'DAL');

HASH partitioned table

TABLE sessions (
 id UUID NOT NULL DEFAULT gen_random_uuid(),
 user_id BIGINT NOT NULL
) PARTITION BY HASH (user_id)
{
 PARTITIONS {
 sessions_0 FOR VALUES WITH (MODULUS 4, REMAINDER 0);
 sessions_1 FOR VALUES WITH (MODULUS 4, REMAINDER 1);
 sessions_2 FOR VALUES WITH (MODULUS 4, REMAINDER 2);
 sessions_3 FOR VALUES WITH (MODULUS 4, REMAINDER 3);
 }
}

-- emits
CREATE TABLE "public"."sessions" (
 "id" uuid NOT NULL DEFAULT gen_random_uuid(),
 "user_id" bigint NOT NULL
) PARTITION BY HASH ("user_id");

CREATE TABLE "public"."sessions_0"
 PARTITION OF "public"."sessions"
 FOR VALUES WITH (MODULUS 4, REMAINDER 0);

-- ... (sessions_1, sessions_2, sessions_3 follow same pattern)

Sub-partitioning

TABLE events ( ... ) PARTITION BY RANGE (created_at)
{
 PARTITIONS {
 events_2024 FOR VALUES FROM ('2024-01-01') TO ('2025-01-01')
 PARTITION BY LIST (region) {
 PARTITIONS {
 events_2024_us FOR VALUES IN ('us-east', 'us-west');
 events_2024_eu FOR VALUES IN ('eu-west', 'eu-central');
 }
 };
 }
}

-- emits
CREATE TABLE "public"."events" ( ... ) PARTITION BY RANGE ("created_at");

CREATE TABLE "public"."events_2024"
 PARTITION OF "public"."events"
 FOR VALUES FROM ('2024-01-01') TO ('2025-01-01')
 PARTITION BY LIST ("region");

CREATE TABLE "public"."events_2024_us"
 PARTITION OF "public"."events_2024"
 FOR VALUES IN ('us-east', 'us-west');

CREATE TABLE "public"."events_2024_eu"
 PARTITION OF "public"."events_2024"
 FOR VALUES IN ('eu-west', 'eu-central');

Partition-local constraints (PostgreSQL 18+)

A partition can declare its own constraints, independent of the parent, by adding a trailing { } body to its PARTITIONS { } entry:

Tables on DPG — Declarative PG

Overview

Minimal table

Full table with all sub-objects

Columns

Standard column types

GENERATED ALWAYS AS (computed column)

GENERATED … AS IDENTITY (sequence-backed)

COLUMN reference block

Constraints

Inline constraints

Multi-column constraints (table-level only)

Constraint in { } block

Indexes

Row Level Security

Enable RLS

Force RLS (applies to table owner too)

SELECT policy

INSERT policy

UPDATE policy (USING + WITH CHECK)

RESTRICTIVE policy

Policy scoped to specific roles

Policy change behaviour

Triggers

BEFORE INSERT row trigger

AFTER UPDATE OF specific columns

Statement-level trigger with transition tables

CONSTRAINT trigger

Trigger change behaviour

Partitioning

RANGE partitioned table

LIST partitioned table

HASH partitioned table

Sub-partitioning

Partition-local constraints (PostgreSQL 18+)

Constraint in `{ }` block