Guia API escalonamento automático do Lakebase

info

O dimensionamento automático do Lakebase está disponível nas seguintes regiões: us-east-1, us-east-2, eu-central-1, eu-west-1, eu-west-2, ap-south-1, ap-southeast-1, ap-southeast-2.

O Lakebase autoscale é a versão mais recente do Lakebase com recursos como autoscale compute, escala-to-zero, branching e instant restore. Para comparação de recursos com o provisionamento do Lakebase, veja escolhendo entre versões.

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 , os SDKs Databricks (Python, Java, Go) e Terraform.

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)

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

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.

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

Recursos adicionais

SDKs e Infrastructure-as-Code

• Documentação da CLI do Databricks
• Documentação do SDK do Python
• Documentação do SDK Java
• Documentação do SDK Go
• Documentação do provedor Terraform
• Comece com Terraform para Lakebase