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

Atualize seu pacote para usar recursos de autoscale

Este guia aborda a atualização de um Databricks Asset Bundle (DAB) existente. A atualização converte uma configuração Lakebase de provisionamento (um database_instances recurso, opcionalmente com uma instância filha, catálogos e tabelas sincronizadas) para recurso Lakebase de autoscale (postgres_projects, postgres_branches, postgres_endpoints, e opcionalmente postgres_catalogs e postgres_synced_tables).

Quando aplicável​

O seu banco de dados Lakebase já funciona na plataforma de autoscale. A partir de 12 de março de 2026, a API de instância de banco de dados cria novas instâncias do Lakebase como projetos de autoscale. Seu pacote é a única parte que ainda os referencia utilizando database_instances. A partir de junho de 2026, a Databricks automaticamente atualizará as instâncias provisionadas existentes para Autoscale. Em ambos os casos, os passos de atualização do bundle são os mesmos.

Como a atualização funciona​

A atualização está no local. Databricks não move nem copia seus dados. O pacote interrompe o acompanhamento dos recursos provisionados e começa a gerenciar o mesmo banco de dados subjacente por meio dos recursos de autoscale. Isso desbloqueia recursos como o dimensionamento para zero e a ramificação.

A alteração exige duas chamadas de databricks bundle deploy, com os comandos databricks bundle deployment bind e unbind entre elas, para gerenciar a transição de estado do pacote.

Para as diferenças conceituais entre provisionadas e autoscale, consulte Atualizar para autoscale. Esta página aborda apenas a atualização da configuração do pacote.

Pré-requisitos​

Antes de começar, é preciso ter:

  • Versão 1.2.0 ou superior da CLI do Databricks, que atualiza seus recursos existentes no local. Para verificar sua versão, execute databricks -v.
  • Autenticação configurada para seu workspace do Databricks. Consulte Configurar acesso ao seu workspace.
  • Permissão CAN MANAGE no projeto Lakebase. Consulte Gerenciar permissões de projeto.
  • Um banco de dados Lakebase existente atualmente gerenciado por um pacote como database_instances. Se sua configuração incluir uma instância filha, catálogos ou tabelas sincronizadas, este guia também as abrange.

Esta página aborda database_instances, database_catalogs e synced_database_tables (tabelas sincronizadas). Databricks Apps ainda não são abordados.

Mapeamento de recursos​

provisionamento

Dimensionamento automático

Pai database_instances

postgres_projects além de um branch production criado implicitamente

Criança database_instances

postgres_branches cujo branch_id é igual ao da instância filha name

Endpoint de leitura e gravação da instância secundária

postgres_endpoints com endpoint_id = "primary" na branch filha

database_catalogs

postgres_catalogs cujo catalog_id é igual ao do catálogo name

synced_database_tables

postgres_synced_tables cujo synced_table_id é igual ao da tabela sincronizada name

O ID do projeto é o name da instância pai , em minúsculas. Caso não haja certeza (por exemplo, se o nome contiver letras maiúsculas), localize o seu projeto na lista de projetos do aplicativo Lakebase e consulte o seu project_id.

Etapa 1: Estado inicial (Provisionado)​

O databricks.yml inicial será algo assim. Os nomes são espaços reservados; utilize seus nomes reais. Inclua os blocos database_catalogs e synced_database_tables somente se o seu pacote os gerencia.

YAML
resources:
  database_instances:
    root:
      name: my-instance
      capacity: CU_2
    child:
      name: my-child
      capacity: CU_2
      parent_instance_ref:
        name: ${resources.database_instances.root.name}

  database_catalogs:
    cat:
      name: my-catalog
      database_instance_name: ${resources.database_instances.root.name}
      database_name: my_db
      create_database_if_not_exists: true

  synced_database_tables:
    orders_synced:
      name: my-catalog.default.orders_synced
      database_instance_name: ${resources.database_instances.root.name}
      logical_database_name: my_db
      spec:
        scheduling_policy: SNAPSHOT
        source_table_full_name: main.default.orders
        primary_key_columns:
          - id
        new_pipeline_spec:
          storage_catalog: main
          storage_schema: default

Passo 2 (implantado 1): Adote os autoscale recurso​

Adicione os recursos de autoscale ao pacote junto com os provisionados existentes. Os blocos provisionados permanecem na configuração durante este passo. O projeto, as branches e o endpoint usam um conjunto mínimo de campos. O catálogo e a tabela sincronizada precisam de mais alguns campos, incluindo a tabela de origem da tabela sincronizada, a chave primária e o armazenamento do pipeline.

YAML
resources:
  database_instances:
    root:
      name: my-instance
      capacity: CU_2
    child:
      name: my-child
      capacity: CU_2
      parent_instance_ref:
        name: ${resources.database_instances.root.name}

  database_catalogs:
    cat:
      name: my-catalog
      database_instance_name: ${resources.database_instances.root.name}
      database_name: my_db
      create_database_if_not_exists: true

  synced_database_tables:
    orders_synced:
      name: my-catalog.default.orders_synced
      database_instance_name: ${resources.database_instances.root.name}
      logical_database_name: my_db
      spec:
        scheduling_policy: SNAPSHOT
        source_table_full_name: main.default.orders
        primary_key_columns:
          - id
        new_pipeline_spec:
          storage_catalog: main
          storage_schema: default

  postgres_projects:
    pg_root:
      project_id: my-instance

  postgres_branches:
    pg_production:
      branch_id: production
      parent: ${resources.postgres_projects.pg_root.id}
    pg_child:
      branch_id: my-child
      parent: ${resources.postgres_projects.pg_root.id}

  postgres_endpoints:
    pg_child_rw:
      endpoint_id: primary
      parent: ${resources.postgres_branches.pg_child.id}
      endpoint_type: ENDPOINT_TYPE_READ_WRITE

  postgres_catalogs:
    pg_cat:
      catalog_id: my-catalog
      branch: ${resources.postgres_branches.pg_production.id}
      postgres_database: my_db
      create_database_if_missing: false

  postgres_synced_tables:
    pg_orders_synced:
      synced_table_id: my-catalog.default.orders_synced
      branch: ${resources.postgres_branches.pg_production.id}
      postgres_database: my_db
      source_table_full_name: main.default.orders
      primary_key_columns:
        - id
      scheduling_policy: SNAPSHOT
      new_pipeline_spec:
        storage_catalog: main
        storage_schema: default
nota

As chaves de recurso de um pacote devem ser únicas em todos os tipos de recurso em um único pacote. Os recursos de autoscale acima usam um prefixo pg_ para evitar conflitos com as chaves provisionadas existentes (root, child, cat, orders_synced).

Antes de implantar, vincule cada recurso de autoscale ao seu backend existente. A vinculação garante que a implantação adote os recursos existentes em vez de criar novos. O ID do recurso para cada comando bind é o nome canônico do recurso no workspace:

Bash
databricks bundle deployment bind pg_root \
  projects/my-instance

databricks bundle deployment bind pg_production \
  projects/my-instance/branches/production

databricks bundle deployment bind pg_child \
  projects/my-instance/branches/my-child

databricks bundle deployment bind pg_child_rw \
  projects/my-instance/branches/my-child/endpoints/primary

databricks bundle deployment bind pg_cat \
  catalogs/my-catalog

databricks bundle deployment bind pg_orders_synced \
  synced_tables/my-catalog.default.orders_synced

Após a vinculação, implantar o pacote:

Bash
databricks bundle deploy

A implantação adota os recursos de autoscale em estado de pacote sem recriá-los. Os dados permanecem inalterados.

Passo 3 (Implantação 2): remover os recursos provisionados do estado do pacote​

Depois que a implantação no passo 2 for concluída sem erros, remova as declarações provisionadas do pacote.

Para cada recurso provisionado, executar bundle deployment unbind. A próxima implantação em seguida para de acompanhar o recurso provisionado sem destruí-lo:

Bash
databricks bundle deployment unbind orders_synced
databricks bundle deployment unbind cat
databricks bundle deployment unbind child
databricks bundle deployment unbind root

Em seguida, remova o database_instances (ambas as entradas root e child), database_catalogs e os blocos synced_database_tables do YAML do seu pacote e reimplante:

Bash
databricks bundle deploy

O pacote não acompanha mais os recursos provisionados. Os dados permanecem. Os recursos de autoscale adotados no passo 2 agora gerenciam totalmente o banco de dados.

nota

unbind Remove os recursos provisionados do acompanhamento de pacote sem excluí-los, para que seu banco de dados continue em execução.

Funções e bancos de dados Postgres​

Funções e bancos de dados Postgres residem no seu banco de dados, não como recursos empacotados. A atualização do seu pacote não as altera. Eles permanecem na base de dados, disponíveis como antes.

O DABs ainda não disponibiliza funções ou bancos de dados Postgres como tipos de recurso de bundle. Para criar e gerenciá-los como código, use os recursos databricks_postgres_role e databricks_postgres_database do Terraform juntamente com seu pacote.

O que é possível após atualizar seu pacote​

Depois que o autoscale gerenciar seu projeto, será possível fazer coisas que não estavam disponíveis no provisionado. Alguns destaques:

Para um pacote completo que usa muitos desses juntos, consulte Gerenciar Lakebase com DABs.

nota

Para desativar totalmente um projeto mais tarde, databricks bundle destroy não funciona para o Lakebase (endpoints de leitura e gravação não podem ser excluídos individualmente). Consulte Limpar recursos para o método correto.

Veja também​

Nesta página