Introdução à CLI do Databricks para Lakebase

Este guia ajuda você a começar a usar a CLI do Databricks para gerenciar seus projetos, ramificações e cálculos/bases computacionais (pontos de acesso) no Lakebase. Você aprenderá a criar um projeto de trabalho em apenas alguns comandos.

Para obter a referência de comando completa e todas as opções disponíveis, consulte os comandos de postgres da CLI do Databricks.

Pré-requisitos

• CLI do Databricks: instalar a CLI do Databricks. Consulte Instalar a CLI do Databricks.
• Acesso ao workspace: você deve ter acesso a um workspace do Azure Databricks no qual o recurso lakebase reside.

Autenticar com Azure Databricks

Antes de executar comandos da CLI, autentique-se com seu workspace do Azure Databricks:

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

Substitua https://your-workspace.cloud.databricks.com pela URL real do seu workspace. Esse comando abre uma janela do navegador para você se autenticar com sua conta do Azure Databricks usando o OAuth.

Observação

Se você tiver vários perfis, use o --profile sinalizador para especificar qual deles usar: databricks postgres <command> --profile my-profile. Para exibir seus perfis configurados, execute databricks auth profiles.

Para obter mais opções de autenticação, consulte a autenticação do Databricks.

Obter ajuda de comando

A CLI fornece ajuda interna para todos os comandos. Use --help para ver os comandos e opções disponíveis.

Obtenha uma visão geral de todos os comandos do Postgres:

databricks postgres --help

O comando exibe todos os comandos disponíveis, sinalizadores globais e informações sobre convenções de nomenclatura de recursos.

Obtenha ajuda detalhada para um comando específico:

databricks postgres create-project --help

Isso mostra a finalidade do comando, os parâmetros obrigatórios e opcionais, os exemplos de uso e os sinalizadores disponíveis.

Início Rápido: Criar seu primeiro projeto

Siga estes passos para criar um projeto com uma ramificação e um endpoint de computação:

1. Criar um projeto

Criar um projeto do Lakebase:

databricks postgres create-project my-project \
  --json '{
    "spec": {
      "display_name": "My Lakebase Project"
    }
  }'

Esse comando cria um projeto e aguarda a conclusão dele. A ID do projeto (my-project) torna-se parte do nome do recurso: projects/my-project. O projeto é criado com um ramo de produção padrão e um ponto de extremidade de computação de leitura e gravação, ambos com IDs gerados automaticamente.

Opcionalmente, exporte a ID do projeto como uma variável para usar em comandos subsequentes:

export PROJECT_ID="my-project"

2. Obter o ID do ramo

Liste os branches em seu projeto para localizar a ID de branch padrão:

databricks postgres list-branches projects/$PROJECT_ID

Isso retorna informações sobre todos os branches do projeto. Procure o branch com "default": true no status. Observe o ID da ramificação no campo name (por exemplo, production para a ramificação padrão).

Opcionalmente, exporte a ID do branch como uma variável para uso em comandos subsequentes:

export BRANCH_ID="production"

Substitua production pela ID de ramificação real da lista de saída.

3. Obtenha o ID do ponto de extremidade

Liste os pontos de extremidade em sua ramificação. O ramo padrão inclui automaticamente um ponto de extremidade de leitura/gravação.

databricks postgres list-endpoints projects/$PROJECT_ID/branches/$BRANCH_ID

Observe a ID do ponto de extremidade do name campo (por exemplo, primary para o ponto de extremidade de leitura-gravação padrão). Opcionalmente, exporte-o como uma variável:

export ENDPOINT_ID="primary"

Substitua primary pelo ID real do ponto de extremidade da lista de saída.

4. Gerar credenciais de banco de dados

Gere credenciais para se conectar ao banco de dados:

databricks postgres generate-database-credential \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID

O comando retorna um token OAuth que você pode usar com clientes PostgreSQL, como psql acessar seus dados usando sua identidade do Databricks. Para obter instruções passo a passo sobre como se conectar com psql, consulte Conectar com psql. Para obter mais informações sobre expiração e autenticação de token, consulte Autenticação.

Gerenciar projetos

Listar projetos

Liste todos os projetos em seu workspace:

databricks postgres list-projects

O comando retorna o nome, o nome de exibição, o estado atual e os registros de data e hora de cada projeto.

Obter detalhes do projeto

Obtenha informações detalhadas sobre um projeto:

databricks postgres get-project projects/$PROJECT_ID

O comando retorna o nome de exibição do projeto, a versão do PostgreSQL, o proprietário, o período de retenção do histórico, os limites de tamanho do branch, o tamanho do armazenamento e os carimbos de data/hora.

Gerenciar branches

Obter detalhes do branch

Obtenha informações detalhadas sobre um branch:

databricks postgres get-branch projects/$PROJECT_ID/branches/$BRANCH_ID

O comando retorna o estado atual do ramo, o status de proteção, o tamanho lógico, os detalhes do ramo de origem (se aplicável) e as marcas de data e hora.

Criar uma ramificação de funcionalidade

Crie um novo branch com base em um branch existente para testar as alterações. Quando você especifica um source_branch, o novo branch terá o mesmo esquema e dados que o branch de origem no momento da criação. Substitua as IDs do projeto e do branch pelos valores reais:

databricks postgres create-branch \
  projects/my-project \
  feature \
  --json '{
    "spec": {
      "source_branch": "projects/my-project/branches/production",
      "no_expiry": true
    }
  }'

Observação

Ao criar um branch, você deve especificar uma política de expiração. Use no_expiry: true para criar um branch permanente.

Para usar variáveis de shell dentro da especificação JSON (como $PROJECT_ID ou $BRANCH_ID), use aspas duplas para o valor --json e escape as aspas internas.

O Lakebase cria automaticamente o ramo de recursos com um ponto de extremidade de computação primário de leitura/gravação. Depois de concluir o desenvolvimento e os testes no ramo de funcionalidades, você pode excluí-lo.

databricks postgres delete-branch projects/$PROJECT_ID/branches/feature

Observação

Os comandos de exclusão retornam imediatamente, mas a exclusão real pode levar tempo para ser concluída. Você pode verificar a exclusão executando o comando get resource correspondente, que retorna um erro depois que o recurso é totalmente excluído.

Atualizar a proteção de ramificação

Atualize um recurso usando o padrão de máscara de atualização. A máscara de atualização especifica quais campos atualizar:

databricks postgres update-branch \
  projects/$PROJECT_ID/branches/$BRANCH_ID \
  spec.is_protected \
  --json '{
    "spec": {
      "is_protected": true
    }
  }'

Este exemplo define spec.is_protected como true, tornando o branch protegido. A máscara de atualização (spec.is_protected) informa à API qual campo atualizar. O comando retorna o recurso atualizado, mostrando o novo valor e um carimbo de data/hora atualizado update_time.

Gerenciar cálculos

Ver detalhes de processamento

Obtenha informações detalhadas sobre um endpoint:

databricks postgres get-endpoint projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID

O comando retorna o tipo de endpoint, as configurações de dimensionamento automático, o estado atual, o host de conexão, o tempo limite de suspensão e os registros de data e hora.

Dimensionar leituras com réplicas de leitura

Adicione réplicas de leitura para lidar com o aumento do tráfego de leitura. O exemplo abaixo adiciona uma réplica de leitura (read replica) ao branch de produção padrão.

databricks postgres create-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID \
  read-replica-1 \
  --json '{
    "spec": {
      "endpoint_type": "ENDPOINT_TYPE_READ_ONLY",
      "autoscaling_limit_min_cu": 0.5,
      "autoscaling_limit_max_cu": 4.0
    }
  }'

Você pode criar várias réplicas de leitura com IDs de ponto de extremidade diferentes (read-replica-1, read-replica-2, etc.) para distribuir cargas de trabalho de leitura.

Atualizar limites de dimensionamento automático

Para atualizar vários campos, use uma lista separada por vírgulas:

databricks postgres update-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID \
  "spec.autoscaling_limit_min_cu,spec.autoscaling_limit_max_cu" \
  --json '{
    "spec": {
      "autoscaling_limit_min_cu": 1.0,
      "autoscaling_limit_max_cu": 8.0
    }
  }'

Configurar a escala para zero

Para configurar a escala como zero, inclua spec.suspension na máscara de atualização. Defina suspend_timeout_duration (60s–604800s) para definir o tempo limite de inatividade ou no_suspension: true desabilitá-lo. Não defina ambas. A configuração no_suspension: false é inválida e retorna um erro. Por padrão, o ramo production está com o escalonamento para zero habilitado, com tempo limite de 24 horas.

# Disable scale to zero (compute stays active indefinitely)
databricks postgres update-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID \
  spec.suspension \
  --json '{
    "spec": {
      "no_suspension": true
    }
  }'

# Enable scale to zero with a 5-minute inactivity timeout (60s–604800s)
databricks postgres update-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID \
  spec.suspension \
  --json '{
    "spec": {
      "suspend_timeout_duration": "300s"
    }
  }'

Gerenciando funções

Use a CLI para criar e gerenciar funções postgres para acesso ao banco de dados em um branch. Para obter diretrizes detalhadas sobre tipos de função e autenticação, consulte Criar funções do Postgres.

Criar uma função

Crie uma função baseada em senha:

databricks postgres create-role projects/$PROJECT_ID/branches/$BRANCH_ID \
  --role-id my-app-role \
  --json '{"spec": {"postgres_role": "my-app-role"}}'

Crie uma função OAuth vinculada a uma identidade de Azure Databricks:

# For a user:
databricks postgres create-role projects/$PROJECT_ID/branches/$BRANCH_ID \
  --role-id my-user-role \
  --json '{"spec": {"identity_type": "USER", "postgres_role": "user@example.com"}}'

# For a service principal:
databricks postgres create-role projects/$PROJECT_ID/branches/$BRANCH_ID \
  --role-id my-sp-role \
  --json '{"spec": {"identity_type": "SERVICE_PRINCIPAL", "postgres_role": "<sp-client-id>"}}'

Listar e obter funções

Listar todas as funções em um branch:

databricks postgres list-roles projects/$PROJECT_ID/branches/$BRANCH_ID

Obtenha detalhes sobre uma função específica:

databricks postgres get-role projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID

A resposta inclui o nome do recurso de função gerado pelo sistema (por exemplo, rol-xxxx-xxxxxxxxxx) necessário para chamadas de atualização e exclusão.

Atualizar uma função

Atualize uma função usando o padrão de máscara de atualização. Passe a máscara de atualização como segundo argumento posicional.

Ao atualizar spec.attributes, você deve fornecer todos os três campos de atributo – a API substitui todo o objeto de atributos:

databricks postgres update-role \
  projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID \
  "spec.attributes" \
  --json '{"spec": {"attributes": {"createdb": true, "createrole": false, "bypassrls": false}}}'

Excluir uma função

databricks postgres delete-role projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID

Se a função possuir objetos de banco de dados, use --reassign-owned-to para transferir a propriedade antes da exclusão:

databricks postgres delete-role \
  projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID \
  --reassign-owned-to projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$OTHER_ROLE_ID

Gerenciando tabelas sincronizadas

As tabelas sincronizadas replicam os dados do Catálogo do Unity em seu banco de dados do Lakebase para leituras operacionais de baixa latência. Use create-synced-table com uma {catalog}.{schema}.{table} ID:

databricks postgres create-synced-table my-catalog.sales.orders \
  --json '{
    "spec": {
      "source_table_full_name": "main.sales.orders",
      "branch": "projects/my-project/branches/production",
      "primary_key_columns": ["order_id"],
      "scheduling_policy": "SNAPSHOT",
      "postgres_database": "databricks_postgres",
      "create_database_objects_if_missing": true
    }
  }'

O ID da tabela sincronizada se torna tanto o nome da entidade no Unity Catalog quanto o identificador da tabela do Postgres. Obtenha o status e exclua uma tabela sincronizada com o mesmo formato de ID:

# Check status
databricks postgres get-synced-table "synced_tables/my-catalog.sales.orders"

# Delete
databricks postgres delete-synced-table "synced_tables/my-catalog.sales.orders"

create-synced-table e create-catalog são operações de longa duração. Por padrão, a CLI aguarda a conclusão. Use --no-wait para retornar imediatamente ou --timeout para definir uma duração de espera personalizada. Consulte operações de longa duração.

Para obter diretrizes detalhadas sobre modos de sincronização, mapeamento de tipo de dados e planejamento de capacidade, consulte Os dados do Serve lakehouse com tabelas sincronizadas.

Noções básicas sobre os principais conceitos

Operações de longa duração

Os comandos Criar, atualizar e excluir são operações de execução prolongada. Por padrão, a CLI aguarda a conclusão da operação. Use --no-wait para retornar imediatamente e sondar o status separadamente:

databricks postgres create-project $PROJECT_ID \
  --json '{"spec": {"display_name": "My Project"}}' \
  --no-wait

Verificar o status da operação:

databricks postgres get-operation projects/$PROJECT_ID/operations/operation-id

Nomenclatura de recursos

O Lakebase usa nomes de recursos hierárquicos:

• Projetos: projects/{project_id}. Especifique a ID do projeto ao criar um projeto.
• Branches: projects/{project_id}/branches/{branch_id}. Ao criar uma ramificação, especifique o ID da ramificação.
• Pontos de extremidade: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Especifique a ID do ponto de extremidade (como primary ou read-replica-1) ao criar um ponto de extremidade.

As IDs devem ter de 1 a 63 caracteres, iniciar com uma letra minúscula e conter apenas letras minúsculas, números e hifens.

Atualizar máscaras

Os comandos de atualização exigem uma máscara de atualização que especifica quais campos modificar. A máscara é um caminho de campo como spec.display_name ou uma lista separada por vírgula para campos múltiplos.

O --json payload contém os novos valores para esses campos. Somente os campos listados na máscara de atualização são modificados.

Recursos adicionais

• Referência de comandos da CLI do Databricks para PostgreSQL
• Criar funções do Postgres
• Conectar-se ao psql
• Gerenciar branches
• Configurar o dimensionamento automático
• Servir dados do Lakehouse com tabelas sincronizadas