Create and manage a database instance

Important

Lakebase Provisioned is the original Lakebase offering that uses provisioned compute you scale manually. For supported regions, see Region availability. For the latest version of Lakebase, with autoscaling compute, scale-to-zero, branching, and instant restore, see Lakebase Autoscaling.

New Lakebase instances will be created as Autoscaling projects. Rollout starts March 12, 2026. For details, see Autoscaling by default.

To get started with OLTP workloads, create a Lakebase Provisioned database instance using the Azure Databricks UI, API call, Python SDK, or CLI.

Create a database instance

Create a database instance with recommended defaults. You need to provide an instance name (1-63 characters, letters and hyphens only). As the creator, you are the database owner with the databricks_superuser role.

Most workspace users can create database instances by default. If you encounter permission issues, see database instance permissions.

UI

Click Apps in the top right corner and select Lakebase Postgres.
Click Provisioned to open the Provisioned instances page.
Click Create database instance.
Configure your instance:
- Name: Enter a database instance name (1-63 characters, letters and hyphens only).
- Capacity: Select the compute size (default: 2 CU). See Instance size.
- Serverless usage policy: Select a budget policy to attribute serverless usage and billing (optional). See Serverless usage policies.
(Optional) Expand Advanced Settings to configure:
- Create from parent: Create a copy-on-write clone from an existing instance, including data up to a specific point in time. See Create from parent.
- Enable HA: Enable high availability with failover nodes, configure readable secondaries, and set the number of HA nodes. See High availability.
Click Create.

Python SDK

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

# Initialize the Workspace client
w = WorkspaceClient()

# Create a database instance
instance = w.database.create_database_instance(
    DatabaseInstance(
        name="my-database-instance",
        capacity="CU_1"
    )
)

print(f"Created database instance: {instance.name}")
print(f"Connection endpoint: {instance.read_write_dns}")

CLI

# Create a database instance
databricks database create-database-instance my-database-instance \
  --capacity CU_1

# Create with advanced options (using JSON for more complex parameters)
databricks database create-database-instance \
  --json '{
    "name": "my-database-instance",
    "capacity": "CU_2",
    "retention_window_in_days": 14
  }'

curl

Create a database instance and specify a retention window.

export PAT=<YOUR_PAT>
export INSTANCE_NAME="instance_name"

> curl -X POST --header "Authorization: Bearer ${DATABRICKS_TOKEN}" https://[your databricks workspace]/api/2.0/database/instances \
--data-binary @- << EOF
{
  "name": "$INSTANCE_NAME",
  "capacity": "CU_1",
  "retention_window_in_days": 14
}
EOF

Advanced settings

You can also configure these features during creation or after creation by editing your instance:

Feature	Description
Serverless usage policy	Select a budget policy for your database instance to attribute serverless usage and billing to specific budgets. You can also add custom tags.
Instance size	Scale compute resources for your workload performance requirements (defaults to 2 CU).
Restore window	Set the retention window (2-35 days, default 7 days) for point-in-time recovery.
High availability	Add failover nodes to ensure business continuity for production workloads.
Create from parent	Create a copy-on-write clone from an existing database instance.

Stop or start an instance

To stop or start a database instance, you must have CAN MANAGE permissions on it. To stop or start an instance, use the Azure Databricks UI, API call, Python SDK, or CLI.

UI

Click Apps in the top right corner and select Lakebase Postgres.
Click Provisioned to open the Provisioned instances page.
Click the database instance you want to stop or start.
Click Stop or Start in the upper-right corner of the page.

Python SDK

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

# Initialize the Workspace client
w = WorkspaceClient()

# Stop a database instance
instance_name = "my-database-instance"
w.database.update_database_instance(
    name=instance_name,
    database_instance=DatabaseInstance(
        name=instance_name,
        stopped=True
    ),
    update_mask="*"
)
print(f"Stopped database instance: {instance_name}")

# Start a database instance
w.database.update_database_instance(
    name=instance_name,
    database_instance=DatabaseInstance(
        name=instance_name,
        stopped=False
    ),
    update_mask="*"
)
print(f"Started database instance: {instance_name}")

CLI

# Stop a database instance
databricks database update-database-instance my-database-instance '*' \
  --json '{
    "stopped": true
  }'

# Start a database instance
databricks database update-database-instance my-database-instance '*' \
  --json '{
    "stopped": false
  }'

curl

The following API call stops a database instance.

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

The following API call starts a database instance.

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

Behavior when stopped

Database instance behavior:

Data is preserved.
The instance cannot be used for read or write operations.
Synced tables do not serve reads.
Lakeflow Spark Declarative Pipelines (LDP) do not detect stopped instances and might return errors.
Registered catalogs on stopped instances do not show schema details in the UI.

Functional limitations:

You cannot create or delete DatabaseTables or DatabaseCatalogs.
You can delete or resize a stopped instance. Capacity changes take effect when the instance restarts.
You can stop pipelines.

Behavior when started

The instance enters the STARTING state and becomes AVAILABLE when ready.

Limitations

LDP do not detect stopped instances and can return errors.
Registered catalogs on stopped instances do not show schema details in the UI.

Delete an instance

Be cautious when deleting the database instance, as doing so will delete all associated data.

You must have CAN MANAGE permissions on the database instance. If you are not the owner of the tables or catalogs, you must reassign ownership to yourself. Workspace admins can delete database instances they do not own.

Databricks recommends deleting all associated Unity Catalog catalogs, synced tables, and child instances before deleting the database instance. Otherwise, attempting to view catalogs or run SQL queries that reference them results in errors.

UI

Click Apps in the top right corner and select Lakebase Postgres.
Click Provisioned to open the Provisioned instances page.
Select the database instance you want to delete.
Select Catalogs in the Lakebae App sidebar to view the full list of database catalogs associated with the database instance.
For each database catalog, delete all synced tables, including those that are located in managed catalogs and are not registered as database catalogs.
Click > Delete catalog.

Python SDK

from databricks.sdk import WorkspaceClient

# Initialize the Workspace client
w = WorkspaceClient()

# Delete a database instance
instance_name = "my-database-instance"
w.database.delete_database_instance(
    name=instance_name,
    purge=True  # Required to delete the instance
)
print(f"Deleted database instance: {instance_name}")

# Delete with force option (to delete child instances too)
w.database.delete_database_instance(
    name=instance_name,
    force=True,  # Delete child instances too
    purge=True
)

CLI

# Delete a database instance
databricks database delete-database-instance my-database-instance \
  --purge

# Delete with force option (to delete child instances too)
databricks database delete-database-instance my-database-instance \
  --json '{
    "force": true,
    "purge": true
  }'

curl

purge=true must be specified to delete a database instance.

curl -X DELETE --header "Authorization: Bearer ${DATABRICKS_TOKEN}" https://$WORKSPACE/api/2.0/database/instances/$INSTANCE_NAME?purge=true

Update a serverless usage policy of a database instance

Serverless usage policies consist of tags that are applied to any serverless compute activity incurred by a user assigned to the policy. By tagging a database instance with a serverless usage policy, you can attribute billing and usage costs to particular policies, making it easier to track, manage, and control spend across serverless resources.

Use the UI to update the budget policy of a database instance:

Click Apps in the top right corner and select Lakebase Postgres.
Click Provisioned to open the Provisioned instances page.
Select the database instance you want to update the billing policy for.
Click Edit in the upper-right.
Select a Serverless usage policy.
Click Save.

Manage instance capacity

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

Each capacity unit allocates about 16 GB of RAM along with associated CPU and local SSD resources. Before scaling, test and optimize queries. Storage scales automatically.

UI

Click Apps in the top right corner and select Lakebase Postgres.
Click Provisioned to open the Provisioned instances page.
Select the database instance you want to resize.
Click Edit in the upper-right corner.
Use the Capacity drop-down menu to select the new instance size.
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

w = WorkspaceClient()
instance_name = "my-database-instance"
w.database.update_database_instance(
    name=instance_name,
    database_instance=DatabaseInstance(name=instance_name, capacity="CU_4"),
    update_mask="*"
)

CLI

databricks database update-database-instance my-database-instance '*' --capacity CU_4

Monitor a database instance

Access metrics from the Monitoring tab on the instance details page.

Click Apps in the top right corner and select Lakebase Postgres.
Click Provisioned to open the Provisioned instances page.
Select the database instance you want to monitor.
Select Monitoring from the Lakebase App sidebar.

Use the following metrics to analyze performance trends, identify potential bottlenecks, and evaluate whether to optimize application usage or scale your instance:

Transactions per second: Shows committed transaction throughput. Use this to understand workload patterns and identify peak transaction periods. If this value is consistently high, consider optimizing client behavior or increasing the size of the instance.
Rows per second: Displays the number of rows fetched, returned, inserted, updated, and deleted. Rows fetched refers to the number of rows returned to clients. Rows returned refers to the number of rows read by queries. Helps diagnose the type of workload and its impact on the system. If performance is constrained, consider adding indexes or optimizing query patterns.
Open connections: Displays the number of open active connections. Connections consume instance resources. Use this to evaluate whether client-side connection pooling is needed. Refer to limits for the maximum number of allowed connections.
Storage utilization: Indicates current storage usage for the instance. If utilization approaches Lakebase Provisioned limits, remove unnecessary data or indexes. Alternatively, contact support to request a quota increase.
CPU utilization (%): Measures CPU usage for the database instance. High CPU usage might indicate a computation-heavy workload. Consider application-side optimizations or increasing the size of the instance.
Page read throughput (%): Reflects how close the instance is to its page read capacity, typically caused by cache misses. If the value is high, reduce the workload or working set, add indexes, cache queries on the client side, or streamline the data.
Buffer cache hit rate (%): Indicates the percentage of reads served from memory. High-performance workloads should see values above 99%. Low rates suggest the workload exceeds cache capacity or could benefit from optimizations.
Local SSD cache hit rate (%): Tracks the percentage of reads served from the SSD cache after a buffer cache miss. A low value may increase page read throughput. Use similar optimizations as with buffer cache, or consider a larger instance.
Deadlocks per second: Measures how often transactions encounter deadlocks. These typically occur when multiple transactions access the same resources in conflicting order. Investigate and refactor workloads to prevent deadlocks.

Next steps

Serve lakehouse data with synced tables.
Connect and query your database instance.
Register database instance in Unity Catalog.
Allow other users access to the database instance from Azure Databricks. See Manage permissions and Postgres roles.

Limitations and requirements

The following sections describe limits and configuration requirements for managed database instances.

A workspace allows a maximum of ten instances.
Each instance supports up to 1000 concurrent connections.
The logical size limit across all databases in an instance is 2 TB.
Database instances are scoped to a single workspace.

Instance name requirements

Must be 1 to 63 characters long.
Must begin with a letter.
Can contain only alphanumeric characters and hyphens.
Cannot include two consecutive hyphens.

Maklum balas

Adakah halaman ini membantu?

Last updated on 2026-05-15

Create and manage a database instance

Create a database instance

UI

Python SDK

CLI

curl

Advanced settings

Stop or start an instance

UI

Python SDK

CLI

curl

Behavior when stopped

Behavior when started

Limitations

Delete an instance

UI

Python SDK

CLI

curl

Update a serverless usage policy of a database instance

Manage instance capacity

UI

curl

Python SDK

CLI

Monitor a database instance

Next steps

Limitations and requirements

Instance name requirements

Maklum balas

Sumber tambahan