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

Atualize sua configuração do Terraform para usar recursos de autoscale

Este guia orienta você sobre como atualizar uma configuração existente do Terraform para usar os recursos de autoscale do Lakebase (databricks_postgres_project, databricks_postgres_branch, databricks_postgres_endpoint, databricks_postgres_catalog, databricks_postgres_synced_table).

Quando aplicável​

Antes de seguir este guia, confirme se sua instância do Lakebase foi atualizada para o Autoscaling. Desde 12 de março de 2026, novas instâncias Lakebase criadas pela API de instâncias de banco de dados são criadas como projetos de escalonamento automático — sua configuração do Terraform é a única parte que ainda as referencia usando databricks_database_instance. As instâncias provisionadas existentes também estão sendo atualizadas automaticamente para o autoscale a partir de junho de 2026. Em ambos os casos, os passos de atualização da configuração do Terraform são os mesmos. Consulte a seção 'Confirme se a sua instância está com autoscale' abaixo para descobrir se a sua instância de banco de dados foi migrada com sucesso ou ainda não.

Como a atualização funciona​

A atualização está no local. Seus dados não são movidos nem copiados. O Terraform para de acompanhar os recursos provisionados e começa a gerenciar o mesmo banco de dados subjacente por meio dos recursos de autoscale, desbloqueando recursos como escala para zero e ramificação.

A alteração exige exatamente duas chamadas de terraform apply: uma para adotar os recursos de autoscale e outra para remover os provisionados do estado do Terraform.

Para as diferenças conceituais entre provisionamento e autoscale, consulte Autoscale por default. Esta página aborda apenas a atualização da configuração do Terraform.

Pré-requisitos​

Antes de começar, é preciso:

  • Terraform 1,7 ou superior. Os blocos import e removed juntos exigem o Terraform 1.7+.
  • Uma entidade de serviço configurada para autenticação OAuth machine-to-machine (M2M) com permissão CAN MANAGE (Pode gerenciar) no projeto. Consulte Autorizar o acesso da entidade de serviço ao Databricks com OAuth e Gerenciar permissões de projeto.
  • Um banco de dados Lakebase existente atualmente gerenciado pelo Terraform como databricks_database_instance. Se a sua configuração incluir uma instância secundária, um databricks_database_database_catalog ou um databricks_database_synced_database_table, este guia também os abrange. Consulte a seção 'Confirme se a sua instância está com autoscale' abaixo para descobrir se a sua instância de banco de dados foi migrada com sucesso ou ainda não.
  • Se você tem uma tabela sincronizada para atualizar para o Terraform com dimensionamento automático, este guia assume que a tabela Delta de origem já existe no Unity Catalog com uma coluna id INTEGER NOT NULL. Este guia refere-se a ele como main.default.orders; substitua o nome completo da sua tabela de origem real.

A troca de um aplicativo de um databricks_database_instance para um databricks_postgres_project recurso ainda não está coberta.

Confirme se sua instância está com o Dimensionamento automático ativado​

Antes de atualizar sua configuração do Terraform, confirme se a atualização para o autoscale foi concluída para sua instância de banco de dados. Os blocos import no Passo 2 adotam um projeto de autoscale, branches e endpoints que só existem após a conclusão da atualização.

Verificar:

  1. Abra a página **Provisionada** no aplicativo Lakebase, encontre sua instância e clique para a página da instância.
  2. Um banner na página da instância confirma se a atualização foi concluída com sucesso.
  3. Clique em "Ir para a IU de autoscale". Quando estiver na página do projeto de UI do Autoscale, clique em "Configurações". Encontre o nome do recurso, clique nos dois quadrados próximos ao campo de entrada do nome do recurso para copiar o nome do recurso do projeto de Autoscale. Será utilizado para fazer referência aos recursos no bloco de importação do Terraform.

Se a atualização ainda não estiver concluída, aguarde até que esteja antes de prosseguir. Para solicitar um upgrade expedito, entre em contato com sua equipe de conta ou o Suporte Databricks.

Mapeamento de recursos​

provisionamento

Dimensionamento automático

Pai databricks_database_instance

databricks_postgres_project além de um branch production criado implicitamente

Endpoint de leitura e gravação da instância principal

databricks_postgres_endpoint com endpoint_id = "primary" na branch production

Instância principal HA (node_count, secundários legíveis)

um compute group do endpoint production spec

Filho databricks_database_instance (opcional)

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

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

databricks_postgres_endpoint com endpoint_id = "primary" na branch filha

databricks_database_database_catalog (opcional)

databricks_postgres_catalog com o mesmo catalog_id

databricks_database_synced_database_table (opcional)

databricks_postgres_synced_table com o mesmo synced_table_id

Cada instância provisionada mapeia para um branch chamado production em seu projeto de autoscale. Uma instância filha é a exceção: ela é mapeada para uma ramificação separada cujo branch_id é igual ao name da instância filha.

O ID do projeto é nameo da sua instância **pai**, em letras minúsculas — se o nome contiver letras maiúsculas, o ID do projeto será a sua forma em minúsculas. Confirme isso na interface do usuário do Databricks antes de importar. Todos os IDs de importação de branch usam esse ID de projeto como o segmento de projeto, mesmo para o branch filho.

Etapa 1: Estado inicial (Provisionado)​

A configuração inicial é a seguinte. Os nomes my-instance, my-child, my-catalog, my_db e main.default.orders são espaços reservados; use os nomes que seus recursos reais já possuem. A instância raiz aqui é HA (uma primária mais uma secundária legível); se a sua não for, omita node_count e enable_readable_secondaries. Os blocos de catálogo e de tabela sincronizada são opcionais — deve-se manter apenas aqueles que a sua configuração já utiliza.

Hcl
terraform {
  required_providers {
    databricks = {
      source = "databricks/databricks"
    }
  }
}

resource "databricks_database_instance" "root" {
  name     = "my-instance"
  capacity = "CU_2"
  node_count                  = 2
  enable_readable_secondaries = true
}

resource "databricks_database_instance" "child" {
  name     = "my-child"
  capacity = "CU_2"
  parent_instance_ref = {
    name = databricks_database_instance.root.name
  }
}

resource "databricks_database_database_catalog" "cat" {
  name                          = "my-catalog"
  database_instance_name        = databricks_database_instance.root.name
  database_name                 = "my_db"
  create_database_if_not_exists = true
}

resource "databricks_database_synced_database_table" "syt" {
  name                  = "my-catalog.default.orders_synced"
  logical_database_name = databricks_database_database_catalog.cat.database_name
  spec = {
    scheduling_policy                  = "SNAPSHOT"
    source_table_full_name             = "main.default.orders"
    primary_key_columns                = ["id"]
    create_database_objects_if_missing = true
    new_pipeline_spec = {
      storage_catalog = "main"
      storage_schema  = "default"
    }
  }
}

Passo 2 (Aplicar 1): adotar os recursos de autoscale​

Adicione os novos recursos de autoscale juntamente com os provisionados existentes. Mantenha os blocos databricks_database_instance existentes na configuração — os novos recursos de autoscale ficam ao lado deles. O projeto e ambos os branches usam um bloco import. Os dois endpoints (da branch production e da branch filha) usam replace_existing = true em vez de um bloco import, porque os endpoints não suportam blocos import padrão hoje. terraform plan mostrará os endpoints como "será criado", o que é o comportamento esperado para fins de migração — nada é recriado no lado do servidor, seus recursos estão seguros.

Hcl
# In Lakebase Autoscaling, the parent database instance is represented
# by a project plus an implicitly created "production" branch.
resource "databricks_postgres_project" "root" {
  project_id = "my-instance"  # use the ID from section "Confirm your instance is on Autoscaling"
  spec       = null
}

# Branch corresponding to the parent database_instance.
resource "databricks_postgres_branch" "production" {
  branch_id = "production"
  parent    = databricks_postgres_project.root.name
  spec      = null
}

# Branch corresponding to the child database_instance.
resource "databricks_postgres_branch" "child" {
  branch_id = "my-child"
  parent    = databricks_postgres_project.root.name
  spec      = null
  # spec = null is required during adoption. Setting any spec field causes
  # Terraform to write that value on apply. Fields like source_branch,
  # source_branch_lsn, and endpoint_type are immutable in Lakebase —
  # specifying them forces Terraform to replace (delete and recreate) the
  # resource instead of importing it cleanly. After adoption is complete
  # you can populate mutable fields (such as is_protected) to manage the
  # branch going forward. To look up the source branch, read it from
  # Branch.status.source_branch.
}

# The child branch's primary read-write endpoint.
# Pick one of the spec variants from the tabs below.
resource "databricks_postgres_endpoint" "child_rw_endpoint" {
  endpoint_id = "primary"
  parent      = databricks_postgres_branch.child.name
  spec = {
    endpoint_type = "ENDPOINT_TYPE_READ_WRITE"
  }
  replace_existing = true
}

# The production branch's primary read-write endpoint. Because the parent
# instance is HA, its HA carries over here as a compute `group` (see the
# "Preserving HA" note below). If your parent instance isn't HA, drop the
# `group` and `no_suspension` and keep only `endpoint_type`. If
resource "databricks_postgres_endpoint" "production_rw_endpoint" {
  endpoint_id = "primary"
  parent      = databricks_postgres_branch.production.name
  spec = {
    endpoint_type = "ENDPOINT_TYPE_READ_WRITE"
    no_suspension = true
    group = {
      min                         = 2
      max                         = 2
      enable_readable_secondaries = true
    }
  }
  replace_existing = true
}

# Import the project. Postgres resources use the canonical
# "projects/{project_id}" form as the import ID, where project_id is
# the resource name from section "Confirm your instance is on Autoscaling",
# with "projects/" prefix stripped off.
import {
  to = databricks_postgres_project.root
  id = "projects/my-instance"
}

# Import the production branch. The Provisioned parent always maps to
# a branch named "production" on the new project.
# Use the resource name from section "Confirm your instance is on Autoscaling",
# append "/branches/production" to it.
import {
  to = databricks_postgres_branch.production
  id = "projects/my-instance/branches/production"
}

# Import the child branch. Use the resource name from section
# "Confirm your instance is on Autoscaling", same as when importing
# the "production" branch above. The branch segment is the child instance's name.
import {
  to = databricks_postgres_branch.child
  id = "projects/my-instance/branches/my-child"
}

# The catalog. Pin `catalog_id` to the same name your
# databricks_database_database_catalog already uses, written as a
# literal so the new resource does not depend on the old one. `spec
# = null` is required during adoption — see the "Why spec = null on
# catalog and synced table" note below.
resource "databricks_postgres_catalog" "cat" {
  catalog_id = "my-catalog"
  spec       = null
}

import {
  to = databricks_postgres_catalog.cat
  id = "catalogs/my-catalog"
}

# The synced table. Pin `synced_table_id` to the same fully-qualified
# name your databricks_database_synced_database_table already uses,
# again as a literal.
# `depends_on` is required to build the correct Terraform dependency graph,
# for correct resource management.
resource "databricks_postgres_synced_table" "syt" {
  synced_table_id = "my-catalog.default.orders_synced"
  spec            = null
  depends_on = [
    databricks_postgres_catalog.cat
  ]
}

import {
  to = databricks_postgres_synced_table.syt
  id = "synced_tables/my-catalog.default.orders_synced"
}

Para o spec do endpoint, escolha uma das variantes abaixo.

nota

Por que spec = null no catálogo e na tabela sincronizada. Hoje, após terraform import, o spec do catálogo e da tabela sincronizada retorna vazio da Leitura do provedor (os campos de entrada dentro de spec são tratados como somente gravação). Se você deixar spec preenchido no HCL, o Terraform diferencia o HCL preenchido em relação ao estado vazio e planeja destruir e recriar o recurso. Definir spec = null não fornece nada para o Terraform diferenciar, de modo que a importação se mantém. Seus dados não são tocados — o servidor já tem a configuração correta desde que os recursos provisionados foram criados. Os campos de especificação também são IMMUTABLE nesses recursos, então, mesmo que você pudesse inserir valores em HCL, você não conseguiria alterá-los depois. Endpoints, projetos e branches não precisam de spec = null porque suas spec idas e voltas pela Leitura são feitas corretamente.

Adotar o endpoint existente como está. Nenhuma alteração de comportamento no lado do servidor durante a adoção.

Hcl
spec = {
  endpoint_type = "ENDPOINT_TYPE_READ_WRITE"
}
nota

Preservar Alta Disponibilidade. O production endpoint acima carrega o HA da instância pai como um compute group: min e max são iguais ao node_count da instância, e enable_readable_secondaries corresponde à instância. Endpoints HA devem definir no_suspension = true, portanto, um endpoint HA também não pode escalar para zero.

Cada escolha é um único terraform apply.

Execute terraform apply.

Passo 3 (Aplicar 2): Remover os recursos provisionados do estado do Terraform​

Após garantir que os recursos de autoscale estão gerenciando seu banco de dados corretamente, exclua os blocos databricks_database_instance originais do estado do Terraform. Use um bloco removed com lifecycle.destroy = false para que o Terraform pare de gerenciar o recurso provisionado sem excluir nenhum dado.

Remova os blocos databricks_database_instance e quaisquer blocos databricks_database_database_catalog / databricks_database_synced_database_table da configuração e, em seguida, adicione um bloco removed {} para cada um deles.

Hcl
removed {
  from = databricks_database_synced_database_table.syt
  lifecycle {
    destroy = false
  }
}

removed {
  from = databricks_database_database_catalog.cat
  lifecycle {
    destroy = false
  }
}

removed {
  from = databricks_database_instance.child
  lifecycle {
    destroy = false  # it is crucial to set destroy = false. Not doing so results in your database being deleted.
  }
}

removed {
  from = databricks_database_instance.root
  lifecycle {
    destroy = false
  }
}

Execute terraform apply.

Na saída do plano, serão exibidas linhas como:

# databricks_database_instance.root will no longer be managed by Terraform, but will not be destroyed
# (destroy = false is set in the configuration)
...
... and similar entry for each of the resource you have used removed block for.
...

Isto é esperado. Os dados permanecem. O Terraform simplesmente para de acompanhar o recurso provisionado e agora gerencia seu banco de dados por meio dos recursos de autoscale que você adotou no passo 2.

Funções e bancos de dados Postgres​

Uma vez que os recursos de autoscale estejam em sua configuração, você pode usar o Terraform para criar e atualizar funções e bancos de dados do Postgres futuramente por meio de databricks_postgres_role e databricks_postgres_database. Funções e bancos de dados que já existem no seu banco de dados, mas não são declarados no Terraform, não serão removidos — o Terraform só destrói recursos que ele monitora no estado. A importação de funções e bancos de dados que existiam antes da atualização da configuração ainda não é compatível. Consulte as databricks_postgres_role e databricks_postgres_database páginas de referência, ou Configuração Típica de Projeto Lakebase com Terraform para um exemplo completo.

Assim como o branch production e o endpoint primary, todo projeto de autoscale também tem uma função e um banco de dados criados implicitamente.

O que é possível agora que você atualizou​

Uma vez que seu projeto seja gerenciado como autoscale, será possível fazer coisas que não estavam disponíveis no modelo de provisionamento. Alguns destaques:

Para uma configuração Terraform completa pronta para produção que usa muitos deles juntos, consulte Configuração típica de projeto Lakebase com Terraform.

Recursos adicionais​

Nesta página