Guia API escalonamento automático do Lakebase

info

Lakebase autoscale é a versão mais recente do Lakebase, com recursos como autoscale compute, escala-to-zero, branching e instant restore. Para regiões compatíveis, consulte Disponibilidade por região. Se você é usuário de provisionamento Lakebase , consulte ProvisionamentoLakebase.

Esta página fornece uma visão geral da API de escalonamento automático do Lakebase, incluindo autenticação, endpoints disponíveis e padrões comuns para trabalhar com a API REST , CLI Databricks e os SDKs Databricks (Python, Java, Go).

Para obter a referência completa da API, consulte a documentação da API do Postgres.

importante

A API Lakebase Postgres está em versão Beta . O endpoint API , seus parâmetros e comportamentos estão sujeitos a alterações.

Autenticação

A API de escalonamento automático do Lakebase usa autenticação OAuth em nívelworkspace para gerenciar a infraestrutura do projeto (criação de projetos, configuração de definições, etc.).

nota

Dois tipos de conectividade : Esta API serve para gerenciamento da plataforma (criação de projetos, branches, computação). Para acesso ao banco de dados (conexão para consulta de dados):

• Clientes SQL (psql, pgAdmin, DBeaver): Use tokens OAuth do Lakebase ou senhas do Postgres. Consulte Autenticação.
• API de dados (HTTP RESTful): Use tokens OAuth do Lakebase. Consulte a API de Dados.
• Drivers de linguagem de programação (psycopg, SQLAlchemy, JDBC): Use tokens OAuth do Lakebase ou senhas do Postgres. Consulte o Guia de Início Rápido.

Para uma explicação completa dessas duas camadas de autenticação, consulte Arquitetura de autenticação.

Configurar autenticação

Autentique-se usando a CLI do Databricks:

Bash

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

Siga as instruções do navegador para log in. A CLI armazena em cache seus tokens OAuth em ~/.databricks/token-cache.json.

Em seguida, escolha seu método de acesso:

Python SDK

O SDK utiliza autenticação unificada e gerencia automaticamente os tokens OAuth:

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

Java SDK

O SDK utiliza autenticação unificada e gerencia automaticamente os tokens OAuth:

Java

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

CLI

O comando usa automaticamente os tokens em cache:

Bash

databricks postgres list-projects

curl

Gere tokens para chamadas diretas API :

Bash

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}"

Os tokens OAuth expiram após uma hora. Regenerar conforme necessário.

Para obter mais detalhes, consulte Autorizar o acesso do usuário ao Databricks com OAuth.

Ponto final disponível (Beta)

Todos os endpoints usam o caminho base /api/2.0/postgres/.

Projetos

Operação	Método	Endpoint	Documentação
Criar projeto	POST	/projects	Criar um projeto
Projeto de atualização	PATCH	/projects/{project_id}	Configurações gerais
Excluir projeto	DELETE	/projects/{project_id}	Excluir um projeto
Obtenha o projeto	GET	/projects/{project_id}	Obtenha detalhes do projeto
Lista de projetos	GET	/projects	Lista de projetos

Galhos

Operação	Método	Endpoint	Documentação
Criar branch	POST	/projects/{project_id}/branches	Crie um branch
Atualizar ramificação	PATCH	/projects/{project_id}/branches/{branch_id}	Atualizar configurações da filial
Excluir ramo	DELETE	/projects/{project_id}/branches/{branch_id}	Excluir um ramo
Obter ramo	GET	/projects/{project_id}/branches/{branch_id}	ver ramos
Listar filiais	GET	/projects/{project_id}/branches	Listar filiais

ponto final (réplicas de computação e leitura)

Na API, um compute é chamado de endpoint . Para um mapeamento completo dos termos de interface do usuário e API , consulte compute e endpoint.

Operação	Método	Endpoint	Documentação
Criar endpoint	POST	/projects/{project_id}/branches/{branch_id}/endpoints	Criar uma compute / Criar uma réplica de leitura
Atualizar endpoint	PATCH	/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}	Editar uma compute / Editar uma réplica de leitura
Excluir endpoint	DELETE	/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}	Excluir uma compute / Excluir uma réplica de leitura
Obter endpoint	GET	/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}	visualizar computar
Listar endpoints	GET	/projects/{project_id}/branches/{branch_id}/endpoints	visualizar computar

Funções

Operação	Método	Endpoint	Documentação
Listar funções	GET	/projects/{project_id}/branches/{branch_id}/roles	visualizar funções do Postgres
Criar função	POST	/projects/{project_id}/branches/{branch_id}/roles	Criar uma função OAuth | Criar uma função de senha
Obtenha uma vaga	GET	/projects/{project_id}/branches/{branch_id}/roles/{role_id}	visualizar funções do Postgres
Atualizar função	PATCH	/projects/{project_id}/branches/{branch_id}/roles/{role_id}	Atualizar uma função
Excluir função	DELETE	/projects/{project_id}/branches/{branch_id}/roles/{role_id}	Excluir uma função

Catálogos

Operação	Método	Endpoint	Documentação
banco de dados de registro com Unity Catalog	POST	/catalogs	registrar um banco de dados
Obtenha o cadastro no catálogo	GET	/catalogs/{catalog_id}	Verificar status do registro
Excluir registro de catálogo	DELETE	/catalogs/{catalog_id}	Cancelar o registro de um banco de dados

nota

O registro e a exclusão são operações demoradas. Pesquise as operações devolvidas até done: true. Veja Operações de longa duração.

Excluir um registro de catálogo não exclui o banco de dados Postgres subjacente.

Tabelas sincronizadas

Operação	Método	Endpoint	Documentação
Criar tabela sincronizada	POST	/synced_tables	Criar uma tabela sincronizada
Obter tabela sincronizada	GET	/synced_tables/{table_name}	Verificar status de sincronização
Excluir tabela sincronizada	DELETE	/synced_tables/{table_name}	Excluir uma tabela sincronizada

nota

O table_name no caminho usa o formato catalog.schema.table.

Criar e excluir são operações demoradas. Pesquise as operações devolvidas até done: true. Veja Operações de longa duração.

Excluir uma tabela sincronizada remove apenas o registro do Unity Catalog . Exclua a tabela do Postgres separadamente para liberar espaço.

Credenciais do banco de dados

Operação	Método	Endpoint	Documentação
Gerar credenciais de banco de dados	POST	/credentials	autenticação por tokens OAuth

operações

Operação	Método	Endpoint	Documentação
Obtenha operações	GET	/projects/{project_id}/operations/{operation_id}	Veja o exemplo abaixo.

Permissões

As permissões ACL do projeto usam a API de permissões padrão do Databricks, não o caminho base /api/2.0/postgres/ . Defina request_object_type como database-projects e request_object_id como o ID do projeto.

Operação	Método	Endpoint	Documentação
Obter permissões do projeto	GET	/api/2.0/permissions/database-projects/{project_id}	Referência da API de permissões
Atualizar permissões do projeto	PATCH	/api/2.0/permissions/database-projects/{project_id}	Referência da API de permissões
Substituir permissões do projeto	PUT	/api/2.0/permissions/database-projects/{project_id}	Referência da API de permissões

Os níveis de permissão concedíveis para projetos Lakebase são CAN_USE e CAN_MANAGE. CAN_CREATE é um nível herdado e não pode ser definido através da API. Consulte Níveis de permissão.

Para exemplos de uso e equivalentes em CLI/SDK/Terraform, consulte Conceder permissões programaticamente.

Obtenha operações

Verifique o status de uma operação de longa duração pelo nome do recurso.

Python SDK

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}")

Java SDK

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());

CLI

Por default, a CLI aguarda automaticamente a conclusão das operações. Use --no-wait para ignorar a sondagem:

Bash

# 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

Bash

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

Formato da resposta:

JSON

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

Campos:

• done: false durante o processo, true quando estiver concluído
• responseContém o resultado quando done é true
• errorContém detalhes do erro caso as operações falhem.

Padrões comuns

nomeação de recursos

Os recursos seguem um padrão de nomenclatura hierárquico, onde os recursos filhos têm escopo limitado ao seu recurso pai.

Os projetos utilizam este formato:

projects/{project_id}

Recursos filhos como operações estão aninhados em seu projeto pai:

projects/{project_id}/operations/{operation_id}

Isso significa que você precisa do ID do projeto pai para acessar operações ou outros recursos filhos.

IDs de recursos:

Ao criar um recurso, você deve fornecer um ID de recurso (como my-app) para o parâmetro project_id, branch_id ou endpoint_id . Este ID torna-se parte do caminho do recurso nas chamadas da API (como projects/my-app/branches/development).

Você pode, opcionalmente, fornecer um display_name para dar ao seu recurso um rótulo mais descritivo. Se você não especificar um nome de exibição, o sistema usará o ID do seu recurso como nome de exibição.

:::dica Encontrando recurso na interface do usuário

Para localizar um projeto na interface do usuário do Lakebase, procure pelo nome de exibição dele na lista de projetos. Se você não forneceu um nome de exibição personalizado ao criar o projeto, procure por seu project_id (como "meu-app").

:::

nota

Os IDs dos recursos não podem ser alterados após a criação.

Requisitos:

• Deve ter entre 1 e 63 caracteres.
• Somente letras minúsculas, dígitos e hífenes.
• Não pode começar nem terminar com um hífen.
• Exemplos: my-app, analytics-db, customer-123

Operações de longa duração (LROs)

As operações de criação, atualização e exclusão retornam um objeto databricks.longrunning.Operation que fornece um status de conclusão.

Exemplo de resposta operacional:

JSON

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

Verificar conclusão usando GetOperation:

Python SDK

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}")

Java SDK

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());

CLI

Por default, a CLI aguarda automaticamente a conclusão das operações. Use --no-wait para retornar imediatamente:

Bash

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

curl

Bash

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

Verifique a cada poucos segundos até que done seja true.

Atualizar máscaras

As operações de atualização requerem um parâmetro update_mask que especifica quais campos devem ser modificados. Isso evita a sobrescrita acidental de campos não relacionados.

Diferenças de formato:

Método	Formato	Exemplo
API REST	Parâmetro de consulta	?update_mask=spec.display_name
SDK Python	Objeto FieldMask	update_mask=FieldMask(field_mask=["spec.display_name"])
CLIPE	Argumento posicional	update-project NAME spec.display_name

Tratamento de erros

A API do Lakebase retorna códigos de status HTTP padrão.

409: Operações conflitantes

Mensagem de erro:

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

O que significa:

Lakebase às vezes programa operações de manutenção interna em projetos. Se uma solicitação do cliente chegar enquanto uma dessas operações internas estiver em andamento, o Lakebase poderá rejeitar a nova solicitação com um erro 409 Conflict .

Este é o comportamento esperado. Os clientes devem estar preparados para tentar novamente as solicitações quando esse erro ocorrer.

O que fazer:

Tente novamente. Quando as operações internas forem concluídas, Lakebase aceitará novas solicitações para o projeto.

Utilize um recuo exponencial para novas tentativas: aguarde um curto intervalo antes da primeira nova tentativa e, em seguida, dobre o tempo de espera em cada tentativa subsequente. Um intervalo inicial de 100 milissegundos, com um máximo de 30 segundos, é um default razoável.

Python SDK

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

Bash

# 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

Um 409 Conflict em uma solicitação de API do Lakebase significa que a solicitação não foi aceita, não que ela foi aplicada. Sempre verifique o estado do recurso após uma nova tentativa bem-sucedida chamando o endpoint GET correspondente.

SDKs e Infrastructure-as-Code

• SDK Python
• SDK Java
• SDK Go
• Pacotes de Automação Declarativa
• Gerenciando projetos Lakebase com Bundles
• provedor Terraform
• Comece com Terraform para Lakebase