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

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

Este guia descreve como atualizar uma configuração do Terraform existente para usar os recursos do Lakebase Autoscaling (databricks_postgres_project, databricks_postgres_branch, databricks_postgres_endpoint).

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.
  • Uma instância de banco de dados Lakebase provisionada migrada com sucesso, atualmente gerenciada pelo Terraform como databricks_database_instance. Se a sua configuração incluir uma instância secundária, este guia também aborda isso. 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.

Esta página abrange databricks_database_instance. databricks_database_synced_database_table e databricks_database_catalog ainda não são abordados, e nem a troca de um aplicativo de um databricks_database_instance para um databricks_postgres_project recurso.

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

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 e my-child são placeholders; utilize os nomes que as suas instâncias reais já possuem. A instância raiz aqui é HA (um primário mais um secundário legível); caso a sua não seja, omita node_count e enable_readable_secondaries.

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

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

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

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.root e databricks_database_instance.child da configuração e, em seguida, adicione:

Hcl
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)

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.

Veja também​

Nesta página