Saltar al contenido principal

Uso de extensiones de Postgres 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 →

Las extensiones de Postgres son módulos complementarios que amplían la funcionalidad de la base de datos proporcionando nuevos tipos de datos, operadores, funciones, lenguajes procedurales y más.

Esta guía explica cómo definir un campo de esquema que utilice un tipo de datos proporcionado por la extensión PostGIS, y configurar la migración del esquema para gestionar tanto las instalaciones de extensiones Postgres como el esquema Ent como una única unidad de migración usando Atlas.

[Función Pro de Atlas]

El soporte de Atlas para Extensiones 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. Extensiones como postgis o hstore no tienen representación en el esquema Ent. Una extensión Postgres puede instalarse una vez en tu base de datos Postgres y utilizarse múltiples veces en diferentes esquemas.

Para extender nuestra migración de esquema PostgreSQL e incluir tanto extensiones como nuestros 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 las extensiones necesarias usadas en tu base de datos. Igualmente, puedes definir las extensiones en el lenguaje HCL de Atlas Schema:

schema.sql
-- Install PostGIS extension.
CREATE EXTENSION postgis;

2. En tu esquema Ent, define un campo que utilice el tipo de datos proporcionado por la extensión. En este ejemplo, usamos el tipo de datos GEOMETRY(Point, 4326) proporcionado por la extensión postgis:

ent/schema/user.go
// Fields of the User.
func (User) Fields() []ent.Field {
    return []ent.Field{
        field.Bytes("location").
            // Ideally, we would use a custom GoType
            // to represent the "geometry" type.
            SchemaType(map[string]string{
                dialect.Postgres: "GEOMETRY(Point, 4326)",
            }),
    }
}

3. Crea un archivo de configuración atlas.hcl simple con un composite_schema que incluya tanto las extensiones definidas en schema.sql como tu esquema Ent:

atlas.hcl
data "composite_schema" "app" {
  # Install extensions first (PostGIS).
  schema "public" {
    url = "file://schema.sql"
  }
  # Then, load the Ent schema.
  schema "public" {
    url = "ent://ent/schema"
  }
}

env "local" {
  src = data.composite_schema.app.url
  dev = "docker://postgis/latest/dev"
  format {
    migrate {
      diff = "{{ sql . \"  \" }}"
    }
  }
}

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:

-- Add new schema named "public"
CREATE SCHEMA IF NOT EXISTS "public";
-- Set comment to schema: "public"
COMMENT ON SCHEMA "public" IS 'standard public schema';
-- Create extension "postgis"
CREATE EXTENSION "postgis" WITH SCHEMA "public" VERSION "3.4.2";
-- Create "users" table
CREATE TABLE "public"."users" ("id" bigint NOT NULL GENERATED BY DEFAULT AS IDENTITY, "location" public.geometry(point,4326) NOT NULL, PRIMARY KEY ("id"));
[Las extensiones son objetos de nivel de base de datos]

Aunque el argumento SCHEMA es compatible con el comando CREATE EXTENSION, solo indica dónde se instalarán los objetos de la extensión. La extensión en sí se instala a nivel de base de datos y no puede cargarse múltiples veces en diferentes esquemas.

Por lo tanto, para evitar conflictos con otros esquemas, al trabajar con extensiones, el alcance de la migración debe establecerse a nivel de base de datos, donde los objetos se califican con el nombre del esquema. Por ello, se elimina search_path de la URL de la base de datos de desarrollo en el archivo atlas.hcl.

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 extension "postgis"
CREATE EXTENSION "postgis" WITH SCHEMA "public" VERSION "3.4.2";
-- Create "users" table
CREATE TABLE "public"."users" (
  "id" bigint NOT NULL GENERATED BY DEFAULT AS IDENTITY,
  "location" public.geometry(point,4326) 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, es necesario aplicar el esquema directamente en la base de datos sin generar un archivo de migración. Por ejemplo, al experimentar con cambios de esquema, al crear bases de datos para pruebas, etc. En estos casos, puedes usar el siguiente comando para aplicar el esquema directamente en la base de datos:

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

O utilizando el SDK de Atlas para Go:

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?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.