RFC DPG-1: Declarative PG

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

DPG Working Group D. Tsegaw
Request for Comments: 1 Independent
Category: Standards Track May 2026
ISSN: (N/A — project-internal specification)


 Declarative PG (DPG): A Declarative State-Based Superset
 of PostgreSQL DDL

Abstract

 This document specifies Declarative PG (DPG), a declarative,
 state-based superset of PostgreSQL SQL that compiles to idiomatic
 PostgreSQL DDL. DPG source files describe the desired state of a
 PostgreSQL database; the DPG compiler computes the minimal, safe,
 ordered set of DDL statements required to transition the current
 state to the desired state. This specification defines the DPG
 source language, the compilation pipeline, the snapshot interchange
 format, the migration output format, and all associated tooling
 behaviour.

Status of This Memo

 This document specifies a Standards Track protocol for the DPG
 project ecosystem. Distribution of this memo is unlimited.

 This document is the authoritative specification for DPG.
 Implementations MUST conform to every normative statement in this
 document.

Copyright Notice

 Copyright (c) 2026 Daniel Tsegaw. All rights reserved.

 Redistribution and use of this specification, with or without
 modification, is permitted provided that the above copyright notice
 and this permission notice appear in all copies.

1. Introduction
 1.1. Purpose and Scope
 1.2. Problem Statement
 1.3. Prior Art
 1.4. Core Design Tenets
 1.5. Terminology
2. Conventions Used in This Document
 2.1. Requirements Notation
 2.2. Syntax Notation
 2.3. Examples
3. Project Structure and Configuration
 3.1. Directory Layout
 3.2. Root dpg.toml
 3.3. Cluster dpg.toml
 3.4. Database dpg.toml
 3.5. Cluster-Level Objects Directory
 3.6. Discovery Algorithm
 3.7. Block Merge Conflict Resolution
 3.8. Minimum PostgreSQL Version Targeting
 3.9. Ignored Objects
4. Language Fundamentals
 4.1. Source File Format
 4.2. The Two-Part Syntax Model
 4.3. The No-Verb Mandate
 4.4. Structural Scoping
 4.5. Statement Terminators
 4.6. Dollar-Quoted String Parsing
 4.7. Macro Preprocessor
 4.8. Dual Definition Modes
 4.9. Block Merging
 4.10. Identifiers
5. Type System
 5.1. ENUM Types
 5.2. Composite Types
 5.3. Range Types
 5.4. Domain Types
 5.5. Base (Shell) Types
 5.6. Virtual Types
6. Schema and Namespace Objects
 6.1. SCHEMA
 6.2. EXTENSION
7. Tables
 7.1. Table Declaration Syntax
 7.2. Column Definitions
 7.3. Constraints
 7.4. The COLUMN Reference Block
 7.5. Column-Level Grants
 7.6. Column Renaming
 7.7. Indexes
 7.8. Row Level Security
 7.9. Triggers
 7.10. Table-Level Grants and Revocations
 7.11. Table Lifecycle Directives
 7.12. Unlogged and Foreign Tables
 7.13. Partitioned Tables
8. Views
 8.1. Regular Views
 8.2. Materialized Views
 8.3. Recursive Views
9. Functions and Procedures
 9.1. Function Declaration Syntax
 9.2. Function Attributes
 9.3. Procedures
 9.4. Aggregate Functions
 9.5. Function Body Diffing Semantics
10. Sequences
11. Access Control
 11.1. Roles
 11.2. Grants — The Additive Model
 11.3. Revocations
 11.4. Default Privileges
 11.5. Owner Impersonation at Object Creation
 11.6. Parameter Privileges
12. Full-Text Search Objects
 12.1. Text Search Configurations
 12.2. Text Search Dictionaries
 12.3. Text Search Parsers
 12.4. Text Search Templates
13. Logical Replication
 13.1. Publications
 13.2. Subscriptions
14. Advanced PostgreSQL Objects
 14.1. Event Triggers
 14.2. Collations
 14.3. Operators
 14.4. Operator Classes and Families
 14.5. Casts
 14.6. Extended Statistics Objects
 14.7. Tablespaces
 14.8. Foreign Data Wrappers
 14.9. Foreign Servers
 14.10. User Mappings
 14.11. Security Labels
15. Compilation Pipeline
 15.1. Phases Overview
 15.2. Phase 1 — File Discovery
 15.3. Phase 2 — Macro Preprocessing
 15.4. Phase 3 — Tokenization
 15.5. Phase 4a — PostgreSQL Parsing (Part 1)
 15.6. Phase 4b — Block Parsing (Part 2)
 15.7. Phase 5 — IR Construction
 15.8. Phase 6 — Merging
 15.9. Phase 7 — Dependency Resolution
 15.10. Phase 8 — Linting
 15.11. Phase 9 — Differencing
 15.12. Phase 10 — Emission
16. Snapshot Format
 16.1. Purpose and Placement
 16.2. Top-Level Fields
 16.3. Per-Object Snapshot Schema
 16.4. Versioning
 16.5. Further Object Records
 16.6. Cluster-Level Snapshot File
 16.7. Source Revision Detection
 16.8. Migration Log
 16.9. Ledger
 16.10. Preconditions
17. Migration Output Format
 17.1. Output Structure
 17.2. Safety Classification
 17.3. Execution Modes
 17.4. Idempotency Requirement
18. CLI Commands
 18.1. dpg plan
 18.2. dpg apply
 18.3. dpg verify
 18.4. dpg resolve
 18.5. dpg dump
 18.6. dpg diff
 18.7. dpg validate
 18.8. dpg fmt
 18.9. dpg portability
 18.10. dpg init
 18.11. dpg completion
 18.12. dpg docs
 18.13. dpg log
 18.14. Target Selection
19. The Linter
 19.1. Built-in Rules
 19.2. Configuration
 19.3. Rule Scope
20. Introspection Engine
 20.1. Catalog Tables Read
 20.2. Drift Detection
21. Per-Object Diff Algorithms
22. Dependency Ordering
 22.1. Topological Sort
 22.2. Circular Dependency Resolution
23. Out of Scope
24. Security Considerations
25. Feature Coverage Matrix
Appendix A. ABNF Grammar Summary
Appendix B. Complete Example Project
Appendix C. Error Code Reference
Appendix D. Supplementary Specifications
 D.1. Secret Resolution
 D.2. Name Maps
 D.3. SERIAL / BIGSERIAL / SMALLSERIAL Columns
Appendix E. Revision History
Appendix F. Standard SQL / PostgreSQL-Specific Classification
Normative References
Informative References
Author's Address

1. Introduction

1.1. Purpose and Scope

This document specifies the Declarative PG (DPG) language, its compilation model, and all associated tooling. DPG is a declarative, state-based superset of PostgreSQL SQL. A DPG source tree describes the desired state of one or more PostgreSQL databases. The DPG compiler ingests that description, compares it against a committed schema snapshot, and emits the minimal ordered set of PostgreSQL DDL statements required to transition the database to the desired state.

RFCs on DPG — Declarative PG

RFC DPG-1: Declarative PG

Table of Contents

1. Introduction

1.1. Purpose and Scope