Registering a Lakebase database in Unity Catalog

What it is

A Lakebase database can be registered as a catalog in Unity Catalog. The catalog mirrors one Postgres database: its schemas become Unity Catalog schemas and its tables become tables you can find in Catalog Explorer, grant on, trace in lineage and query with SQL — including in the same query as Delta tables.

The catalog is read-only. Writes still go to Postgres, through a Postgres connection.

Why it exists

An application database is usually a blind spot for the data team: its tables do not show up in the catalog, nobody can say who reads them, and a question that needs both an operational table and a lakehouse table becomes an export. Registering the database puts its tables where every other table already is, under the same permissions, audit and lineage, without copying a row.

How it works

Registering

In Catalog Explorer, create a catalog of type Lakebase Postgres, then choose the project, branch and database. You need CREATE CATALOG on the metastore. The same can be done with w.postgres.create_catalog in the SDK, or declared as a postgres_catalogs resource in a bundle (see Declarative Automation Bundles and the Databricks CLI).

Each catalog maps to exactly one database. A database on a child branch cannot be registered on its own; register databases on the branch that holds the long-lived data.

Querying

Queries against the catalog run on a serverless SQL warehouse. Pro and Classic warehouses return PERMISSION_DENIED (see SQL warehouse types and channels).

SELECT c.segment, COUNT(*) AS open_tickets
FROM shop_pg.support.tickets AS t          -- Lakebase, through the registered catalog
JOIN main.gold.customer_ltv AS c           -- Delta
  ON t.customer_id = c.customer_id
WHERE t.status = 'open'
GROUP BY c.segment;

The catalog caches the database’s metadata. A table created in Postgres a minute ago may not appear until the catalog is refreshed.

Two sets of permissions, again

To let someone query the catalog, grant it in Unity Catalog:

GRANT USE CATALOG ON CATALOG shop_pg TO `analysts`;
GRANT USE SCHEMA, SELECT ON SCHEMA shop_pg.support TO `analysts`;

These grants apply to warehouse queries only. Someone connecting to Postgres directly is governed by Postgres roles and grants, and nothing granted in Unity Catalog reaches them (see Connecting to Lakebase, roles and permissions). The two are configured separately and should say the same thing about who may read what.

Removing the catalog registration leaves the database and its data untouched.

How it differs from federation

Lakehouse Federation reaches an external PostgreSQL server — or MySQL, SQL Server and others — through a connection with stored credentials, and pushes queries down to it. A registered Lakebase catalog points at the platform’s own database: you pick the project, branch and database, instead of creating a connection with credentials for a server somewhere else. If the Postgres is Lakebase, register it; if it is somewhere else, federate it.

For analytics over live operational data, Databricks also has Lakehouse//RT, in Beta: a separate feature from the registered catalog.

Example

A support dashboard joins open tickets, written by the support application into Lakebase, with the customer value computed in the lakehouse. Register the application database once as shop_pg, grant the analysts SELECT on its support schema, and point the dashboard at a serverless warehouse. The tickets are never exported, and the dashboard shows tickets as the application sees them.

Common mistakes

• Expecting to write through the catalog. It is read-only. INSERT goes to Postgres.
• A Pro or Classic warehouse. Only serverless can query it.
• Registering a branch’s database. Child-branch databases cannot be registered on their own.
• Thinking the Unity Catalog grant covers the application. It covers warehouse queries; Postgres grants cover direct connections.
• A table that “does not exist”. The metadata is cached; refresh the catalog after creating tables.