Fundamentals on DPG — Declarative PG

Two-Part Syntax

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

Every DPG object has at most two parts: native PostgreSQL DDL with the CREATE verb removed (Part 1), and an optional { } block for things PostgreSQL expresses as separate statements (Part 2).

Rule of thumb: if PostgreSQL writes it as part of CREATE OBJECT, it is Part 1. If PostgreSQL writes it as a separate statement (CREATE INDEX, GRANT, COMMENT ON), it is Part 2.

Basic object — Part 1 only

TABLE simple_log (
 id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 message TEXT NOT NULL
);

-- emits
CREATE TABLE "public"."simple_log" (
 "id" bigint GENERATED ALWAYS AS IDENTITY CONSTRAINT "simple_log_pkey" PRIMARY KEY,
 "message" text NOT NULL
);

Object with a `{ }` block — Parts 1 and 2

TABLE users (
 id BIGINT GENERATED ALWAYS AS IDENTITY,
 email TEXT NOT NULL,
 CONSTRAINT pk_users PRIMARY KEY (id),
 CONSTRAINT uq_users_email UNIQUE (email)
)
{
 COMMENT 'Primary identity store';
 OWNER app_role;
 INDEXES { idx_email (email); }
 GRANTS { SELECT TO app_readonly; }
}

-- 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")
);

CREATE INDEX "idx_email" ON "public"."users" ("email");

COMMENT ON TABLE "public"."users" IS 'Primary identity store';
ALTER TABLE "public"."users" OWNER TO "app_role";
GRANT SELECT ON TABLE "public"."users" TO "app_readonly";

Since idx_email is declared alongside its own brand-new table, it’s created inside the same transaction as the CREATE TABLE — PostgreSQL rejects CREATE INDEX CONCURRENTLY inside a transaction block, so DPG never emits CONCURRENTLY here, even if the index had written it explicitly. See Indexes for CONCURRENTLY on indexes added to an already-existing table.

Project Structure

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

A DPG project maps one-to-one onto the topology of a PostgreSQL deployment. The directory structure encodes clusters and databases; .dpg files are scoped to their containing database automatically.

Directory layout

myproject/
├── dpg.toml # root config
│
├── production/ # cluster directory
│ ├── dpg.toml # cluster config (connection URL, options)
│ ├── cluster/ # cluster-level objects (roles, tablespaces)
│ │ ├── roles.dpg
│ │ └── tablespaces.dpg
│ │
│ └── myapp/ # database directory
│ ├── dpg.toml # database config (name, default schema)
│ ├── extensions.dpg
│ └── schemas/
│ └── public/
│ ├── types.dpg
│ ├── tables/
│ │ ├── users.dpg
│ │ └── orders.dpg
│ ├── views.dpg
│ └── functions.dpg
│
└── .dpg/
 ├── snapshots/
 │ └── production/
 │ └── myapp.json # committed snapshot — source of truth for diffing
 └── migrations/
 └── production/
 └── myapp/
 ├── 20260101T120000Z-4f0c2b9e1d7a.sql # migration log (committed)
 └── 20260101T120000Z-4f0c2b9e1d7a.json

Discovery rules:

Macros

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

Macros are source-level text fragments defined once and spread inline at any number of call sites. The preprocessor expands them before parsing — the compiler sees only the expanded result.

MACRO declarations generate no SQL. They must appear at the top level of a .dpg file, not inside blocks.

Paren-body macro — column fragments

A paren-body macro spreads into a ( ) column list.

MACRO common_timestamps (
 created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
 updated_at TIMESTAMPTZ
)

TABLE accounts (
 id UUID NOT NULL DEFAULT gen_random_uuid(),
 name TEXT NOT NULL,
 ...common_timestamps,
 CONSTRAINT pk_accounts PRIMARY KEY (id)
);

-- emits (macro expanded inline)
CREATE TABLE "public"."accounts" (
 "id" uuid NOT NULL DEFAULT gen_random_uuid(),
 "name" text NOT NULL,
 "created_at" timestamptz NOT NULL DEFAULT now(),
 "updated_at" timestamptz,
 CONSTRAINT "pk_accounts" PRIMARY KEY ("id")
);

Brace-body macro — block fragments

A brace-body macro spreads into a { } block.

Snapshots & Diffing

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

DPG never requires a live database connection to generate a migration. The primary workflow diffs .dpg source files against a committed JSON snapshot.

Workflow

.dpg source files ──compile──▶ desired state
 │
 ▼ diff
.dpg/snapshots/prod/myapp.json ───────▶│
 ▼
 migration SQL

dpg apply executes the SQL, records it in the migration log and updates the snapshot atomically. The snapshot is always the post-apply state.

Migration log

The snapshot says what state the source has been migrated to; the migration log says how a database gets there. Each migration is <id>.sql (the SQL as dpg plan prints it) beside <id>.json, which names the migration it follows and the snapshot change it made:

Name Maps

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

Name Maps let you annotate DPG schema objects with the naming convention each downstream tool should apply to them. ORM generators (Prisma, Drizzle), type-safe query builders (sqlc), and API code generators can read these annotations from the snapshot and produce identifiers in the right casing for their target language — without touching the DPG source.

Name maps are metadata only: they do not affect generated PostgreSQL DDL and produce no SQL migration steps. They are serialised into the snapshot JSON for downstream consumers.

Fundamentals on DPG — Declarative PG

Two-Part Syntax

Basic object — Part 1 only

Object with a { } block — Parts 1 and 2

Project Structure

Directory layout

Macros

Paren-body macro — column fragments

Brace-body macro — block fragments

Snapshots & Diffing

Workflow

Migration log

Name Maps

Object with a `{ }` block — Parts 1 and 2