Guía de la API de escalado automático de Lakebase

Importante

El escalado automático de Lakebase es la versión más reciente de Lakebase, con proceso de escalado automático, escalado a cero, bifurcación y restauración instantánea. Para ver las regiones admitidas, consulte Disponibilidad de regiones. Si es un usuario aprovisionado de Lakebase, consulte Aprovisionamiento de Lakebase.

En esta página se proporciona información general sobre la API de escalado automático de Lakebase, incluida la autenticación, los puntos de conexión disponibles y los patrones comunes para trabajar con la API REST, la CLI de Databricks y los SDK de Databricks (Python, Java, Go).

Para obtener la referencia de API completa, consulte la documentación de la API de Postgres.

Importante

La API de Postgres de Lakebase está en beta. Los puntos de conexión de API, los parámetros y los comportamientos están sujetos a cambios.

Autenticación

La API de escalado automático de Lakebase usa la autenticación de OAuth de nivel de área de trabajo para administrar la infraestructura del proyecto (crear proyectos, configurar opciones, etc.).

Nota:

Dos tipos de conectividad: esta API es para la administración de plataformas (creación de proyectos, ramas, procesos). Para acceder a la base de datos (conectar para consultar datos):

Clientes SQL (psql, pgAdmin, DBeaver): utilice tokens OAuth de Lakebase o contraseñas de Postgres. Consulte Autenticación.
Data API (RESTful HTTP): use tokens de OAuth de Lakebase. Consulte Api de datos.
Controladores del lenguaje de programación (psycopg, SQLAlchemy, JDBC): use tokens de OAuth de Lakebase o contraseñas de Postgres. Consulte Inicio rápido.

Para obtener una explicación completa de estas dos capas de autenticación, consulte Arquitectura de autenticación.

Configuración de la autenticación

Autenticación mediante la CLI de Databricks:

databricks auth login --host https://your-workspace.cloud.databricks.com

Siga las indicaciones del explorador para iniciar sesión. La CLI almacena en caché el token de OAuth en ~/.databricks/token-cache.json.

A continuación, elija el método de acceso:

SDK de Python

El SDK usa la autenticación unificada y controla automáticamente los tokens de OAuth:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

SDK de Java

El SDK usa la autenticación unificada y controla automáticamente los tokens de OAuth:

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

Interfaz de línea de comandos (CLI)

Los comandos usan automáticamente el token almacenado en caché:

databricks postgres list-projects

curl

Genere un token para llamadas DE API directas:

export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)

curl -X GET "https://your-workspace.cloud.databricks.com/api/2.0/postgres/projects" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Los tokens de OAuth expiran después de una hora. Vuelva a generar según sea necesario.

Para más información, consulte Autorización del acceso de usuario a Databricks con OAuth.

Puntos de conexión disponibles (beta)

Todos los puntos de conexión usan la ruta base de acceso /api/2.0/postgres/.

Proyectos

Operation	Método	Punto final	Documentation
Crear proyecto	`POST`	`/projects`	Creación de un proyecto
Actualizar proyecto	`PATCH`	`/projects/{project_id}`	Configuración general
Eliminar proyecto	`DELETE`	`/projects/{project_id}`	Eliminación de un proyecto
Obtener proyecto	`GET`	`/projects/{project_id}`	Obtener detalles del proyecto
Enumerar proyectos	`GET`	`/projects`	Enumerar proyectos

Sucursales

Operation	Método	Punto final	Documentation
Crear rama	`POST`	`/projects/{project_id}/branches`	Crear una rama
Actualizar rama	`PATCH`	`/projects/{project_id}/branches/{branch_id}`	Actualizar la configuración de la rama
Eliminar rama	`DELETE`	`/projects/{project_id}/branches/{branch_id}`	Eliminación de una rama
Obtener rama	`GET`	`/projects/{project_id}/branches/{branch_id}`	Ver ramas
Enumerar ramas	`GET`	`/projects/{project_id}/branches`	Enumerar ramas

Puntos de conexión (procesos y réplicas de lectura)

En la API, un cómputo se denomina endpoint. Para obtener un mapeo completo de los términos de la interfaz de usuario y API, consulte Cómputos y puntos de conexión.

Operation	Método	Punto final	Documentation
Creación de un punto de conexión	`POST`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Crear una instancia de cómputo / Crear una réplica de lectura
Actualizar punto de conexión	`PATCH`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Editar un recurso de computación / Edición de una réplica de lectura
Eliminación de un punto de conexión	`DELETE`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Eliminación de un proceso / Eliminación de una réplica de lectura
Obtención del punto de conexión	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Visualización de procesos
Enumerar puntos de conexión	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Visualización de procesos

Funciones

Operation	Método	Punto final	Documentation
Lista de roles	`GET`	`/projects/{project_id}/branches/{branch_id}/roles`	Visualización de roles de Postgres
Creación de un rol	`POST`	`/projects/{project_id}/branches/{branch_id}/roles`	Creación de un rol \| de OAuthCreación de un rol de contraseña
Recuperar rol	`GET`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Visualización de roles de Postgres
Actualización de rol	`PATCH`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Actualización de un rol
Eliminar rol	`DELETE`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Eliminación de un rol

Catálogos

Operation	Método	Punto final	Documentation
Registro de la base de datos con el catálogo de Unity	`POST`	`/catalogs`	Registro de una base de datos
Obtención del registro de catálogo	`GET`	`/catalogs/{catalog_id}`	Comprobación del estado del registro
Eliminación del registro de catálogo	`DELETE`	`/catalogs/{catalog_id}`	Anulación del registro de una base de datos

Nota:

Registrar y eliminar son operaciones de larga duración. Sondee la operación devuelta hasta done: true. Consulte Operaciones de ejecución prolongada.

La eliminación de un registro de catálogo no quita la base de datos de Postgres subyacente.

Tablas sincronizadas

Operation	Método	Punto final	Documentation
Creación de una tabla sincronizada	`POST`	`/synced_tables`	Creación de una tabla sincronizada
Obtener tabla sincronizada	`GET`	`/synced_tables/{table_name}`	Comprobación del estado de sincronización
Eliminar tabla sincronizada	`DELETE`	`/synced_tables/{table_name}`	Eliminación de una tabla sincronizada

Nota:

El table_name en la ruta de acceso utiliza el formato catalog.schema.table.

Crear y eliminar son operaciones de larga duración. Sondee la operación devuelta hasta done: true. Consulte Operaciones de ejecución prolongada.

Al eliminar una tabla sincronizada, solo se quita el registro del catálogo de Unity. Quite la tabla Postgres por separado para liberar espacio.

Credenciales de base de datos

Operation	Método	Punto final	Documentation
Generación de credenciales de base de datos	`POST`	`/credentials`	Autenticación de tokens de OAuth

Operaciones

Operation	Método	Punto final	Documentation
Obtener operación	`GET`	`/projects/{project_id}/operations/{operation_id}`	Consulte el ejemplo siguiente.

Permisos

Los permisos de ACL del proyecto usan la API de permisos de Azure Databricks estándar, no la ruta de /api/2.0/postgres/ acceso base. Establezca request_object_type en database-projects y request_object_id en el ID del proyecto.

Operation	Método	Punto final	Documentation
Obtención de permisos de proyecto	`GET`	`/api/2.0/permissions/database-projects/{project_id}`	Referencia de API de permisos
Actualización de los permisos del proyecto	`PATCH`	`/api/2.0/permissions/database-projects/{project_id}`	Referencia de API de permisos
Reemplazar permisos de proyecto	`PUT`	`/api/2.0/permissions/database-projects/{project_id}`	Referencia de API de permisos

Los niveles de permisos que se pueden conceder para los proyectos de Lakebase son CAN_USE y CAN_MANAGE. CAN_CREATE es un nivel heredado y no se puede establecer a través de la API. Consulte Niveles de permisos.

Para obtener ejemplos de uso y los equivalentes de CLI/SDK/Terraform, consulte Concesión de permisos mediante programación.

Obtención de la operación

Compruebe el estado de una operación de ejecución prolongada por su nombre de recurso.

SDK de Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# Start an operation (example: create project)
operation = w.postgres.create_project(...)
print(f"Operation started: {operation.name}")

# Wait for completion
result = operation.wait()
print(f"Operation completed: {result.name}")

SDK de Java

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;

WorkspaceClient w = new WorkspaceClient();

// Start an operation (example: create project)
CreateProjectOperation operation = w.postgres().createProject(...);
System.out.println("Operation started: " + operation.getName());

// Wait for completion
Project result = operation.waitForCompletion();
System.out.println("Operation completed: " + result.getName());

Interfaz de línea de comandos (CLI)

La CLI espera automáticamente a que se completen las operaciones de forma predeterminada. Use --no-wait para omitir el sondeo:

# Create project without waiting
databricks postgres create-project --no-wait ...

# Later, check the operation status
databricks postgres get-operation projects/my-project/operations/abc123

curl

# Get operation status
curl -X GET "$WORKSPACE/api/2.0/postgres/projects/my-project/operations/abc123" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

Formato de respuesta:

{
  "name": "projects/my-project/operations/abc123",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/databricks.postgres.v1.Project",
    "name": "projects/my-project",
    ...
  }
}

Campos:

done: false mientras está en curso, true cuando se completa
response: contiene el resultado cuando done es true
error: contiene detalles de error si se produjo un error en la operación.

Patrones comunes

Asignación de nombres de recursos

Los recursos siguen un patrón de nomenclatura jerárquico en el que los recursos secundarios están delimitados por su recurso principal.

Los proyectos usan este formato:

projects/{project_id}

Los recursos secundarios, como las operaciones, están anidados en su proyecto primario:

projects/{project_id}/operations/{operation_id}

Esto significa que necesita el identificador del proyecto principal para acceder a las operaciones u otros recursos secundarios.

Identificadores de recursos:

Al crear recursos, debe proporcionar un identificador de recurso (como my-app) para el parámetro project_id, branch_id o endpoint_id. Este identificador forma parte de la ruta de acceso del recurso en las llamadas API (por ejemplo projects/my-app/branches/development, ).

Opcionalmente, puede proporcionar un display_name para proporcionar a su recurso una etiqueta más descriptiva. Si no especifica un nombre para mostrar, el sistema usa el identificador de recurso como nombre para mostrar.

:::tip Búsqueda de recursos en la interfaz de usuario

Para buscar un proyecto en la interfaz de usuario de Lakebase, busque su nombre de visualización en la lista de proyectos. Si no proporcionó un nombre visible personalizado al crear el proyecto, busque su project_id (por ejemplo, "my-app").

:::

Nota:

Los identificadores de recursos no se pueden cambiar después de la creación.

Requisitos:

Debe tener entre 1 y 63 caracteres
Solo letras minúsculas, dígitos y guiones
No se puede iniciar ni terminar con un guión
Ejemplos: my-app, analytics-db, customer-123

Operaciones de larga duración (LROs)

Las operaciones de creación, actualización y eliminación devuelven un databricks.longrunning.Operation objeto que proporciona un estado de finalización.

Respuesta de la operación de ejemplo:

{
  "name": "projects/my-project/operations/abc123",
  "done": false
}

Sondee la finalización mediante GetOperation:

SDK de Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# Start an operation
operation = w.postgres.create_project(...)

# Wait for completion
result = operation.wait()
print(f"Operation completed: {result.name}")

SDK de Java

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;

WorkspaceClient w = new WorkspaceClient();

// Start an operation
CreateProjectOperation operation = w.postgres().createProject(...);

// Wait for completion
Project result = operation.waitForCompletion();
System.out.println("Operation completed: " + result.getName());

Interfaz de línea de comandos (CLI)

La CLI espera automáticamente a que se completen las operaciones de forma predeterminada. usa --no-wait para retornar inmediatamente:

databricks postgres create-project --no-wait ...

curl

# Poll the operation
curl "$WORKSPACE/api/2.0/postgres/projects/my-project/operations/abc123" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq '.done'

Sondea cada pocos segundos hasta que done sea true.

Actualizar máscaras

Las operaciones de actualización requieren un update_mask parámetro que especifique los campos que se van a modificar. Esto evita que se sobrescriban accidentalmente campos no relacionados.

Diferencias de formato:

Método	Formato	Example
REST API	Parámetro de consulta	`?update_mask=spec.display_name`
SDK de Python	Objeto FieldMask	`update_mask=FieldMask(field_mask=["spec.display_name"])`
Interfaz de línea de comandos (CLI)	Argumento posicional	`update-project NAME spec.display_name`

Gestión de errores

La API de Lakebase devuelve códigos de estado HTTP estándar.

409: Operaciones en conflicto

Mensaje de error:

project already has running conflicting operations, scheduling of new ones is prohibited

Lo que significa:

Lakebase a veces programa operaciones de mantenimiento internas en proyectos. Si llega una solicitud de cliente mientras una de estas operaciones internas está en curso, Lakebase puede rechazar la nueva solicitud con un 409 Conflict error.

Este es el comportamiento esperado. Los clientes deben estar preparados para reintentar solicitudes cuando se produzca este error.

Qué hacer:

Intente de nuevo la solicitud. Cuando se completa la operación interna, Lakebase acepta nuevas solicitudes para el proyecto.

Use retroceso exponencial para reintentos: espere un intervalo corto antes del primer reintento y, a continuación, doble la espera en cada intento posterior. Un intervalo inicial de 100 milisegundos con un máximo de 30 segundos es un valor predeterminado razonable.

SDK de Python

import time
from databricks.sdk import WorkspaceClient
from databricks.sdk.errors import ResourceConflict
from databricks.sdk.service.postgres import Branch, BranchSpec

w = WorkspaceClient()

def retry_on_conflict(fn, max_attempts=5, base_delay=0.1):
    """Retry a Lakebase API call when a conflicting operation is in progress."""
    for attempt in range(max_attempts):
        try:
            return fn()
        except ResourceConflict:
            if attempt == max_attempts - 1:
                raise
            wait = base_delay * (2 ** attempt)
            print(f"Conflicting operation in progress. Retrying in {wait}s...")
            time.sleep(wait)

# Example: create a branch with retry
branch = retry_on_conflict(
    lambda: w.postgres.create_branch(
        parent="projects/my-project",
        branch=Branch(spec=BranchSpec(no_expiry=True)),
        branch_id="my-branch",
    ).wait()
)

curl

# Retry with exponential backoff on 409 responses
retry_on_conflict() {
  local cmd=("$@")
  local max_attempts=5
  local delay=0.1
  local attempt=0

  while [ $attempt -lt $max_attempts ]; do
    response=$(curl -s -w "\n%{http_code}" "${cmd[@]}")
    http_code=$(echo "$response" | tail -n1)
    body=$(echo "$response" | sed '$d')

    if [ "$http_code" -ne 409 ]; then
      echo "$body"
      return 0
    fi

    attempt=$((attempt + 1))
    if [ $attempt -eq $max_attempts ]; then
      echo "Max retries reached. Last response: $body" >&2
      return 1
    fi

    echo "Conflicting operation in progress. Retrying in ${delay}s..." >&2
    sleep "$delay"
    delay=$((delay * 2))
  done
}

# Example: create a branch with retry
retry_on_conflict \
  -X POST "$WORKSPACE/api/2.0/postgres/projects/my-project/branches?branch_id=my-branch" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"spec": {"no_expiry": true}}'

Nota:

Una 409 Conflict en una solicitud de API de Lakebase significa que no se aceptó la solicitud, no que se aplicó. Compruebe siempre el estado del recurso después de un reintento correcto llamando al punto de conexión correspondiente GET .

SDK y infraestructura como código

Comentarios

¿Le resultó útil esta página?

Last updated on 2026-04-04

Compartir vía

Guía de la API de escalado automático de Lakebase

Autenticación

Configuración de la autenticación

SDK de Python

SDK de Java

Interfaz de línea de comandos (CLI)

curl

Puntos de conexión disponibles (beta)

Proyectos

Sucursales

Puntos de conexión (procesos y réplicas de lectura)

Funciones

Catálogos

Tablas sincronizadas

Credenciales de base de datos

Operaciones

Permisos

Obtención de la operación

SDK de Python

SDK de Java

Interfaz de línea de comandos (CLI)

curl

Patrones comunes

Asignación de nombres de recursos

Operaciones de larga duración (LROs)

SDK de Python

SDK de Java

Interfaz de línea de comandos (CLI)

curl

Actualizar máscaras

Gestión de errores

409: Operaciones en conflicto

SDK de Python

curl

SDK y infraestructura como código

Comentarios

Recursos adicionales