Skip to main content

Register a Lakebase database in Unity Catalog

Beta

Lakebase Postgres (Autoscaling Beta) is the next version of Lakebase, available for evaluation only. For production workloads, use Lakebase Public Preview. See choosing between versions to understand which version is right for you.

Registering a Lakebase database in Unity Catalog creates a read-only catalog that represents your Postgres database, enabling unified data governance and cross-source analytics across your lakehouse and transactional workloads.

Why register in Unity Catalog​

Registration provides several benefits:

Unified governance: Apply Unity Catalog's governance controls—permissions, lineage tracking, and audit logs—to your Lakebase data alongside your lakehouse data.

Cross-source queries: Query both Unity Catalog tables and Lakebase databases from a single SQL interface, enabling analytics that combine transactional and analytical data.

Centralized discovery: Browse and discover Lakebase databases, schemas, and tables through Catalog Explorer alongside other data sources in your workspace.

Integrated workflows: Use Lakebase data in Databricks dashboards and applications without switching contexts or managing separate connections.

How it works​

Registration creates a read-only Unity Catalog catalog that mirrors your Postgres database structure, providing metadata access to your database objects (schemas, tables, views) through Unity Catalog's governance layer.

You initiate registration from Catalog Explorer rather than from the Lakebase interface, which integrates naturally with Unity Catalog's catalog creation workflow.

After registration:

  • Your Lakebase database appears as a catalog in Unity Catalog
  • Unity Catalog permissions control who can view and query the database
  • The catalog remains read-only—you manage the actual database through Lakebase

Prerequisites​

  • An existing Lakebase database project with at least one database
  • CREATE CATALOG privileges on the Unity Catalog metastore
  • A serverless SQL warehouse to query the registered catalog

Register a database​

To register a Lakebase database in Unity Catalog:

  1. In Catalog Explorer, click Create catalog.
  2. Select Lakebase Serverless as the catalog type.
  3. Enter a catalog name and select your database project, branch, and Postgres database.
  4. Click Create.

Register LKB database in Unity Catalog

The catalog appears in Catalog Explorer, where you can browse schemas, tables, and views, and query them using SQL warehouses.

Explore registered databases​

After registration, navigate to your catalog in Catalog Explorer to browse schemas, tables, and views. Click any table to view schema details, sample data, and lineage information.

Unity Catalog automatically syncs metadata from your Lakebase database. When you add or modify tables in Lakebase, refresh the catalog view to see updates.

Query registered databases​

Query registered Lakebase databases using SQL warehouses or any tool that connects to Unity Catalog:

SQL
-- Query a registered :re[LKB] database
SELECT * FROM chatbot_catalog.public.conversations
WHERE created_at >= current_date - INTERVAL 7 DAYS;

-- Join :re[LKB] and lakehouse data
SELECT
  c.conversation_id,
  c.user_id,
  c.agent_response,
  u.user_name,
  u.subscription_tier
FROM chatbot_catalog.public.conversations c
JOIN main.user_analytics.users u
  ON c.user_id = u.user_id;

The read-only catalog ensures queries don't modify your Lakebase database through Unity Catalog. To modify data, use the Lakebase SQL Editor or connect directly to your database.

Permissions and access control​

Unity Catalog permissions control access to registered Lakebase databases:

  • Catalog ownership: The user who registers the database becomes the catalog owner
  • Read access: Grant USE CATALOG and SELECT privileges to allow others to query the database
  • Metastore admin: Metastore admins can manage all registered catalogs

To grant access to a registered database:

SQL
-- Grant read access to a group
GRANT USE CATALOG ON CATALOG chatbot_catalog TO `ai-engineering`;
GRANT SELECT ON CATALOG chatbot_catalog TO `ai-engineering`;

Permissions set in Unity Catalog control query access through SQL warehouses. Direct connections to your Lakebase database use Postgres roles and permissions independently.

Unregister a database​

To unregister a Lakebase database from Unity Catalog, select the catalog in Catalog Explorer, click the Dots circle icon., and select Delete.

Deleting the catalog removes it from Unity Catalog but doesn't affect your Lakebase database. The database remains accessible through Lakebase and direct Postgres connections.

note

If you created synced tables from the registered database, delete those tables first. Each source table can only be used to create 20 synced tables, and synced tables pending deletion count toward this limit.

Limitations​

Read-only access: Catalogs registered from Lakebase databases are read-only. You can't modify data through Unity Catalog queries.

Single database per catalog: Each Unity Catalog catalog represents one Lakebase database. To expose multiple databases, register each one separately.

Metadata sync: Unity Catalog caches metadata to reduce Postgres requests. New objects may not appear immediately. Click Refresh Schema Icon to trigger a full refresh.

Branch isolation: Catalogs register databases from specific branches. To access data from multiple branches, register a database from each branch as a separate catalog.

Next steps​

Last updated on