Update your bundle to use Autoscaling resources

This guide walks you through updating an existing Databricks Asset Bundle (DAB). The update converts a Lakebase Provisioned setup (a database_instances resource, optionally with a child instance, catalogs, and synced tables) to Lakebase Autoscaling resources (postgres_projects, postgres_branches, postgres_endpoints, and optionally postgres_catalogs and postgres_synced_tables).

When this applies

Your Lakebase database already runs on the Autoscaling platform. As of March 12, 2026, the Database instance API creates new Lakebase instances as Autoscaling projects. Your bundle is the only part that still references them using database_instances. Starting June 2026, Databricks automatically upgrades existing Provisioned instances to Autoscaling. In both cases, the bundle update steps are the same.

How the update works

The update is in-place. Databricks doesn't move or copy your data. The bundle stops tracking the Provisioned resources and starts managing the same underlying database through the Autoscaling resources. This unlocks features like scale-to-zero and branching.

The change takes two databricks bundle deploy calls, with databricks bundle deployment bind and unbind commands between them to manage the bundle state transition.

For the conceptual differences between Provisioned and Autoscaling, see Upgrade to Autoscaling. This page covers only the bundle configuration update.

Prerequisites

Before you begin, you must have:

• Databricks CLI version 1.2.0 or higher, which updates your existing resources in place. To check your version, run databricks -v.
• Authentication configured for your Databricks workspace. See Configure access to your workspace.
• CAN MANAGE permission on the Lakebase project. See Manage project permissions.
• An existing Lakebase database currently managed by a bundle as database_instances. If your setup includes a child instance, catalogs, or synced tables, this guide covers those too.

This page covers database_instances, database_catalogs, and synced_database_tables (synced tables). Databricks Apps are not yet covered.

Resource mapping

Provisioned	Autoscaling
Parent database_instances	postgres_projects plus an implicitly created production branch
Child database_instances	postgres_branches whose branch_id equals the child instance's name
Child instance's read-write endpoint	postgres_endpoints with endpoint_id = "primary" on the child branch
database_catalogs	postgres_catalogs whose catalog_id equals the catalog's name
synced_database_tables	postgres_synced_tables whose synced_table_id equals the synced table's name

The project ID is the parent instance's name, lowercased. If you're unsure (for example, the name had uppercase letters), find your project in the Lakebase app's projects list and read its project_id.

Step 1: Starting state (Provisioned)

Your starting databricks.yml looks something like this. The names are placeholders; use your real names. Include the database_catalogs and synced_database_tables blocks only if your bundle manages them.

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

Step 2 (Deploy 1): Adopt the Autoscaling resources

Add the Autoscaling resources to the bundle alongside the existing Provisioned ones. The Provisioned blocks stay in the configuration during this step. The project, branches, and endpoint use a minimal field set. The catalog and synced table need a few more fields, including the synced table's source table, primary key, and pipeline storage.

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

note

Bundle resource keys must be unique across all resource types in a single bundle. The Autoscaling resources above use a pg_ prefix to avoid colliding with the existing Provisioned keys (root, child, cat, orders_synced).

Before deploying, bind each Autoscaling resource to its existing backend. Binding ensures the deploy adopts the existing resources instead of creating new ones. The resource ID for each bind command is the resource's canonical name in the 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

After binding, deploy the bundle:

Bash

databricks bundle deploy

The deploy adopts the Autoscaling resources into bundle state without recreating them. Your data remains unaffected.

Step 3 (Deploy 2): Remove the Provisioned resources from bundle state

After the deploy in step 2 completes without errors, drop the Provisioned declarations from the bundle.

For each Provisioned resource, run bundle deployment unbind. The next deploy then stops tracking the Provisioned resource without destroying it:

Bash

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

Then remove the database_instances (both the root and child entries), database_catalogs, and synced_database_tables blocks from your bundle YAML and redeploy:

Bash

databricks bundle deploy

The bundle no longer tracks the Provisioned resources. The data stays. The Autoscaling resources you adopted in step 2 now manage your database entirely.

note

unbind removes the Provisioned resources from bundle tracking without deleting them, so your database keeps running.

Postgres roles and databases

Postgres roles and databases live in your database, not as bundle resources. Updating your bundle doesn't change them. They remain in the database, available as before.

DABs doesn't yet make Postgres roles or databases available as bundle resource types. To create and manage them as code, use the databricks_postgres_role and databricks_postgres_database Terraform resources alongside your bundle.

What's possible after updating your bundle

After Autoscaling manages your project, you can do things that weren't available on Provisioned. Some highlights:

• Branching. Create instant, isolated copies of your database for development, testing, or recovery. Includes protected branches and point-in-time branching.
• Scale to zero. Pause compute on inactive branches to save cost.
• Instant restore. Recover to any moment within your retention window (up to 30 days).
• Read replicas. Separate read-only compute endpoints sharing the same storage.
• Snapshots. Point-in-time captures of your root branch, manual or scheduled.

For a complete bundle that uses many of these together, see Manage Lakebase with DABs.

note

To fully decommission a project later, databricks bundle destroy doesn't work for Lakebase (read-write endpoints can't be deleted individually). See Clean up resources for the correct method.

See also

• Upgrade to Autoscaling
• Manage Lakebase with DABs
• Bundle resources reference
• Databricks bundle deployment