Saltar al contenido principal

Uso de tipos enumerados de Postgres en esquemas 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 enumerados son estructuras de datos que contienen un conjunto predefinido y ordenado de valores. Por defecto, al usar field.Enum en tu esquema Ent, se utilizan tipos de cadena simples para representar los valores enumerados en PostgreSQL y SQLite. Sin embargo, en algunos casos, es preferible utilizar los tipos enumerados nativos que ofrece la base de datos.

Esta guía explica cómo definir un campo de esquema que utilice un tipo enumerado nativo de PostgreSQL y configurar la migración del esquema para gestionar tanto los enums de Postgres como el esquema Ent como una única unidad de migración usando Atlas.

[Función Pro de Atlas]

El soporte de Atlas para Esquema Compuesto utilizado en esta guía 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 utiliza principalmente para definir tipos Ent (objetos), sus campos, relaciones y lógica. Los tipos enumerados externos u otros objetos de base de datos no tienen representación en los modelos Ent. Un tipo enumerado de Postgres puede definirse una vez en tu esquema de Postgres y usarse múltiples veces en diferentes campos y modelos.

Para extender nuestro esquema PostgreSQL e incluir tanto tipos enumerados personalizados como tipos 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 archivo schema.sql que defina el tipo enumerado necesario. Alternativamente, puedes definir el tipo enumerado en el lenguaje HCL de Atlas Schema:

schema.sql
CREATE TYPE status AS ENUM ('active', 'inactive', 'pending');

2. En tu esquema Ent, define un campo enumerado que utilice el tipo ENUM subyacente de Postgres:

ent/schema/user.go
// Fields of the User.
func (User) Fields() []ent.Field {
    return []ent.Field{
        field.Enum("status").
            Values("active", "inactive", "pending").
            SchemaType(map[string]string{
                dialect.Postgres: "status",
            }),
    }
}
nota

Si un esquema con tipos específicos de driver se usa con otras bases de datos, Ent recurre al tipo predeterminado del driver (ej: TEXT en SQLite y ENUM (...) en MariaDB o MySQL).

3. Crea un archivo de configuración atlas.hcl simple con un composite_schema que incluya tanto tus tipos enumerados personalizados definidos en schema.sql como tu esquema 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 compuesto, podemos obtener su representación usando el comando atlas schema inspect, generar migraciones de esquema, aplicarlas a una base de datos y más. Aquí tienes algunos comandos para comenzar 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 enumerado status se define en el esquema antes de su uso en la columna users.status:

-- Create enum type "status"
CREATE TYPE "status" AS ENUM ('active', 'inactive', 'pending');
-- Create "users" table
CREATE TABLE "users" ("id" bigint NOT NULL GENERATED BY DEFAULT AS IDENTITY, "status" "status" 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 enum type "status"
CREATE TYPE "status" AS ENUM ('active', 'inactive', 'pending');
-- Create "users" table
CREATE TABLE "users" ("id" bigint NOT NULL GENERATED BY DEFAULT AS IDENTITY, "status" "status" 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.