Register your database in Unity Catalog

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.

Lakebase Provisioned uses provisioned compute that you manually scale. For feature comparison with the new Lakebase Autoscaling, see choosing between versions.

This page explains how to register your Lakebase database as a read-only Unity Catalog catalog. This allows you to use Unity Catalog privileges to manage data access and leverage integrations like managed data syncing.

Ownership and permissions

• If the database does not exist, it can be created along with the catalog. In this case, ownership of the objects will follow these guidelines.
• The catalog creator must additionally have CREATE CATALOG privileges on the Unity Catalog metastore.

Create a catalog

To register a database with Unity Catalog, use the Databricks UI, API call, Python SDK, or CLI.

UI

1. Click Apps in the top right corner and select Lakebase Postgres.
2. Click Provisioned to open the Provisioned instances page.
3. Select your database instance.
4. Select the Catalogs page in the Lakebase App sidebar.
5. Click Add catalog in the upper-right.
6. In the Add catalog dialog:
   • Catalog name: Enter the desired Unity Catalog catalog name.
   • Postgres database: Select an existing Postgres database from the drop-down menu (for example, databricks_postgres), or enter a new database name to create it along with the catalog.
7. Click Create.
8. After creation, click on the catalog in the Catalogs list to see the Catalog Explorer view.

Python SDK

Python

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

# Initialize the Workspace client
w = WorkspaceClient()

# Register an existing database as a UC catalog
catalog = w.database.create_database_catalog(
    DatabaseCatalog(
        name="my_catalog",                    # Name of the UC catalog to create
        database_instance_name="my-instance", # Name of the database instance
        database_name="databricks_postgres",  # Name of the existing Postgres database
    )
)
print(f"Created database catalog: {catalog.name}")

# Create a new database and register it as a UC catalog
catalog = w.database.create_database_catalog(
    DatabaseCatalog(
        name="new_catalog",                   # Name of the UC catalog to create
        database_instance_name="my-instance", # Name of the database instance
        database_name="new_database",         # Name of the Postgres database to register (and optionally create)
        create_database_if_not_exists=True    # Create the database if it doesn't exist
    )
)
print(f"Created new database and catalog: {catalog.name}")

CLI

Bash

# Register an existing database as a UC catalog
databricks database create-database-catalog my_catalog my-instance databricks_postgres

# Create a new database and register it as a UC catalog
databricks database create-database-catalog new_catalog my-instance new_database \
  --create-database-if-not-exists

curl

Bash

export PG_DATABASE_NAME="<name of the PG database to sync to UC>"
export CATLAOG_NAME="<name of UC catalog to create>"

Bash

// Optional
export CREATE_DATABASE_IF_NOT_EXISTS="<whether to create a new database>"

Bash

curl -X POST --header "Authorization: Bearer ${DATABRICKS_TOKEN}" https://$WORKSPACE/api/2.0/database/catalogs \
--data-binary @- << EOF
{
  "name": "$CATALOG_NAME",
  "database_name": "$PG_DATABASE_NAME",
  "instance_name": "$INSTANCE_NAME",
  "create_database_if_not_exists": "$CREATE_DATABASE_IF_NOT_EXISTS" // optional
}

Limitations

• Database names must only contain alphanumerical or underscore characters. Note database names cannot include hyphens.
• The catalog created in Unity Catalog based on the database is read-only.
• Database instances are scoped to a single workspace and don't support cross-workspace access. Users are able to see these tables in Catalog Explorer if they have the required Unity Catalog permissions from other workspaces attached to the same metastore, but they cannot access the table contents.

• Catalog names must follow the existing constraints for Unity Catalog securable object names.

Explore Postgres objects in Unity Catalog via a Database Catalog

To view the catalog, ensure you have a running serverless SQL warehouse attached.

1. Click Catalog in the workspace sidebar.
2. From the Catalog browser, click the cluster and select a running serverless SQL warehouse as your compute resource.
3. Click Start and close.

As you open the catalog, schemas, and tables, syncs should be triggered automatically. However, the UI may cache data to reduce the number of Postgres requests, so new objects may not show up immediately.

To trigger a full refresh, click .

Delete a database catalog in Unity Catalog

You must be the owner of a database catalog or a metastore admin to delete it.

Databricks recommends that you first delete all synced tables from the database catalog. Each source table can only be used to create 20 synced tables, and it can take up to three days for synced tables to be cleaned up in Unity Catalog after a database catalog is deleted. Synced tables pending deletion in Unity Catalog count toward the 20 synced tables per source table limit.

Use the Databricks UI, Python SDK, CLI, or API to delete a database catalog.

UI

1. Click Apps in the top right corner and select Lakebase Postgres.
2. Click Provisioned to open the Provisioned instances page.
3. Select your database instance.
4. Select the Catalogs page in the Lakebase App sidebar.
5. For the catalog you want to delete, click on the right side of the row.
6. Click Delete.

Python SDK

Python

from databricks.sdk import WorkspaceClient

# Initialize the Workspace client
w = WorkspaceClient()

# Delete a database catalog
catalog_name = "my_catalog"
w.database.delete_database_catalog(name=catalog_name)
print(f"Deleted database catalog: {catalog_name}")

CLI

Bash

# Delete a database catalog
databricks database delete-database-catalog my_catalog

curl

Bash

curl -X DELETE --header "Authorization: Bearer ${DATABRICKS_TOKEN}" https://$WORKSPACE/api/2.0/database/catalogs/$CATALOG_NAME

After the catalog is deleted, you can rename or drop the Postgres database.