Comece a usar a linha de comando Databricks para o Lakebase

Este guia ajuda-o a começar com a CLI Databricks para gerir os seus projetos, branches e computações (endpoints) no Lakebase. Vai aprender a criar um projeto funcional em apenas alguns comandos.

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

Pré-requisitos

• Databricks CLI: Instale a CLI do Databricks. Veja instalar a interface de comando Databricks.
• Acesso ao espaço de trabalho: Deve ter acesso a um espaço de trabalho Azure Databricks onde reside o seu recurso Lakebase.

Autenticar com o Azure Databricks

Antes de executar quaisquer comandos CLI, autentique com o seu espaço de trabalho Azure Databricks:

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

Substitui https://your-workspace.cloud.databricks.com pelo URL real do teu espaço de trabalho. Este comando abre uma janela do navegador para se autenticar com a sua conta Azure Databricks usando o OAuth.

Observação

Se tiver vários perfis, use a --profile flag para especificar qual usar: databricks postgres <command> --profile my-profile. Para visualizar os seus perfis configurados, execute databricks auth profiles.

Para mais opções de autenticação, consulte Databricks Autenticação.

Obter ajuda para comandos

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

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

databricks postgres --help

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

Obtenha ajuda detalhada para um comando específico:

databricks postgres create-project --help

Este mostra o propósito do comando, parâmetros obrigatórios e opcionais, exemplos de utilização e flags disponíveis.

Início Rápido: Crie o seu primeiro projeto

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

1. Criar um projeto

Crie um projeto Lakebase:

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

Este comando cria um projeto e espera que este seja concluído. O ID do projeto (my-project) passa a fazer parte do nome do recurso: projects/my-project. O projeto é criado com um ramo de produção padrão e um endpoint de computação de leitura e escrita, ambos com IDs gerados automaticamente.

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

export PROJECT_ID="my-project"

2. Obtenha o ID da agência

Liste os ramos no seu projeto para encontrar o ID predefinido do ramo:

databricks postgres list-branches projects/$PROJECT_ID

Isto devolve informações sobre todos os ramos do projeto. Procura o ramo com "default": true no estado. Note o ID do ramo no campo name (por exemplo, production para o ramo padrão).

Exporte o ID do ramo como uma variável para utilização em comandos subsequentes.

export BRANCH_ID="production"

Substitui production pelo ID real do teu ramo na saída da lista.

Obtenha o ID do endpoint

Lista os pontos finais na tua agência. O ramo predefinido inclui automaticamente um endpoint de leitura-escrita:

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

Anote o ID do endpoint do campo name (por exemplo, primary para o endpoint padrão de leitura e escrita). Opcionalmente, exporte-o como variável:

export ENDPOINT_ID="primary"

Substitui primary pelo ID real do endpoint da lista apresentada.

4. Gerar credenciais de base de dados

Gera credenciais para te ligares à tua base de dados:

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

O comando devolve um token OAuth que podes usar com clientes PostgreSQL, como psql para aceder aos teus dados usando a identidade do teu Databricks. Para instruções passo a passo sobre como ligar com psql, veja Ligar com psql. Para mais informações sobre expiração e autenticação de tokens, consulte Autenticação.

Gerir projetos

Listar projetos

Liste todos os projetos no seu espaço de trabalho:

databricks postgres list-projects

O comando devolve o nome de cada projeto, o nome apresentado, o estado atual e as marcas temporais.

Obtenha detalhes do projeto

Obtenha informações detalhadas sobre um projeto:

databricks postgres get-project projects/$PROJECT_ID

O comando devolve o nome de exibição do projeto, a versão PostgreSQL, o proprietário, o período de retenção do histórico, os limites do tamanho do ramo, o tamanho do armazenamento e os carimbos temporais.

Gerir filiais

Obtenha detalhes das filiais

Obtenha informações detalhadas sobre uma filial:

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

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

Criar um ramo de funcionalidades

Crie um novo ramo baseado num ramo existente para testar alterações. Quando especificas um source_branch, o novo ramo terá o mesmo esquema e dados que o ramo de origem no momento da criação. Substitua os IDs do projeto e dos ramos pelos seus 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 ramo, deve especificar uma política de expiração. Use no_expiry: true para criar um ramo permanente.

Para usar variáveis da shell na 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 funcionalidades com um endpoint primário de leitura-escrita de computação. Depois de terminares o desenvolvimento e os testes no ramo de funcionalidades, podes apagá-lo:

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

Observação

Os comandos de apagar retornam imediatamente, mas a eliminação pode demorar algum tempo a ser concluída. Pode verificar a eliminação executando o comando get resource correspondente, que devolve um erro depois de o recurso ser totalmente eliminado.

Atualizar proteção de branch

Atualize um recurso usando o padrão de atualização da máscara. A máscara de atualização especifica quais os campos a 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 para true, tornando o ramo protegido. A máscara de atualização (spec.is_protected) indica à API qual campo atualizar. O comando retorna o recurso atualizado mostrando o novo valor e um timestamp atualizado update_time.

Gerir computações

Ver detalhes de computação

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 definições de escalonamento automático, o estado atual, o host de ligação, o tempo limite de suspensão e as marcas temporais.

Leituras à escala com réplicas de leitura

Adicionar réplicas de leitura para lidar com o aumento do tráfego de leitura. O exemplo seguinte adiciona uma réplica de leitura ao ramo 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
    }
  }'

Pode criar múltiplas réplicas de leitura com diferentes IDs de endpoint (read-replica-1, read-replica-2, etc.) para distribuir cargas de trabalho de leitura.

Atualizar limites de dimensionamento automático

Para atualizar múltiplos 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 escala para zero

Para configurar escala para zero, inclua spec.suspension na máscara de atualização. Defina suspend_timeout_duration (60s–604800s) para definir o timeout da inatividade, ou no_suspension: true para o desativar. Não defina ambas. A configuração no_suspension: false é inválida e devolve um erro. Por defeito, o ramo production tem o dimensionamento para zero ativado com um limite de tempo 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"
    }
  }'

Funções de gestão

Use a CLI para criar e gerir funções Postgres para acesso a bases de dados dentro de uma filial. Para orientações detalhadas sobre tipos de funções e autenticação, consulte Criar funções Postgres.

Criar uma função

Crie um papel baseado em palavra-passe:

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

Criar um papel OAuth ligado a uma identidade do 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>"}}'

Lista e obtenha as funções

Liste todos os cargos numa filial:

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

Obtenha detalhes sobre um cargo específico:

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 atualizar e eliminar chamadas.

Atualizar um papel

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, deve fornecer os três campos de atributos — 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 o papel detém objetos da base de dados, use --reassign-owned-to para transferir a propriedade antes da eliminaçã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

Gerir tabelas sincronizadas

Tabelas sincronizadas replicam os dados do Unity Catalog para a sua base de dados Lakebase para leituras operacionais de baixa latência. Utilize create-synced-table com um ID {catalog}.{schema}.{table}:

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 torna-se tanto o nome da entidade do Catálogo Unity como a identificação da tabela Postgres. Obtenha o estado e apague 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 predefinição, a CLI aguarda a conclusão. Use --no-wait para voltar imediatamente ou --timeout para definir uma duração de espera personalizada. Ver Operações de longa duração.

Para orientações detalhadas sobre modos de sincronização, mapeamento de tipos de dados e planeamento de capacidade, consulte Servir dados do lakehouse com tabelas sincronizadas.

Compreensão dos conceitos-chave

Operações de longa duração

Comandos de criar, atualizar e eliminar são operações de longa duração. Por defeito, a CLI espera que a operação seja concluída. Use --no-wait para voltar imediatamente e consultar o estado separadamente:

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

Verificar o estado da operação:

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

Nomenclatura de recursos

O Lakebase utiliza nomes de recursos hierárquicos:

• Projetos: projects/{project_id}. Especifica o ID do projeto ao criar um projeto.
• Ramos: projects/{project_id}/branches/{branch_id}. Especifica o ID do ramo ao criar um ramo.
• Pontos de extremidade: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Especifica o ID do endpoint (como primary ou read-replica-1) ao criar um endpoint.

Os IDs devem ter entre 1 e 63 caracteres, começar com uma letra minúscula e conter apenas letras minúsculas, números e hífens.

Atualizar máscaras

Os comandos de atualização requerem uma máscara de atualização que especifique quais os campos a modificar. A máscara é um caminho de campo como spec.display_name ou uma lista separada por vírgulas para vários campos.

A --json carga útil contém os novos valores desses campos. Apenas os campos listados na máscara de atualização são modificados.

Recursos adicionais

• Referência de comandos da CLI Databricks para PostgreSQL
• Criar funções de Postgres
• Liga-te ao psql
• Gerir filiais
• Configurar o dimensionamento automático
• Disponibilizar dados da arquitetura lakehouse com tabelas sincronizadas