Using Domain Types in GORM

PostgreSQL domain types are user-defined data types that extend existing ones, allowing you to add constraints that restrict the values they can hold. Setting a field type as a domain type enables you to enforce data integrity and validation rules at the database level.

This guide explains how to define a schema field type as a domain type in your GORM model and configure the schema migration to manage both the domains and the GORM model as a single migration unit using Atlas.

Atlas Pro Feature

Atlas support for Domain Types is available exclusively to Pro users. To use this feature, run:

atlas login

Getting started with Atlas and GORM

Before we continue to domain types, ensure you have installed the Atlas GORM Provider on your GORM project.

To set up, follow along the getting started guide for GORM and Atlas.

Composite Schema

The GORM package is mostly used for defining tables (our Go types) and interacting with the database. Domain types, or any other database objects do not have representation in GORM models - A domain type can be defined once, and may be used multiple times in different fields and models.

In order to extend our PostgreSQL schema to include both custom domain types and our GORM types, we configure Atlas to read the state of the schema from a Composite Schema data source. Follow the steps below to configure this for your project:

1. Create a schema.sql that defines the necessary domain type. In the same way, you can configure the domain type in Atlas Schema HCL language:

Using SQL
Using HCL

schema.sql
CREATE DOMAIN us_postal_code AS TEXT
CHECK(
  VALUE ~ '^\d{5}$'
  OR VALUE ~ '^\d{5}-\d{4}$'
);

schema.hcl
schema "public" {}

domain "us_postal_code" {
  schema = schema.public
  type   = text
  null   = true
  check "us_postal_code_check" {
    expr = "((VALUE ~ '^\\d{5}$'::text) OR (VALUE ~ '^\\d{5}-\\d{4}$'::text))"
  }
}

2. In your GORM model, define a field that uses the domain type only in PostgreSQL dialect:

models.go
type User struct {
    gorm.Model
    Name       string
    PostalCode string `gorm:"type:us_postal_code"`
}

3. In your atlas.hcl config file, add a composite_schema that includes both your custom types defined in schema.sql and your GORM model:

atlas.hcl
data "composite_schema" "app" {
  # Load custom types first.
  schema "public" {
    url = "file://schema.hcl"
  }
  # Then, load the GORM model.
  schema "public" {
    url = data.external_schema.gorm.url
  }
}

env "local" {
  src = data.composite_schema.app.url
  dev = "docker://postgres/15/dev?search_path=public"
}

Usage

After setting up our schema, we can get its representation using the atlas schema inspect command, generate migrations for it, apply them to a database, and more. Below are a few commands to get you started with Atlas:

Inspect the Schema

The atlas schema inspect command is commonly used to inspect databases. However, we can also use it to inspect our composite_schema and print the SQL representation of it:

atlas schema inspect \
  --env local \
  --url env://src \
  --format '{{ sql . }}'

The command above prints the following SQL. Note, the us_postal_code domain type is defined in the schema before its usage in the postal_code field:

-- Create domain type "us_postal_code"
CREATE DOMAIN "us_postal_code" AS text CONSTRAINT "us_postal_code_check" CHECK ((VALUE ~ '^\d{5}$'::text) OR (VALUE ~ '^\d{5}-\d{4}$'::text));
-- Create "users" table
CREATE TABLE "users" ("id" bigserial NOT NULL, "created_at" timestamptz NULL, "updated_at" timestamptz NULL, "deleted_at" timestamptz NULL, "name" text NULL, "postal_code" "us_postal_code" NULL, PRIMARY KEY ("id"));
-- Create index "idx_users_deleted_at" to table: "users"
CREATE INDEX "idx_users_deleted_at" ON "users" ("deleted_at");

Generate Migrations For the Schema

To generate a migration for the schema, run the following command:

atlas migrate diff \
  --env local

Note that a new migration file is created with the following content:

migrations/20240712090543.sql
-- Create domain type "us_postal_code"
CREATE DOMAIN "us_postal_code" AS text CONSTRAINT "us_postal_code_check" CHECK ((VALUE ~ '^\d{5}$'::text) OR (VALUE ~ '^\d{5}-\d{4}$'::text));
-- Create "users" table
CREATE TABLE "users" ("id" bigserial NOT NULL, "created_at" timestamptz NULL, "updated_at" timestamptz NULL, "deleted_at" timestamptz NULL, "name" text NULL, "postal_code" "us_postal_code" NULL, PRIMARY KEY ("id"));
-- Create index "idx_users_deleted_at" to table: "users"
CREATE INDEX "idx_users_deleted_at" ON "users" ("deleted_at");

Apply the Migrations

To apply the migration generated above to a database, run the following command:

atlas migrate apply \
  --env local \
  --url "postgres://postgres:pass@localhost:5432/database?search_path=public&sslmode=disable"

Apply the Schema Directly on the Database

Sometimes, there is a need to apply the schema directly to the database without generating a migration file. For example, when experimenting with schema changes, spinning up a database for testing, etc. In such cases, you can use the command below to apply the schema directly to the database:

atlas schema apply \
  --env local \
  --url "postgres://postgres:pass@localhost:5432/database?search_path=public&sslmode=disable"

Or, using the Atlas Go SDK:

ac, err := atlasexec.NewClient(".", "atlas")
if err != nil {
    log.Fatalf("failed to initialize client: %w", err)
}
// Automatically update the database with the desired schema.
// Another option, is to use 'migrate apply' or 'schema apply' manually.
if _, err := ac.SchemaApply(ctx, &atlasexec.SchemaApplyParams{
    Env: "local",
    URL: "postgres://postgres:pass@localhost:5432/database?search_path=public&sslmode=disable",
}); err != nil {
    log.Fatalf("failed to apply schema changes: %w", err)
}

Getting started with Atlas and GORM​

Composite Schema​

Usage​

Inspect the Schema​

Generate Migrations For the Schema​

Apply the Migrations​