Saltar al contenido principal

Usar tipos de dominio en el esquema de Ent

[Traducción Beta No Oficial]

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

Los tipos de dominio en PostgreSQL son tipos de datos definidos por el usuario que extienden tipos existentes, permitiendo añadir restricciones que limitan los valores que pueden contener. Configurar un campo como tipo de dominio permite imponer reglas de integridad y validación de datos directamente a nivel de base de datos.

Esta guía explica cómo definir un campo del esquema como tipo de dominio en tu esquema de Ent y configurar la migración para gestionar tanto los dominios como el esquema de Ent como una única unidad de migración usando Atlas.

[Función Pro de Atlas]

El soporte de Atlas para tipos de dominio está disponible exclusivamente para usuarios Pro. Para usar esta función, ejecuta:

atlas login

Instalar Atlas​

[Traducción Beta No Oficial]

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

Para instalar la última versión de Atlas, simplemente ejecuta uno de los siguientes comandos en tu terminal, o visita el sitio web de Atlas:

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

Iniciar sesión en Atlas​

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

Esquema compuesto​

El paquete ent/schema se usa principalmente para definir tipos de Ent (objetos), sus campos, relaciones y lógica. Los tipos de dominio, u otros objetos de base de datos, no tienen representación en los modelos de Ent. Un tipo de dominio puede definirse una vez y usarse múltiples veces en diferentes campos y modelos.

Para extender nuestro esquema de PostgreSQL incluyendo tanto tipos de dominio personalizados como nuestros tipos de Ent, configuramos Atlas para leer el estado del esquema desde una fuente de datos de Esquema Compuesto. Sigue estos pasos para configurarlo en tu proyecto:

1. Crea un schema.sql que defina el tipo de dominio necesario. De igual forma, puedes configurar el tipo de dominio en el lenguaje HCL de Atlas Schema:

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

2. En tu esquema de Ent, define un campo que use el tipo de dominio solo en el dialecto PostgreSQL:

ent/schema/user.go
// Fields of the User.
func (User) Fields() []ent.Field {
    return []ent.Field{
        field.String("postal_code").
            SchemaType(map[string]string{
                dialect.Postgres: "us_postal_code",
            }),
    }
}
nota

Si un esquema con tipos específicos del controlador se usa con otras bases de datos, Ent recurre al tipo predeterminado del controlador (ej. "varchar").

3. Crea un archivo de configuración atlas.hcl simple con un composite_schema que incluya tanto tus tipos personalizados definidos en schema.sql como tu esquema de Ent:

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

Uso​

Tras configurar nuestro esquema, podemos obtener su representación usando el comando atlas schema inspect, generar migraciones, aplicarlas a una base de datos y más. Aquí tienes algunos comandos para empezar con Atlas:

Inspeccionar el esquema​

El comando atlas schema inspect se usa comúnmente para inspeccionar bases de datos. Sin embargo, también podemos usarlo para inspeccionar nuestro composite_schema e imprimir su representación SQL:

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

El comando anterior imprime el siguiente SQL. Observa que el tipo de dominio us_postal_code se define en el esquema antes de su uso en el campo postal_code:

-- 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" bigint NOT NULL GENERATED BY DEFAULT AS IDENTITY, "postal_code" "us_postal_code" NOT NULL, PRIMARY KEY ("id"));

Generar migraciones para el esquema​

Para generar una migración para el esquema, ejecuta el siguiente comando:

atlas migrate diff \
  --env local

Ten en cuenta que se crea un nuevo archivo de migración con el siguiente contenido:

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" bigint NOT NULL GENERATED BY DEFAULT AS IDENTITY, "postal_code" "us_postal_code" NOT NULL, PRIMARY KEY ("id"));

Aplicar las migraciones​

Para aplicar la migración generada a una base de datos, ejecuta el siguiente comando:

atlas migrate apply \
  --env local \
  --url "postgres://postgres:pass@localhost:5432/database?search_path=public&sslmode=disable"
[Aplicar el esquema directamente en la base de datos]

En ocasiones, puede ser necesario aplicar el esquema directamente a la base de datos sin generar un archivo de migración. Por ejemplo, al experimentar con cambios en el esquema, al preparar una base de datos para pruebas, etc. En estos casos, puedes usar el siguiente comando para aplicar el esquema directamente a la base de datos:

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

O bien, usando el SDK de Go de Atlas:

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",
    AutoApprove: true,
}); err != nil {
    log.Fatalf("failed to apply schema changes: %w", err)
}

El código de esta guía está disponible en GitHub.