Manage instance capacity

This page explains the options for right-sizing your Lakebase instance capacity and how to manage it.

Change instance capacity

To resize an instance, you must have CAN MANAGE permissions. Resizing can take several minutes. The capacity change takes effect when the instance is restarted.

UI

1. Open a running instance. See Access a database instance.
2. Click Edit in the upper-right corner.
3. Use the Capacity drop-down menu to select the new instance size.
4. Click Save.

curl

curl -X PATCH --header "Authorization: Bearer ${DATABRICKS_TOKEN}" https://$WORKSPACE/api/2.0/database/instances/$INSTANCE_NAME \
--data-binary @- << EOF
{
  "capacity": "CU_4"
}
EOF

Python SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.database import DatabaseInstance

# Initialize the Workspace client
w = WorkspaceClient()

# Update the capacity
instance_name = "my-database-instance"
w.database.update_database_instance(
    name=instance_name,
    database_instance=DatabaseInstance(
        name=instance_name,
        capacity="CU_4"
    ),
    update_mask="*"
)
print(f"Updated capacity for database instance: {instance_name}")

CLI

# Update a database instance
databricks database update-database-instance my-database-instance \
  --capacity CU_1

# Update using JSON
databricks database update-database-instance my-database-instance \
  --json '{
    "capacity": "CU_2"
  }'

Best practices

Each capacity unit allocates about 16GB of RAM to the database instance, along with all associated CPU and local SSD resources. Scaling up increases these resources linearly. Postgres distributes the allocated memory across multiple components:

• Database caches
• Worker memory
• Other processes with fixed memory requirements

Performance varies based on data size and query complexity.

Before scaling, test and optimize queries. Storage scales automatically.