Saltar al contenido
Logotipo de Aurabase
aurabase

Implementación

Migraciones sin tiempo de inactividad, reversión atómica, CI/CD a través de GitHub Acciones/GitLab/CLI y ramas de bases de datos: una copia de un proyecto para probar una migración o una política antes de la producción.

Explicación8 min leerNivel intermedioRevisado el 15 abr 2026

Esta página fue traducida automáticamente. La versión en inglés es autorizada.

Tres superficies de despliegue#

Un proyecto Aurabase expone tres superficies para implementar: Postgres esquema (migraciones SQL versionadas), funciones perimetrales (WASM + cron + trabajos), políticas y secretos (RLS, env vars, OAuth aplicaciones). Cada uno se impulsa de forma independiente a través de aura CLI.

La CLI (aura) es un binario único, también se puede instalar con npm install -g @aurabase/cli y admite ejecución en seco, mensajes de confirmación y vista previa de diferencias. Compatible con Linux/macOS/Windows.

Desarrollo, vista previa, producción.#

De forma predeterminada, un proyecto tiene dos entornos: dev (local, Kubernetes) y prod (nube). Para intentar un cambio en una copia de sus datos antes de la producción, cree una rama de base de datos ramas de base de datos.

fluxtext
LOCAL DEV
    $ ./start.sh              → full local stack (k3d)
    $ aura dev                → watch mode + types gen

BRANCH (copy of a project, deleted by its TTL)
    $ aura branch create pr-142 --from my-app --ttl 3d
    $ aura db push            → on the branch project, to try the migration
    $ aura branch delete pr-142

PRODUCTION
    merge to main             → CI run: aura db push
                              → aura deploy functions

SQL versionado, reversión atómica#

Las migraciones viven en aurabase/migrations. Un archivo por cambio, marca de tiempo en prefijo. La CLI aplica las migraciones que faltan al proyecto vinculado; regenere sus tipos TypeScript con npx @aurabase/gen después de un cambio.

terminalbash
# Crear una nueva migración
aura db migration new add_devices_table
# → aurabase/migrations/20260415120000_add_devices_table.sql

# Vea qué migraciones están aplicadas o pendientes y luego aplíquelas al proyecto vinculado
aura db status
aura db push

# Regenerar tipos TypeScript
npx @aurabase/gen --out src/aurabase.types.ts

# Listar migraciones aplicadas
aura db migration list
Atención

Migraciones sin tiempo de inactividad. Siga las reglas: agregue primero la columna que acepta valores NULL, el relleno separado y la restricción NOT NULL al final. La CLI no verifica la compatibilidad con versiones anteriores por usted: revise las declaraciones destructivas (drop column, alter column … type) antes de aura db push.

Ramas de base de datos#

Una rama es un nuevo proyecto clonado de un proyecto PostgreSQL existente: su esquema, políticas de seguridad a nivel de fila, funciones, activadores, vistas y (a menos que solicite solo el esquema) sus filas. Tiene su propia URL, claves API y base de datos, por lo que puede ejecutar una migración, probar una política o apuntarle una implementación preliminar sin tocar la fuente. Las ramas se eliminan automáticamente cuando finaliza su tiempo de vida.

clibash
# Desde el proyecto vinculado (enlace aura), 72 horas por defecto
aura branch create feat/new-checkout

# De otro proyecto, guardado 7 días.
aura branch create pr-142 --from my-app --ttl 7d

# Solo esquema: no se copia ninguna fila, las secuencias comienzan de nuevo
aura branch create schema-test --no-data

aura branch list                    # las ramas del proyecto vinculado
aura branch list --all              # cada rama de la organización
aura branch delete feat/new-checkout

aura branch create espera hasta que la rama esté lista, luego imprime su URL y sus claves API, se muestra solo una vez como las de aura projects create (--json las imprime para scripts). Utilice --no-wait para regresar de inmediato y sígalo con aura branch list. Una rama es un proyecto: vincule una carpeta con aura link --project-id <id> y ejecute aura db push allí para intentar una migración.

Qué es una rama, exactamente

Una rama es una copia realizada en el momento de la creación, no una réplica en vivo ni un clon de copia en escritura: nada fluye de regreso a la fuente ni desde ella posteriormente. La plataforma lee la fuente en una instantánea consistente y copia las filas en la base de datos de la sucursal, por lo que el tiempo es proporcional a los datos. En la pila de prueba local, se clonó una tabla de 333 MB de 350.000 filas en 14 segundos. Luego, una migración que funciona en la rama se aplica a producción con el aura db push habitual.

Límites, en su totalidad#

¿Quién puede crear?Miembros con el rol developer o más, de un proyecto PostgreSQL que esté activo y no hibernado. Se rechaza un proyecto MongoDB.
Bifurcación de una ramaRechazado: crea la rama desde su proyecto principal.
NombreLetras, dígitos, ., _, - y /, hasta 63 caracteres, únicos por proyecto entre las ramas activas (no distingue entre mayúsculas y minúsculas).
Tiempo de vivir72 horas por defecto, de 1 hora a 30 días (--ttl 1h a --ttl 30d). La sucursal vencida y su base de datos se eliminan automáticamente, aproximadamente un minuto después de la fecha límite. Puedes eliminarlo antes.
Límite del planUna rama no cuenta contra el límite de su proyecto (max_projects); tiene su propio límite de ramas activas por organización (max_branches): 1 en Gratis, 10 en Pro, 25 en Equipo. Pasado esto, se rechaza la creación con BRANCH_LIMIT_REACHED. Una rama fallida no cuenta. Consulte los límites de límites.
Tamaño de datosLas filas se transmiten por streaming, no se guardan en la memoria, por lo que no hay un límite máximo de 32 MiB. La clonación se rechaza, en unos segundos, cuando las tablas superan el límite de la implementación (2 GiB de forma predeterminada, BRANCH_CLONE_MAX_BYTES cuando aloja Aurabase): el mensaje indica el tamaño y sugiere --no-data. Un clon también se detiene después de 30 minutos.

Lo que no se clona#

  • Clonado: tablas y sus filas, tipos de columnas, valores predeterminados, columnas de identidad, secuencias y su valor actual, restricciones, índices, seguridad a nivel de fila (habilitada, forzada, políticas), funciones y procedimientos SQL, activadores, vistas y vistas materializadas, tipos de enumeración y privilegios sobre todos ellos.
  • No clonado: usuarios de autenticación, sesiones y configuración de autenticación; cubos y objetos de almacenamiento; funciones perimetrales, secretos, variables de entorno y trabajos cron; configuración de la tabla en tiempo real (volverlas a habilitar en la sucursal); comentarios de tablas y columnas, incluidas directivas @graphql; privilegios a nivel de columna; la activación pg_graphql (aura projects graphql-enable en la rama). Los objetos pertenecen a la función de administrador de la sucursal.
  • Rechazado (la rama estaría incompleta): tablas particionadas y heredadas, tablas foráneas, dominios, tipos compuestos y de rango, funciones agregadas, reglas de reescritura, claves foráneas que apuntan a otro esquema y extensiones distintas a las que la plataforma instala en cada proyecto.

Se crea una rama a partir del esquema tal como se lee justo antes de la copia. No cambie el esquema de la fuente (aura db push, DDL) mientras se crea una rama.

Cuando la creación falla#

Nada queda atrás. La copia se ejecuta en una única transacción en la base de datos de la sucursal; en caso de falla, se revierte, el proyecto de rama se elimina y aura branch create imprime el motivo (por ejemplo, el objeto que no se puede clonar). La rama fallida permanece visible en aura branch list durante 24 horas con su mensaje y su nombre vuelve a estar libre. Si el servicio de la base de datos se reinicia en medio de una copia, la rama se declara fallida y se elimina después de 45 minutos.

Tres integraciones listas#

La CLI funciona con cualquier CI. Aquí tenéis las recetas de las tres más habituales.

.github/workflows/deploy.ymlyaml
name: Deploy to Aurabase
on:
  push: { branches: [main] }

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @aurabase/cli   # o descargue el binario desde la página de lanzamiento
      - run: aura login --token ${{ secrets.AURA_PAT }}   # Token de acceso personal aura_pat_*
      - run: aura link ${{ vars.AURA_PROJECT_ID }}
      - run: aura db push
      - run: aura deploy functions

Vincule un proyecto por entorno (un proyecto de prueba y un proyecto de producción) y ejecute la misma canalización en cada uno. No hay ningún indicador --env: el destino es el proyecto al que está vinculada la carpeta.

Atómico, mediante migración descendente#

Cada migración 20260415_xxx.sql puede tener un archivo 20260415_xxx.down.sql al lado. aura db migration down [n] ejecuta el .down.sql de las últimas migraciones aplicadas n, las más recientes primero, y las elimina del historial; el comando verifica la respuesta del servidor y falla si no se revierte nada. Una migración sin .down.sql solo se elimina del historial y la CLI así lo indica.

rollbackbash
# Revertir la última migración aplicada (ejecuta su .down.sql)
aura db migration down

# Revertir los últimos tres
aura db migration down 3

# Arreglar el historial sin tocar el esquema (una migración aplicada a mano, una fallida)
aura db migration repair 20260415120000_add_devices_table.sql --applied

# Una migración fallida se cancela en su propia transacción: no hay nada que revertir.
# La recuperación en un momento dado de una base de datos completa pasa por copias de seguridad (restauración de copia de seguridad de aura db <id> --sí)
Atención

Recuperación de un momento determinado aún no tiene un comando de autoservicio. Para una restauración que realice usted mismo, utilice las instantáneas de aura db backup create / aura db backup restore <id> --yes; la restauración sobrescribe la base de datos, así que primero haga una copia de seguridad nueva.

para ir más lejos#