Using Composite Types in Ent Schema

Using Composite Types in Ent Schema

In PostgreSQL, a composite type is structured like a row or record, consisting of field names and their corresponding data types. Setting an Ent field as a composite type enables you to store complex and structured data in a single column.

This guide explains how to define a schema field type as a composite type in your Ent schema and configure the schema migration to manage both the composite types and the Ent schema as a single migration unit using Atlas.

Atlas Pro Feature

atlas login

Install Atlas

To install the latest release of Atlas, simply run one of the following commands in your terminal, or check out the Atlas website:

macOS + Linux
Homebrew
Docker
Windows

curl -sSf https://atlasgo.sh | sh

brew install ariga/tap/atlas

docker pull arigaio/atlas
docker run --rm arigaio/atlas --help

If the container needs access to the host network or a local directory, use the --net=host flag and mount the desired directory:

docker run --rm --net=host \
  -v $(pwd)/migrations:/migrations \
  arigaio/atlas migrate apply
  --url "mysql://root:pass@:3306/test"

Download the latest release and move the atlas binary to a file location on your system PATH.

$ atlas login a8m
You are now connected to "a8m" on Atlas Cloud.

Composite Schema

An ent/schema package is mostly used for defining Ent types (objects), their fields, edges and logic. Composite types, or any other database objects do not have representation in Ent models - A composite 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 composite types and our Ent 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:

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

Using SQL
Using HCL

schema.sql

CREATE TYPE address AS (
   street text,
   city   text
);

schema.hcl

schema "public" {}
composite "address" {
  schema = schema.public
  field "street" {
    type = text
  }
  field "city" {
    type = text
  }
}

In your Ent schema, define a field that uses the composite type only in PostgreSQL dialect:

Schema
Address Type

ent/schema/user.go

// Fields of the User.
func (User) Fields() []ent.Field {
    return []ent.Field{
        field.String("address").
            GoType(&Address{}).
            SchemaType(map[string]string{
                dialect.Postgres: "address",
            }),
    }
}

note

In case a schema with custom driver-specific types is used with other databases, Ent falls back to the default type used by the driver (e.g., “varchar”).

ent/schematype/address.go

type Address struct {
    Street, City string
}
var _ field.ValueScanner = (*Address)(nil)
// Scan implements the database/sql.Scanner interface.
func (a *Address) Scan(v interface{}) (err error) {
    switch v := v.(type) {
    case nil:
    case string:
        _, err = fmt.Sscanf(v, "(%q,%q)", &a.Street, &a.City)
    case []byte:
        _, err = fmt.Sscanf(string(v), "(%q,%q)", &a.Street, &a.City)
    }
    return
}
// Value implements the driver.Valuer interface.
func (a *Address) Value() (driver.Value, error) {
    return fmt.Sprintf("(%q,%q)", a.Street, a.City), nil
}

Create a simple atlas.hcl config file with a composite_schema that includes both your custom types defined in schema.sql and your Ent schema:

atlas.hcl

data "composite_schema" "app" {
  # Load first custom types first.
  schema "public" {
    url = "file://schema.sql"
  }
  # Second, load the Ent schema.
  schema "public" {
    url = "ent://ent/schema"
  }
}
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 address composite type is defined in the schema before its usage in the address field:

-- Create composite type "address"
CREATE TYPE "address" AS ("street" text, "city" text);
-- Create "users" table
CREATE TABLE "users" ("id" bigint NOT NULL GENERATED BY DEFAULT AS IDENTITY, "address" "address" NOT NULL, PRIMARY KEY ("id"));

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 composite type "address"
CREATE TYPE "address" AS ("street" text, "city" text);
-- Create "users" table
CREATE TABLE "users" ("id" bigint NOT NULL GENERATED BY DEFAULT AS IDENTITY, "address" "address" NOT NULL, PRIMARY KEY ("id"));

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)
}

The code for this guide can be found in GitHub.

Composite Types