Types on DPG — Declarative PG

ENUM

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

Basic ENUM

TYPE user_status AS ENUM ('active', 'suspended', 'deleted');

-- emits (new type)
CREATE TYPE "public"."user_status" AS ENUM ('active', 'suspended', 'deleted');

ENUM with comment

TYPE invoice_status AS ENUM ('draft', 'sent', 'paid', 'void', 'overdue') {
 COMMENT 'Billing lifecycle states for customer invoices';
}

-- emits
CREATE TYPE "public"."invoice_status" AS ENUM ('draft', 'sent', 'paid', 'void', 'overdue');
COMMENT ON TYPE "public"."invoice_status" IS 'Billing lifecycle states for customer invoices';

Adding a value

Add a value to the end of the list (or use BEFORE/AFTER positioning in source — the compiler preserves order).

Composite

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

Basic composite type

SCHEMA public {
 TYPE address AS (
 street TEXT,
 city TEXT,
 state CHAR(2),
 postal_code TEXT,
 country CHAR(2)
 );
}

-- emits
CREATE TYPE "public"."address" AS (
 "street" text,
 "city" text,
 "state" char(2),
 "postal_code" text,
 "country" char(2)
);

Adding an attribute

Adding an attribute emits ALTER TYPE ... ADD ATTRIBUTE — SAFE.

-- before
TYPE contact AS (name TEXT, email TEXT);

-- after (add phone)
TYPE contact AS (name TEXT, email TEXT, phone TEXT);

-- emits (SAFE)
ALTER TYPE "public"."contact" ADD ATTRIBUTE "phone" text;

Attribute comments and renames

Each attribute can carry its own { } block, written with PostgreSQL’s own ATTRIBUTE keyword. It accepts COMMENT and RENAMED FROM.

Range

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

Basic range type

SCHEMA public {
 TYPE float8range AS RANGE (
 SUBTYPE = float8,
 SUBTYPE_DIFF = float8mi
 );
}

-- emits
CREATE TYPE "public"."float8range" AS RANGE (
 SUBTYPE = float8,
 SUBTYPE_DIFF = float8mi
);

Range type with operator class and collation

SCHEMA public {
 TYPE ci_text_range AS RANGE (
 SUBTYPE = text,
 SUBTYPE_OPCLASS = text_pattern_ops,
 COLLATION = "und-u-ks-level2"
 );
}

-- emits
CREATE TYPE "public"."ci_text_range" AS RANGE (
 SUBTYPE = text,
 SUBTYPE_OPCLASS = text_pattern_ops,
 COLLATION = "und-u-ks-level2"
);

Any change to a range type’s parameters requires DROP TYPE CASCADE then CREATE TYPE — DESTRUCTIVE.

Domain

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

Basic domain

SCHEMA public {
 DOMAIN positive_integer AS INTEGER {
 DEFAULT 1;
 CONSTRAINT positive_only CHECK (VALUE > 0);
 CONSTRAINT reasonable_max CHECK (VALUE < 1000000);
 }
}

-- emits
CREATE DOMAIN "public"."positive_integer" AS integer
 DEFAULT 1
 CONSTRAINT "positive_only" CHECK (VALUE > 0)
 CONSTRAINT "reasonable_max" CHECK (VALUE < 1000000);

Domain with NOT NULL

SCHEMA public {
 DOMAIN email_address AS TEXT {
 NOT NULL;
 CONSTRAINT valid_email CHECK (VALUE ~ '^[^@]+@[^@]+\.[^@]+$');
 }
}

-- emits
CREATE DOMAIN "public"."email_address" AS text
 NOT NULL
 CONSTRAINT "valid_email" CHECK (VALUE ~ '^[^@]+@[^@]+\.[^@]+$');

Altering a domain constraint

Adding a new constraint emits ALTER DOMAIN ADD CONSTRAINT. Removing one emits ALTER DOMAIN DROP CONSTRAINT. Changing the base type or a NOT NULL constraint is DESTRUCTIVE.

Virtual

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

Virtual types are DPG DDL constructs that give a structural schema to JSON/JSONB columns and JSON array columns. They generate no PostgreSQL DDL — no CREATE TYPE, ALTER TYPE, or DROP TYPE is ever emitted. When a column or composite type attribute is typed as a virtual type, DPG resolves it to jsonb (or jsonb[]) in all generated SQL.

The structured body is stored in the snapshot so downstream consumers — ORMs, type-safe query builders — can read type information via the snapshot JSON or the pkg/dpg Go API.

Base (Shell) Type

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

Base types (also called shell types) are for C-implemented custom types. They require input and output functions already installed in the database.

Base type declaration

SCHEMA public {
 TYPE mytype (
 INPUT = mytype_in,
 OUTPUT = mytype_out,
 INTERNALLENGTH = 16,
 ALIGNMENT = double
 );
}

-- emits
CREATE TYPE "public"."mytype" (
 INPUT = mytype_in,
 OUTPUT = mytype_out,
 INTERNALLENGTH = 16,
 ALIGNMENT = double
);

Full base type with all options

SCHEMA public {
 TYPE complex (
 INPUT = complex_in,
 OUTPUT = complex_out,
 RECEIVE = complex_recv,
 SEND = complex_send,
 INTERNALLENGTH = 16,
 ALIGNMENT = double,
 STORAGE = plain,
 PASSEDBYVALUE
 );
}

-- emits
CREATE TYPE "public"."complex" (
 INPUT = complex_in,
 OUTPUT = complex_out,
 RECEIVE = complex_recv,
 SEND = complex_send,
 INTERNALLENGTH = 16,
 ALIGNMENT = double,
 STORAGE = plain,
 PASSEDBYVALUE
);

Any change to a base type requires DROP TYPE CASCADE then CREATE TYPE — DESTRUCTIVE.