Guia da API de Dimensionamento Automático do Lakebase

Importante

O dimensionamento automático do Lakebase está disponível nas seguintes regiões: eastus, , eastus2, centralus, southcentralus, , westus, westus2, canadacentral, , brazilsouth, , northeurope, uksouth, , westeurope, , australiaeast, centralindiasoutheastasia.

O Dimensionamento Automático do Lakebase é a versão mais recente do Lakebase, com computação de dimensionamento automático, escala para zero, ramificação e restauração instantânea. Se você for um usuário provisionado do Lakebase, consulte Lakebase Provisioned.

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

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

Importante

A API do Lakebase Postgres está em Beta. Pontos de extremidade de API, parâmetros e comportamentos estão sujeitos a alterações.

Authentication

A API de Dimensionamento Automático do Lakebase usa a autenticação OAuth no nível do workspace para gerenciar a infraestrutura do projeto (criando projetos, definindo configurações etc.).

Observação

Dois tipos de conectividade: essa API é para gerenciamento de plataforma (criação de projetos, branches, computação). Para acesso ao banco de dados (conectando-se para consultar 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 linguagens de programação (psycopg, SQLAlchemy, JDBC): Use tokens de OAuth do Lakebase ou senhas do Postgres. Consulte o Início Rápido.

Para obter uma explicação completa dessas duas camadas de autenticação, consulte a arquitetura de autenticação.

Configurar a autenticação

Autenticar usando a CLI do Databricks:

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

Siga os prompts do navegador para fazer logon. A CLI armazena em cache o token OAuth em ~/.databricks/token-cache.json.

Em seguida, escolha seu método de acesso:

SDK do Python

O SDK usa autenticação unificada e manipula automaticamente tokens OAuth:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

Java SDK

O SDK usa autenticação unificada e manipula automaticamente tokens OAuth:

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

CLI

Os comandos usam automaticamente o token armazenado em cache:

databricks postgres list-projects

encurvar

Gere um token para chamadas diretas à API:

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 o OAuth.

Pontos de extremidade disponíveis (Beta)

Todos os pontos de extremidade usam o caminho base /api/2.0/postgres/.

Projetos

Operation	Método	Ponto final	Documentation
Criar projeto	POST	/projects	Criar um projeto
Atualizar projeto	PATCH	/projects/{project_id}	Configurações gerais
Excluir projeto	DELETE	/projects/{project_id}	Excluir um projeto
Obter projeto	GET	/projects/{project_id}	Obter detalhes do projeto
Listar projetos	GET	/projects	Listar projetos

Ramos

Operation	Método	Ponto final	Documentation
Criar ramificação	POST	/projects/{project_id}/branches	Criar um branch
Atualizar branch	PATCH	/projects/{project_id}/branches/{branch_id}	Atualizar configurações de branch
Excluir branch	DELETE	/projects/{project_id}/branches/{branch_id}	Excluir uma ramificação
Obter ramificação	GET	/projects/{project_id}/branches/{branch_id}	Exibir ramificações
Listar ramificações	GET	/projects/{project_id}/branches	Listar Branches

Pontos de extremidade (computação e réplicas de leitura)

Operation	Método	Ponto final	Documentation
Criar ponto de extremidade	POST	/projects/{project_id}/branches/{branch_id}/endpoints	Criar uma computação / Criar uma réplica de leitura
Atualizar endpoint	PATCH	/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}	Editar uma computação / Editar uma réplica de leitura
Excluir ponto de extremidade	DELETE	/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}	Excluir uma computação / Excluir uma réplica de leitura
Obter o ponto de extremidade	GET	/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}	Exibir cálculos
Listar pontos de extremidade	GET	/projects/{project_id}/branches/{branch_id}/endpoints	Exibir cálculos

Papéis

Operation	Método	Ponto final	Documentation
Listar funções	GET	/projects/{project_id}/branches/{branch_id}/roles	Exibir 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
Obter função	GET	/projects/{project_id}/branches/{branch_id}/roles/{role_id}	Exibir 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

Credenciais de banco de dados

Operation	Método	Ponto final	Documentation
Gerar credencial de banco de dados	POST	/credentials	Autenticação de token OAuth

Operações

Operation	Método	Ponto final	Documentation
Obter operação	GET	/projects/{project_id}/operations/{operation_id}	Veja o exemplo abaixo

Permissões

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

Operation	Método	Ponto final	Documentation
Obter permissões de projeto	GET	/api/2.0/permissions/database-projects/{project_id}	Referência da API de permissões
Atualizar permissões de projeto	PATCH	/api/2.0/permissions/database-projects/{project_id}	Referência da API de permissões
Substituir permissões de projeto	PUT	/api/2.0/permissions/database-projects/{project_id}	Referência da API de permissões

Os níveis de permissão que podem ser concedidos para projetos do Lakebase são CAN_USE e CAN_MANAGE. CAN_CREATE é um nível herdado e não pode ser definido por meio da API. Consulte os níveis de permissão.

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

Obter operação

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

SDK do 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

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

A CLI aguarda automaticamente a conclusão das operações por padrão. Use --no-wait para ignorar a sondagem:

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

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

encurvar

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

Formato de resposta:

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

Campos:

• done: false enquanto estiver em andamento, true quando concluído
• response: contém o resultado quando done é true
• error: contém detalhes de erro se a operação falhou

Padrões comuns

Nomenclatura de recursos

Os recursos seguem um padrão de nomenclatura hierárquico em que os recursos filho têm escopo para o pai.

Os projetos usam este formato:

projects/{project_id}

Recursos filho, como operações, são aninhados em seu projeto pai:

projects/{project_id}/operations/{operation_id}

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

IDs de recurso:

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

Opcionalmente, você pode fornecer um display_name rótulo mais descritivo para o recurso. Se você não especificar um nome de exibição, o sistema usará sua ID de recurso como o nome de exibição.

:::tip Localizando recursos na interface do usuário

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

:::

Observação

As IDs de recurso não podem ser alteradas após a criação.

Requirements:

• Deve ter de 1 a 63 caracteres
• Letras minúsculas, dígitos e hifens somente
• Não é possível iniciar ou terminar com um hífen
• Exemplos: my-app, , analytics-dbcustomer-123

Operações de execução prolongada (LROs)

As operações Criar, atualizar e excluir retornam um databricks.longrunning.Operation objeto que fornece um status de conclusão.

Exemplo de resposta de operação:

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

Sondagem para conclusão usando GetOperation:

SDK do 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

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

A CLI aguarda automaticamente a conclusão das operações por padrão. Use --no-wait para retornar imediatamente:

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

encurvar

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

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

Atualizar máscaras

As operações de atualização exigem um update_mask parâmetro que especifica quais campos modificar. Isso impede a substituição acidental de campos não relacionados.

Diferenças de formato:

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

Tratamento de erros

A API 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:

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

Este comportamento é esperado. Os clientes devem estar preparados para repetir solicitações quando esse erro ocorrer.

O que fazer:

Tente novamente a solicitação. Quando a operação interna é concluída, o Lakebase aceita novas solicitações para o projeto.

Use a retirada exponencial para novas tentativas: aguarde um intervalo curto antes da primeira repetição e, em seguida, dobre a espera em cada tentativa subsequente. Um intervalo inicial de 100 milissegundos com um máximo de 30 segundos é um padrão razoável.

SDK do 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()
)

encurvar

# 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}}'

Observação

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

SDKs e infraestrutura como código

• SDK do Python
• Java SDK
• SDK do Go
• Pacotes de Automação Declarativa
• Gerenciar projetos do Lakebase com pacotes
• Provedor Terraform
• Introdução ao Terraform para Lakebase