Getting Started on DPG — Declarative PG

Installation

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

System Requirements

Requirement	Minimum
PostgreSQL target	14 or later
OS	Linux (amd64/arm64), macOS (amd64/arm64), Windows (amd64)

To build from source, a C compiler (GCC or Clang) and Go 1.25+ are also required — see Build from Source below.

Install from Binary

One-line install (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/thec1oud/dpg/master/scripts/install.sh | bash

This downloads the correct pre-built binary for your platform and installs it to /usr/local/bin (if sudo is available) or ~/.local/bin (otherwise).

Introduction

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

DPG is a declarative, state-based superset of PostgreSQL SQL. You describe what your database should be; the compiler figures out what needs to change and generates the minimal, safe set of DDL statements to reach that state.

The problem with imperative migrations

PostgreSQL DDL is fundamentally imperative. Migration files describe actions taken at a point in time, not the current intended state of the database:

Drift accumulates as production databases are patched and hotfixed outside the migration history.
To understand the current schema, you must mentally replay every migration file from the beginning.
Running a migration file twice will fail or corrupt state — idempotency is never guaranteed.
ALTER TABLE public.users ADD CONSTRAINT ... re-states the schema and table name in every alteration, even though the context is already known.

The DPG answer

Instead of writing commands, you write a description of the desired state. The compiler compares that description against a committed snapshot and generates the precise SQL delta. If the database already matches the description, the output is empty.

Quick Start

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

Core Concepts in 90 Seconds

Offline-first. dpg plan and dpg diff never touch a database. They compare .dpg source files against a committed snapshot. CI pipelines can review migrations before any database is reached.

Idempotent. Applying the same plan twice produces zero SQL on the second run.

Safety-classified. Every generated statement is tagged SAFE, CAUTION, or DESTRUCTIVE. Destructive operations are blocked by default; they require --allow-destructive to proceed.

Additive grants. DPG only emits GRANT. It never auto-revokes. Removing a GRANTS entry emits nothing — write an explicit REVOKES { } block to revoke.

Development Guide

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

Everything needed to build, test, and contribute to DPG.

Prerequisites

Tool	Minimum version	Required for	Notes
Go	1.25.6	Building	Must match `go.mod`; download from go.dev
GCC or Clang	any	Building	CGo required by `pg_query_go` (libpg_query C parser)
Git	2.x	Everything
Docker	20.x	Integration tests	Daemon must be running; pulls `postgres:16-alpine`
Hugo extended	0.147.0	Docs site	Must be the extended variant for Sass/SCSS
Node.js	20+	Docs site	PostCSS dependency for Docsy theme
npm	10+	Docs site	Ships with Node.js
staticcheck	latest	`make lint`	`go install honnef.co/go/tools/cmd/staticcheck@latest`

Why CGo? pg_query_go wraps libpg_query — the real PostgreSQL C parser extracted into a standalone library. DPG uses it so that every .dpg file is parsed by the exact same grammar as PostgreSQL itself. This rules out pure-Go cross-compilation; each target platform must be built natively on that architecture. The release CI uses platform-matched runners (ubuntu-24.04-arm for linux/arm64, macos-latest for darwin/arm64).

Editor Integration

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

DPG ships native plugins for VS Code, Neovim, Helix, and JetBrains IDEs. Each plugin provides:

Syntax highlighting — via the DPG tree-sitter grammar
Diagnostics, hover, go-to-definition, completions — powered by dpg-lsp
Format on save — runs dpg fmt before each write

Prerequisites

dpg

dpg must be on your PATH. See Installation.

dpg-lsp

dpg-lsp is the language server that powers diagnostics, hover, and completions. Install it once and all editors share it: