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.

This page explains how to register your Lakebase database as a 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 or an API call.

UI

1. Click Compute in the workspace sidebar.
2. On the Database instances tab, select your database instance.
3. On the Catalogs tab, click Create catalog.
4. You can register an existing database as a Unity Catalog catalog or create a new one. Use one of the following options:
   • To use an existing database: enter the desired Unity Catalog catalog name and the name of the existing Postgres database. The default database databricks_postgres can be used as the database name.
   • To create a new Postgres database and Unity Catalog catalog at the same time: enter the desired catalog name and turn on Create new database.
5. Click Create.
6. After creation, click on the catalog in the Catalogs list to see the Catalog Explorer view.

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.

• 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 to delete a database catalog.

1. Click Catalog in the workspace sidebar.
2. Select the database catalog you want to delete from the Catalog pane.
3. Click and click Delete.

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