Comece a usar a CLI Databricks para Lakebase.

info

Beta

A partir de 15 de junho, o Lakebase está disponível em Beta no GCP. Consulte Disponibilidade regional para regiões compatíveis.

Este guia ajuda você a começar a usar a CLI Databricks para gerenciar seus projetos, branches e recursos computacionais (endpoints) do Lakebase. Você aprenderá como criar um projeto funcional com apenas alguns comandos.

Para obter uma referência completa do comando e todas as opções disponíveis, consulte o comando postgres CLI Databricks.

Pré-requisitos

CLI do Databricks : Instale a CLI do Databricks. Consulte Instalar a CLI do Databricks.
Acesso ao espaço de trabalho : Você precisa ter acesso a um workspace Databricks onde seu recurso do Lakebase está localizado.

Autentique-se com o Databricks

Antes de executar qualquer comando CLI , autentique-se com seu workspace Databricks :

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

Substitua https://your-workspace.cloud.databricks.com pelo URL real do seu workspace . Este comando abre uma janela do navegador para que você possa se autenticar com sua account Databricks usando OAuth.

nota

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

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

Obtenha ajuda para o comando

A interface de linha de comando (CLI) fornece ajuda integrada 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:

Bash
databricks postgres --help

O comando exibe 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:

Bash
databricks postgres create-project --help

Esta seção mostra a finalidade do comando, os parâmetros obrigatórios e opcionais, exemplos de uso e opções disponíveis.

Início rápido: Crie seu primeiro projeto

Siga estas etapas para criar um projeto com uma ramificação e um endpoint de compute:

1. Criar um projeto

Criar um projeto Lakebase:

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

Este comando cria um projeto e aguarda sua conclusão. O ID do projeto (my-project) torna-se parte do nome do recurso: projects/my-project. O projeto é criado com uma branch de produção default e um endpoint compute de leitura e gravação, ambos com IDs gerados automaticamente.

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

Bash
export PROJECT_ID="my-project"

2. Obtenha o ID da filial

Liste as ramificações do seu projeto para encontrar o ID da ramificação default :

Bash
databricks postgres list-branches projects/$PROJECT_ID

Isso retorna informações sobre todas as filiais do projeto. Procure a ramificação com "default": true no status. Observe o ID da filial do campo name (por exemplo, production para a filial default ).

Opcionalmente, exporte o ID da filial como uma variável para uso em comandos subsequentes:

Bash
export BRANCH_ID="production"

Substitua production pelo ID da sua filial, conforme a lista exibida.

3. Obtenha o ID do endpoint

Liste o endpoint em sua branch. O branch default inclui automaticamente um endpoint de leitura e gravação:

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

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

Bash
export ENDPOINT_ID="primary"

Substitua primary pelo ID do seu endpoint real, obtido na lista de saída.

4. Gerar credenciais de banco de dados

Gere as credenciais para se conectar ao seu banco de dados:

Bash
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 para acessar seu uso de dados sua identidade Databricks . Para obter instruções passo a passo sobre como conectar-se ao psql, consulte Conectar-se com o psql. Para obter mais informações sobre expiração de tokens e autenticação, consulte Autenticação.

Gerenciar projetos

Listar projetos

Liste todos os projetos em seu workspace:

Bash
databricks postgres list-projects

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

Obtenha detalhes do projeto

Obtenha informações detalhadas sobre um projeto:

Bash
databricks postgres get-project projects/$PROJECT_ID

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

Gerenciar branches

Obter detalhes do ramo

Obtenha informações detalhadas sobre uma filial:

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

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

Crie um branch de recurso

Crie uma nova ramificação com base em uma ramificação 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 os IDs do projeto e da ramificação pelos seus valores reais:

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

nota

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

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

Lakebase cria automaticamente o branch de recurso com um endpoint compute primário de leitura e gravação. Após concluir o desenvolvimento e os testes no branch recurso, você pode excluí-lo:

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

nota

O comando Delete retorna imediatamente, mas a exclusão em si pode levar algum tempo para ser concluída. Você pode verificar a exclusão executando o comando correspondente para obter o recurso, que retornará um erro após o recurso ser completamente excluído.

Atualizar proteção de branch

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

Bash
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 ramo 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 update_time atualizado.

Gerenciar computes

Obter detalhes do compute

Obtenha informações detalhadas sobre um endpoint:

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

O comando retorna o tipo de endpoint, as configurações de autoscale, o estado atual, o host de conexão, o tempo limite de suspensão e os carimbos de data/hora.

A escala lê com réplicas lidas

Adicione réplicas de leitura para lidar com o aumento do tráfego de leitura. O exemplo a seguir adiciona uma réplica de leitura ao branch de produção default :

Bash
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 endpoint diferentes (read-replica-1, read-replica-2, etc.) para distribuir as cargas de trabalho de leitura.

Atualizar limites de autoscale

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

Bash
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 a escala para zero, inclua spec.suspension na máscara de atualização. Configure suspend_timeout_duration (60s–604800s) para definir o tempo limite de inatividade, ou no_suspension: true para desativá-lo. Não se deve definir ambos. A configuração no_suspension: false é inválida e retorna um erro. Por padrão, o branch production tem a escala para zero ativada com um tempo limite de 24 horas.

Bash
# 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

Utilize a CLI para criar e gerenciar funções do Postgres para acesso ao banco de dados dentro de uma ramificação. Para obter orientações detalhadas sobre tipos de função e autenticação, consulte Criar funções do Postgres.

Criar uma função

Criar uma função baseada em senha:

Bash
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 do Databricks:

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

Liste e obtenha funções

Liste todas as funções em uma filial:

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

Obtenha detalhes sobre uma vaga específica:

Bash
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 o segundo argumento posicional.

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

Bash
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

Bash
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:

Bash
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

Gerenciar tabelas sincronizadas

Tabelas sincronizadas replicam dados do Unity Catalog para seu banco de dados Lakebase para leituras operacionais de baixa latência. Use create-synced-table com um ID {catalog}.{schema}.{table}:

Bash
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 o nome da entidade do Unity Catalog e identifica a tabela Postgres. Obtenha o status e exclua uma tabela sincronizada com o mesmo formato de ID:

Bash
# 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 default, 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 orientações detalhadas sobre modos de sincronização, mapeamento de tipo de dados e planejamento de capacidade, consulte Disponibilize dados lakehouse com tabelas sincronizadas.

Compreendendo os conceitos- key

operações de longa duração

Os comandos de criação, atualização e exclusão são operações de longa duração. Por default, a CLI aguarda a conclusão das operações. Use --no-wait para retornar imediatamente e consultar o status separadamente:

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

Consulte o status das operações:

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

nomeação de recursos

O Lakebase utiliza nomes de recursos hierárquicos:

Projetos : projects/{project_id}. Você especifica o ID do projeto ao criar um projeto.
Ramos : projects/{project_id}/branches/{branch_id}. Você especifica o ID da filial ao criar uma filial.
ponto final : projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Você especifica o ID do endpoint (como primary ou read-replica-1) ao criar um endpoint.

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

Atualizar máscaras

O comando de atualização requer uma máscara de atualização que especifica quais campos devem ser modificados. A máscara é um caminho de campo como spec.display_name ou uma lista separada por vírgulas para vários campos.

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

Pré-requisitos​

Autentique-se com o Databricks​

Obtenha ajuda para o comando​

Início rápido: Crie seu primeiro projeto​

1. Criar um projeto​

2. Obtenha o ID da filial​

3. Obtenha o ID do endpoint​

4. Gerar credenciais de banco de dados​

Gerenciar projetos​

Listar projetos​

Obtenha detalhes do projeto​

Gerenciar branches​

Obter detalhes do ramo​

Crie um branch de recurso​

Atualizar proteção de branch​

Gerenciar computes​

Obter detalhes do compute​

A escala lê com réplicas lidas​

Atualizar limites de autoscale​

Configurar escala para zero​

funções de gestão​

Criar uma função​

Liste e obtenha funções​

Atualizar uma função​

Excluir uma função​

Gerenciar tabelas sincronizadas​

Compreendendo os conceitos- key​

operações de longa duração​

nomeação de recursos​

Atualizar máscaras​

Recursos adicionais​

Pré-requisitos

Autentique-se com o Databricks

Obtenha ajuda para o comando

Início rápido: Crie seu primeiro projeto

1. Criar um projeto

2. Obtenha o ID da filial

3. Obtenha o ID do endpoint

4. Gerar credenciais de banco de dados

Gerenciar projetos

Listar projetos

Obtenha detalhes do projeto

Gerenciar branches

Obter detalhes do ramo

Crie um branch de recurso

Atualizar proteção de branch

Gerenciar computes

Obter detalhes do compute

A escala lê com réplicas lidas

Atualizar limites de autoscale

Configurar escala para zero

funções de gestão

Criar uma função

Liste e obtenha funções

Atualizar uma função

Excluir uma função

Gerenciar tabelas sincronizadas

Compreendendo os conceitos- key

operações de longa duração

nomeação de recursos

Atualizar máscaras

Recursos adicionais