Comece a usar a CLI Databricks para 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.

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

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

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 novo 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, br-divine-sea-y2k942xa).

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

Bash

export BRANCH_ID="br-divine-sea-y2k942xa"

Substitua br-divine-sea-y2k942xa pelo ID da sua filial default real, 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 . Será no formato projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Extraia o ID endpoint (por exemplo, ep-plain-sunset-y2vc0zan) e, opcionalmente, exporte-o como uma variável:

Bash

export ENDPOINT_ID="ep-plain-sunset-y2vc0zan"

Substitua ep-plain-sunset-y2vc0zan 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

Esta função retorna informações sobre cada projeto, incluindo seu nome, nome de exibição, estado atual e registros de data e hora de criação/atualização.

Obtenha detalhes do recurso

Obtenha informações detalhadas sobre um projeto:

Bash

databricks postgres get-project projects/$PROJECT_ID

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

Obtenha informações detalhadas sobre uma filial:

Bash

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

Esta função retorna informações detalhadas sobre a ramificação, incluindo o estado atual, o status da ramificação default , o status de proteção, o tamanho lógico, os detalhes da ramificação de origem (se ramificada a partir de outra ramificação) e os registros de data e hora de criação/atualização.

Obtenha informações detalhadas sobre um endpoint:

Bash

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

Isso retorna a configuração detalhada endpoint , incluindo o tipo endpoint (leitura e gravação ou somente leitura), configurações de dimensionamento automático (unidades compute mínimas e máximas), estado atual (ATIVO, parado, etc.), host de conexão, tempo limite de suspensão e registros de data e hora de criação/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/br-divine-sea-y2k942xa",
      "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.

O branch de recurso precisa de um endpoint compute de leitura e gravação para permitir operações de banco de dados:

Bash

databricks postgres create-endpoint \
  projects/$PROJECT_ID/branches/feature \
  primary \
  --json '{
    "spec": {
      "endpoint_type": "ENDPOINT_TYPE_READ_WRITE",
      "autoscaling_limit_min_cu": 0.5,
      "autoscaling_limit_max_cu": 2.0
    }
  }'

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 assim que o recurso for 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. Este exemplo 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.

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

• Referência de comandos do PostgreSQL CLI Databricks
• Conecte-se com o psql
• ger ramos
• Configure o dimensionamento automático.