Pular para o conteúdo principal
Última atualização em

Comece a usar a CLI Databricks para Lakebase.

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 estes passos para criar um projeto completo e funcional com uma ramificação e endpoint 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.

Gerenciando seu recurso​

Liste todos os projetos​

Liste todos os projetos em seu workspace:

Bash
databricks postgres list-projects

O comando retorna informações sobre cada projeto, incluindo seu nome, nome de exibição e estado atual. Inclui também os registros de data e hora de criação e atualização.

Obtenha detalhes do recurso​

Obtenha informações detalhadas sobre um projeto:

Bash
databricks postgres get-project projects/$PROJECT_ID

O comando retorna a configuração detalhada do projeto, incluindo o nome de exibição, a versão PostgreSQL , o proprietário e o período de retenção do histórico. Inclui também limites de tamanho de ramificação, configurações endpoint default , tamanho de armazenamento e registros de data e hora de criação e atualização.

Obtenha informações detalhadas sobre uma filial:

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

O comando retorna informações detalhadas sobre a ramificação, incluindo o estado atual, o status da ramificação default , o status de proteção e o tamanho lógico. Inclui também detalhes da ramificação de origem (se ramificada a partir de outra ramificação), bem como os registros de data e hora de criação e atualização.

Obtenha informações detalhadas sobre um endpoint:

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

O comando retorna a configuração detalhada endpoint , incluindo o tipo endpoint (leitura e gravação ou somente leitura), as configurações de dimensionamento automático (unidades compute mínimas e máximas) e o estado atual (ATIVO, parado, etc.). Inclui também o host de conexão, o tempo limite de suspensão e os registros de data e hora de criação e atualização.

Atualizar recurso​

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.

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

Fluxo de trabalho comum​

Crie uma ramificação de recurso a partir da produção.​

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 de shell dentro da especificação JSON (como $PROJECT_ID ou $BRANCH_ID), você precisaria usar aspas duplas para o valor --json e escapar 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.

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.

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

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óximos passos​

Nesta página