Create and manage a database instance

Preview

This feature is in Public Preview in the following regions: us-east-1, us-west-2, eu-west-1, ap-southeast-1, ap-southeast-2, eu-central-1, us-east-2, ap-south-1.

To get started with OLTP workloads, create a Lakebase database instance using the 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

1. Click Compute in the workspace sidebar.
2. Click the Lakebase Postgres tab.
3. Click Create database instance.
4. Enter a database instance name (1-63 characters, letters and hyphens only).
5. Click Create.

Python SDK

Python

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

Bash

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

Bash

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 budget 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 Databricks UI, API call, Python SDK, or CLI.

UI

1. Click Compute in the workspace sidebar.
2. Click the Lakebase Postgres tab.
3. Click the database instance you want to stop or start.
4. Click Stop or Start in the upper-right corner of the page.

Python SDK

Python

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

Bash

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

Bash

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

Bash

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

1. Click Compute in the workspace sidebar.
2. Click the Lakebase Postgres tab.
3. Select the database instance you want to delete.
4. Click the Catalogs tab to view the full list of database catalogs associated with the database instance.
5. For each database catalog, delete all synced tables, including those that are located in managed catalogs and are not registered as database catalogs.
6. Click > Delete catalog.

Python SDK

Python

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

Bash

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

Bash

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

Update a serverless budget policy of a database instance

Serverless budget 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 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:

1. Click Compute in the workspace sidebar.
2. Click the Lakebase Postgres tab.
3. Select the database instance you want to update the billing policy for.
4. Click Edit in the upper-right.
5. Select a Serverless budget policy.
6. Click Save.

Next steps

• Allow other users access to the database instance from Databricks. See Manage roles and permissions and Manage Postgres roles.
• Connect and query your database instance from external tools, the SQL editor, or a notebook.
• Register database instance in Unity Catalog.
• Sync data from existing Unity Catalog tables.

Limitations and requirements

The following sections describe limits and configuration requirements for managed database instances. For constraints on instance creation and usage, see Limitations and considerations.

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.