Skip to main content

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 use Lakebase, you must first create a database instance. This page explains how to create and manage a database instance.

Enable PostgreSQL OLTP database Preview​

  1. As a workspace or account admin, click your username in the top bar of the Databricks workspace.
  2. From the menu, select Previews.
  3. Turn on Lakebase: Managed PostgreSQL OLTP Database.

For more on managing previews, see Manage Databricks Previews.

Create a database instance​

To create a database instance, use the Databricks UI or an API call.

  1. Click Compute in the workspace sidebar.
  2. Click the Database instances tab.
  3. Click Create database instance.
  4. Enter a database instance name.
  5. (Optional) Use the drop-down menu to choose an Instance Size. For details about choosing a capacity, see Manage instance capacity.
  6. (Optional) Click Advanced Settings for additional configurations.
    1. Under Restore window, set the retention window, which determines the time period from which you can create a child instance for point-in-time recovery. The retention window can be between two and 35 days, with seven days as the default. For more details, see Create a child instance.
    2. If you want to create a copy-on-write clone of the original database instance, turn on Create from parent. For more details about the additional parameters, see Create a child instance.
    3. If you want high availability nodes to serve read-only workloads using a separate DNS endpoint, turn on Allow readable secondaries. For more details, see Enable database instance for high availability.
      1. Set the number of additional nodes for high availability. These are known as secondary nodes and perform failover if the primary node fails. For guidance on what number to set, see Configure a database instance for high availability and enable readable secondary instances.
  7. Click Create.

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 or an API call.

  1. Click Compute in the workspace sidebar.
  2. Click the Database instances 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.

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.

  1. Click Compute in the workspace sidebar.
  2. Click the Database instances 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 Kebab menu icon. > Delete catalog.

Next steps​

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.
Last updated on