Configuración de Lakebase Postgres

AppKit se conecta a Lakebase Postgres mediante un recurso postgres declarado en databricks.yml y la variable LAKEBASE_ENDPOINT definida en app.yaml.

Esta página explica la configuración en AppKit. Para obtener información sobre Lakebase en sí (proyectos, branches, autoscaling, escalado a cero), consulta la documentación de Lakebase o la agent skill databricks-lakebase.

Valores de conexión

Databricks Apps inyecta la mayoría de los valores de conexión durante el arranque. LAKEBASE_ENDPOINT es la excepción: se declara en app.yaml mediante valueFrom: postgres y se resuelve en el arranque a partir del recurso postgres:

env:
  - name: LAKEBASE_ENDPOINT
    valueFrom: postgres

En el desarrollo local, estos valores provienen de tu archivo .env. En Configuración local se explica cómo completarlos.

Manifiesto de plugins

Cuando registras el plugin lakebase() en createApp, AppKit genera appkit.plugins.json, que declara los recursos que necesita el plugin. Ejecuta npx @databricks/appkit plugin sync --write para regenerarlo después de añadir o modificar plugins:

npx @databricks/appkit plugin sync --write

Esto se ejecuta automáticamente durante npm run dev y npm run build. Haz commit del archivo junto con tu código.

La referencia de configuración de AppKit detalla los bindings de recursos de plugins en app.yaml.

Jerarquía de recursos

Lakebase Postgres organiza los recursos en proyectos que contienen branches, y cada branch contiene computes y bases de datos.

projects/{project_id}
  └── branches/{branch_id}
        ├── endpoints/{endpoint_id}   (compute)
        └── databases/{database_id}

• Project: contenedor de nivel superior. Se crea con databricks postgres create-project.
• Branch: entorno de base de datos aislado. Los proyectos nuevos incluyen una branch production predeterminada con una base de datos databricks_postgres.
• Compute: aporta capacidad de procesamiento y memoria a una branch. Cada branch recibe automáticamente un compute primary de lectura y escritura. Se pueden añadir réplicas de solo lectura para escalar las lecturas.
• Database: una base de datos PostgreSQL dentro de una branch. Para listarlas, usa databricks postgres list-databases <branch>.

La CLI y la API denominan endpoints a los computes (ENDPOINT_TYPE_READ_WRITE para lectura y escritura, ENDPOINT_TYPE_READ_ONLY para réplicas de lectura). Los comandos y las rutas de recursos de este documento emplean ese término.

La referencia de la CLI de postgres abarca todos los comandos databricks postgres.

Branching

Las branches crean entornos de base de datos aislados. Al crear una branch, Lakebase Postgres copia el esquema y los datos de la branch de origen mediante copy-on-write. Las nuevas branches se crean de forma instantánea y solo pagas por los datos que modifiques.

Cada nueva branch obtiene un endpoint de lectura y escritura primary en projects/{project_id}/branches/{branch_id}/endpoints/primary, que hereda los default_endpoint_settings del proyecto. Usa create-endpoint para añadir réplicas de lectura (ENDPOINT_TYPE_READ_ONLY).

Las branches requieren una política de expiración (ttl, expire_time o no_expiry: true). En Branch expiration se detallan todas las opciones. Para los comandos de la CLI, consulta los ejemplos de Feature branches.

Autoscaling

Los computes escalan automáticamente entre un mínimo y un máximo configurados de unidades de compute (CU). El rango se define por proyecto o por endpoint. Los valores de CU predeterminados, el tamaño máximo de compute y la restricción mín./máx. son configuraciones de Lakebase que cambian con el tiempo, así que consulta Autoscaling para conocer los valores actuales.

El escalado dentro del rango configurado se produce sin interrumpir las conexiones. Cambiar el mínimo o el máximo puede provocar una breve interrupción.

databricks postgres update-endpoint \
  projects/my-project/branches/production/endpoints/primary \
  "spec.autoscaling_limit_min_cu,spec.autoscaling_limit_max_cu" \
  --json '{"spec": {"autoscaling_limit_min_cu": 1.0, "autoscaling_limit_max_cu": 8.0}}'

Escalado a cero

El escalado a cero suspende los computes inactivos para eliminar costos. Cuando llega una nueva consulta, el compute se reanuda automáticamente (normalmente en unos pocos cientos de milisegundos).

El tiempo de espera predeterminado es de 24 horas. Puedes establecer cualquier valor entre 60 segundos y 7 días. En las branches de desarrollo, los tiempos de espera más cortos (por ejemplo, 30 minutos) reducen aún más los costos. Las aplicaciones que se conecten a un compute escalado a cero notarán una breve pausa en la primera consulta. Implementa lógica de reintento de conexión en tu aplicación.

Cuando un compute se reanuda, el contexto de la sesión se restablece (tablas temporales, sentencias preparadas, configuración de sesión, pools de conexiones).

databricks postgres update-project \
  projects/my-project \
  "spec.default_endpoint_settings" \
  --json '{"spec": {"default_endpoint_settings": {"suspend_timeout_duration": "300s"}}}'

databricks postgres update-endpoint \
  projects/my-project/branches/production/endpoints/primary \
  "spec.suspension" \
  --json '{"spec": {"suspend_timeout_duration": "300s"}}'

databricks postgres update-endpoint \
  projects/my-project/branches/production/endpoints/primary \
  "spec.suspension" \
  --json '{"spec": {"no_suspension": true}}'

Qué sigue

Consulta Desarrollo con Lakebase Postgres para conocer la configuración local, las ramas Feature branch y la API completa del plugin, o explora el catálogo de plantillas para ver patrones completos.