Aller au contenu principal
Dernière mise à jour le

Mettez à jour votre configuration Terraform pour utiliser les ressources de mise à l'échelle automatique

Ce guide vous explique comment mettre à jour une configuration Terraform existante pour utiliser les Ressources Lakebase Autoscaling (databricks_postgres_project, databricks_postgres_branch, databricks_postgres_endpoint, databricks_postgres_catalog, databricks_postgres_synced_table).

Quand cela s'applique​

Avant de suivre ce guide, confirmez que votre instance Lakebase a été mise à niveau vers le dimensionnement automatique. Depuis le 12 mars 2026, les nouvelles instances Lakebase créées via l'API d'instances de base de données sont créées en tant que projets de dimensionnement automatique — votre configuration Terraform est la seule partie qui les référence encore en utilisant databricks_database_instance. Les instances provisionnées existantes sont également automatiquement mises à niveau vers le dimensionnement automatique à partir de juin 2026. Dans les deux cas, les étapes de mise à jour de la configuration Terraform sont les mêmes. Consultez la section « Confirmer que votre instance est en dimensionnement automatique » ci-dessous pour savoir si votre instance de base de données a été migrée avec succès ou non.

Fonctionnement de la mise à jour​

La mise à jour est in situ. Vos données ne sont ni déplacées ni copiées. Terraform cesse de suivre les ressources de provisionnement et commence à gérer la même base de données sous-jacente via les ressources de mise à l’échelle automatique, débloquant des capacités telles que le scale-to-zero et le branching.

Le changement nécessite exactement deux appels terraform apply : un pour adopter les ressources de mise à l'échelle automatique, et un pour supprimer les ressources provisionnées de l'état Terraform.

Pour les différences conceptuelles entre Provisionné et Dimensionnement automatique, consultez Dimensionnement automatique par default. Cette page couvre uniquement la mise à jour de la configuration Terraform.

Prérequis​

Avant de commencer, vous avez besoin de :

  • Terraform 1.7 ou version ultérieure. Les blocs import et removed ensemble nécessitent Terraform 1,7+.
  • Un Service Principal configuré pour l'authentification OAuth machine à machine (M2M) avec l'autorisation CAN MANAGE sur le projet. Voir Autoriser l'accès du Service Principal à Databricks avec OAuth et Gérer les autorisations du projet.
  • Une base de données Lakebase existante actuellement gérée par Terraform sous le nom databricks_database_instance. Si votre configuration inclut une instance enfant, un databricks_database_database_catalog ou un databricks_database_synced_database_table, ce guide les couvre également. Voir la section ci-dessous « Confirmer que votre instance utilise l'autoscaling » pour savoir si votre instance de base de données a été migrée avec succès ou non.
  • Si vous avez une table synchronisée à mettre à jour vers Autoscaling Terraform, ce guide suppose que la table Delta source existe déjà dans Unity Catalog avec une colonne id INTEGER NOT NULL. Ce guide s'y réfère en tant que main.default.orders; substituez le nom complet de votre table source réelle.

Le basculement d'une application d'une databricks_database_instance à une databricks_postgres_project Ressource n'est pas encore couvert.

Confirmez que votre instance est en dimensionnement automatique​

Avant de mettre à jour votre configuration Terraform, confirmez que la mise à niveau vers le dimensionnement automatique est terminée pour votre instance de base de données. Les blocs import de l'étape 2 adoptent un projet de dimensionnement automatique, des Branch et des Endpoint qui n'existent qu'une fois la mise à niveau terminée.

À vérifier :

  1. ouvrez la page **Provisionné** dans l'application Lakebase, trouvez votre instance, et accédez à la page d'instance.
  2. Une bannière sur la page de l'instance confirme si la mise à niveau s'est terminée avec succès.
  3. Cliquez sur « Accéder à l'interface utilisateur de l'autoscaling ». Lorsque vous êtes sur la page du projet d'interface utilisateur de l'autoscaling, cliquez sur « Settings ». Trouvez le nom de la Ressource, cliquez sur les deux carrés près du champ de saisie du nom de la Ressource pour copier le nom de la Ressource du projet d'autoscaling. Vous l'utiliserez pour référencer les ressources dans le bloc d'importation Terraform.

Si la mise à niveau n'est pas encore terminée, attendez qu'elle le soit avant de poursuivre. Pour demander une mise à niveau accélérée, contactez votre équipe de compte ou le support Databricks.

Mappage des ressources​

provisionnement

Dimensionnement automatique

Parent databricks_database_instance

databricks_postgres_project plus une Branch production créée implicitement

Endpoint en lecture-écriture de l'instance parente

databricks_postgres_endpoint avec endpoint_id = "primary" sur la Branch production

HA de l’instance parente (node_count, secondaires lisibles)

un compute group de l'Endpoint production spec

Enfant databricks_database_instance (facultatif)

databricks_postgres_branch dont le branch_id est égal à celui de l'instance enfant name

Endpoint en lecture-écriture de l’instance enfant

databricks_postgres_endpoint avec endpoint_id = "primary" sur la Branch enfant

databricks_database_database_catalog (facultatif)

databricks_postgres_catalog avec le même catalog_id

databricks_database_synced_database_table (facultatif)

databricks_postgres_synced_table avec le même synced_table_id

provisionnement

Dimensionnement automatique

Parent databricks_database_instance

databricks_postgres_project plus une Branch production créée implicitement

Endpoint en lecture-écriture de l'instance parente

databricks_postgres_endpoint avec endpoint_id = "primary" sur la Branch production

HA de l’instance parente (node_count, secondaires lisibles)

un compute group de l'Endpoint production spec

Enfant databricks_database_instance (facultatif)

databricks_postgres_branch dont le branch_id est égal à celui de l'instance enfant name

Endpoint en lecture-écriture de l’instance enfant

databricks_postgres_endpoint avec endpoint_id = "primary" sur la Branch enfant

databricks_database_database_catalog (facultatif)

databricks_postgres_catalog avec le même catalog_id

databricks_database_synced_database_table (facultatif)

databricks_postgres_synced_table avec le même synced_table_id

Chaque instance provisionnée est mappée à une Branch nommée production sur son projet de mise à l'échelle automatique. Une instance enfant est l'exception : elle correspond à une Branch distincte dont le branch_id est égal au name de l'instance enfant.

L'ID de projet est l'ID de votre instance name **parente**, en minuscules — si le nom contient des majuscules, l'ID de projet est la forme en minuscules. Confirmez-le dans l'interface utilisateur de Databricks avant d'importer. Tous les ID d'importation de Branch utilisent cet ID de projet comme segment de projet, même pour la Branch enfant.

Étape 1 : État initial (Provisionné)​

Votre configuration de départ se présente comme suit. Les noms my-instance, my-child, my-catalog, my_db et main.default.orders sont des espaces réservés ; utilisez les noms que vos véritables Ressources possèdent déjà. L'instance racine ici est HA (un primaire plus un secondaire lisible) ; si la vôtre ne l'est pas, omettez node_count et enable_readable_secondaries. Les blocs de catalogue et de table synchronisée sont facultatifs — ne conservez que ceux que votre configuration utilise déjà.

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

Étape 2 (Appliquer 1) : Adoptez les ressources d'autoscaling​

Ajoutez les nouvelles ressources de mise à l’échelle automatique à côté des ressources provisionnées existantes. Conservez les blocs databricks_database_instance existants dans la configuration — les nouvelles ressources Autoscaling se trouvent à côté d'eux. Le projet et les deux Branches utilisent un bloc import. Les deux Endpoint (celui de la Branch production et celui de la Branch enfant) utilisent replace_existing = true au lieu d'un bloc import, car les Endpoint ne prennent pas en charge les blocs import standard aujourd'hui. terraform plan affichera les endpoints comme « seront créés », ce qui est le comportement attendu pour les objectifs de migration — rien n'est recréé côté serveur, vos ressources sont en sécurité.

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

Pour le spec de l'Endpoint, choisissez l'une des variantes ci-dessous.

remarque

Pourquoi spec = null sur le catalogue et la table synchronisée. Aujourd'hui, après terraform import, le spec du catalogue et de la table synchronisée revient vide de la lecture du fournisseur (les champs de saisie à l'intérieur de spec sont traités en écriture seule). Si vous laissez spec rempli en HCL, Terraform compare le HCL rempli avec l'état vide et prévoit de détruire et de recréer la ressource. Définir spec = null ne donne rien à comparer à Terraform, donc l'importation est maintenue. Vos données ne sont pas modifiées — le serveur dispose déjà de la configuration correcte depuis la création des ressources provisionnées. Les champs de spécification sont également IMMUTABLE sur ces ressources, donc même si vous pouviez insérer des valeurs en HCL, vous ne pourriez pas les modifier par la suite. Les Endpoints, les projets et les branches n'ont pas besoin de spec = null car leurs spec effectuent des allers-retours via la lecture correctement.

Adoptez l'Endpoint existant tel quel. Aucun changement de comportement côté serveur pendant l'adoption.

Hcl
spec = {
  endpoint_type = "ENDPOINT_TYPE_READ_WRITE"
}
remarque

Préservation de la haute disponibilité. L'Endpoint production ci-dessus porte la haute disponibilité de l'instance parente en tant que compute group: min et max sont égaux au node_count de l'instance, et enable_readable_secondaries correspond à l'instance. Les endpoints HA doivent définir no_suspension = true, de sorte qu'un endpoint HA ne peut pas non plus mettre à l'échelle à zéro.

Chaque choix est un terraform apply unique.

Exécuter terraform apply.

Étape 3 (Appliquer 2) : Supprimez les ressources provisionnées de l'état Terraform​

Une fois que vous êtes sûr que les ressources d'Autoscaling gèrent correctement votre base de données, supprimez les blocs databricks_database_instance d'origine de l'état Terraform. Utilisez un bloc removed avec lifecycle.destroy = false pour que Terraform cesse de gérer la ressource de provisionnement sans supprimer de données.

Supprimez les databricks_database_instance blocs et tous les blocs databricks_database_database_catalog / databricks_database_synced_database_table de la configuration, puis ajoutez un bloc removed {} pour chacun.

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

Exécuter terraform apply.

Dans la sortie du plan, vous verrez des lignes comme :

# 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.
...

C'est prévu. Les données restent. Terraform cesse de suivre la ressource provisionnée et gère désormais votre base de données via les ressources d'autoscaling que vous avez adoptées à l'étape 2.

Rôles et bases de données Postgres​

Une fois que les ressources d'Autoscaling sont dans votre configuration, vous pouvez utiliser Terraform pour créer et mettre à jour les rôles et les bases de données Postgres désormais via databricks_postgres_role et databricks_postgres_database. Les rôles et les bases de données qui existent déjà dans votre base de données mais qui ne sont pas déclarés dans Terraform ne seront pas supprimés — Terraform ne détruit que les ressources qu'il suit en l'état. L’importation des rôles et des bases de données qui existaient avant la mise à jour de la configuration n’est pas encore prise en charge. Consultez les pages de référence databricks_postgres_role et databricks_postgres_database, ou Configuration de projet Lakebase type avec Terraform pour un exemple complet.

Comme la Branch production et le Endpoint primary, chaque projet de mise à l'échelle automatique possède également un rôle et une base de données créés implicitement.

Ce qui est possible maintenant que vous avez mis à niveau​

Une fois votre projet géré en mode de dimensionnement automatique, vous pouvez faire des choses qui n'étaient pas disponibles en mode provisionnement. Quelques points forts :

Pour une configuration Terraform complète et prête pour la production qui utilise plusieurs de ces éléments conjointement, consultez Configuration typique d'un projet Lakebase avec Terraform.

Ressources supplémentaires​

Sur cette page