PostgreSQL Catalog

Explanation (Core Concepts)

What is a PostgreSQL Catalog?

A PostgreSQL catalog registers a PostgreSQL database as a governed, relational catalog inside an xStore. Once registered, xDP can browse the database's schemas, tables, and columns, apply governance policies, and let linked xCompute engines query it — all from the central Data Catalog.

Under the hood, the catalog is created in the xStore's Apache Gravitino metastore using the jdbc-postgresql provider. It connects over JDBC using the PostgreSQL driver (org.postgresql.Driver), so you supply the connection URL and a username/password.

This guide is written for the Platform Administrator who onboards and operates data-source catalogs. It assumes a running xStore (here, <xstore-name>) with at least one metalake (<metalake-name>).

The steps and screenshots in this guide use placeholders, not real object names — substitute your own values wherever you see one:

Placeholder	Stands for
`<xstore-name>`	Your xStore cluster
`<metalake-name>`	The metalake the catalog is created in
`<host>` / `<port>`	Your PostgreSQL server address and port
`<database>`	The PostgreSQL database to catalog
`<schema_1>` …	Schemas discovered inside that database
`<table_1>` …	Tables discovered inside a schema
`<user>`	The PostgreSQL account the catalog connects as

Info
Important: A PostgreSQL catalog is a relational catalog and lives inside a metalake on an xStore. Create the xStore and metalake first; this guide adds a catalog to an existing metalake.

Info
Security note: All screenshots in this guide mask the connection secrets — the JDBC hostname is shown as host, and the username and password are masked. Use your real database host, username, and password when you follow these steps.

Key Concepts

Info
New to xStore catalogs? See xStore Catalog Relational — Core Concepts for the shared model — metalakes, catalog types, the provider list, identity/run-as, the create-catalog wizard, browsing, and what you can do with a catalog.

Concepts specific to PostgreSQL:

Backend (JDBC): PostgreSQL connects via a JDBC URL using the org.postgresql.Driver (pre-filled) and a username/password.

Tutorial (Getting Started)

This tutorial onboards a PostgreSQL catalog named postgres_catalog into the <metalake-name> metalake on <xstore-name>, then browses its schemas and tables.

Prerequisites

A running xStore cluster with status RUNNING.
At least one metalake in that xStore (this tutorial uses <metalake-name>).
A reachable PostgreSQL database, plus its database name.
PostgreSQL credentials (username and password) with read access to the schemas you want to catalog.
Administrative permissions on the xDP platform.

Minimum PostgreSQL permissions

Grant these to the database user/role used by the catalog (and, because Spark/Trino/Jupyter queries run as the per-user identity, to the role the querying users map to). These are datasource-side grants; xCentral/Ranger policies apply on top.

Read-only (onboard + browse + query): GRANT CONNECT ON DATABASE <db>, GRANT USAGE ON SCHEMA <schema>, and GRANT SELECT ON ALL TABLES IN SCHEMA <schema>. (Gravitino browses via JDBC metadata + information_schema/pg_catalog, so the user must be able to see these objects — the default.)
Read-write (write from engines): the above plus GRANT CREATE ON SCHEMA <schema> and GRANT INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA <schema> (and ALTER/DROP on tables managed from xDP).

Run this on PostgreSQL before onboarding (replace the <...> placeholders). Reference: PostgreSQL — GRANT.

-- Run as a superuser or the database owner CREATE ROLE xdp_catalog LOGIN PASSWORD '<password>'; -- Read-only GRANT CONNECT ON DATABASE "<db>" TO xdp_catalog; GRANT USAGE ON SCHEMA "<schema>" TO xdp_catalog; GRANT SELECT ON ALL TABLES IN SCHEMA "<schema>" TO xdp_catalog; ALTER DEFAULT PRIVILEGES IN SCHEMA "<schema>" GRANT SELECT ON TABLES TO xdp_catalog; -- Read-write (add) GRANT CREATE ON SCHEMA "<schema>" TO xdp_catalog; GRANT INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA "<schema>" TO xdp_catalog; ALTER DEFAULT PRIVILEGES IN SCHEMA "<schema>" GRANT INSERT, UPDATE, DELETE ON TABLES TO xdp_catalog;

Step 1 — Open the Data Catalog and choose the metalake

Open Data catalog from the left sidebar and select your xStore (<xstore-name>) from the Select xStore dropdown.
Click <metalake-name> to open it, then click Add Catalog. The 6-step Create Catalog wizard opens (Catalog Type → Provider → Basic Information → Identity → Backend → Review).

Step 2 — Catalog Type

Choose what kind of data this catalog manages. PostgreSQL is a database, so select Relational and click Next.

Step 3 — Provider

Pick PostgreSQL from the list of relational providers, then click Next.

Step 4 — Basic Information

Give the catalog a name and (optionally) a comment. The Metalake is fixed to the one you opened.

Catalog Name: postgres_catalog
Comment: PostgreSQL relational catalog (demo)

Click Next.

Step 5 — Identity

Choose which identity owns the credentials this catalog uses for authentication. The default System User (which runs as xstore-system-user) is used here. Click Next.

Step 6 — Backend (connection + authentication)

Enter the PostgreSQL connection settings:

JDBC URL: jdbc:postgresql://<host>:5432/<database> (the screenshot masks the host as host; use your real database host).
JDBC Driver: org.postgresql.Driver (pre-filled).

Under Backend Authentication, supply the database Username and Password (both masked in the screenshot below). Optionally add custom key-value pairs under Additional Properties, then click Next.

Step 7 — Review & Create

Review the summary and the derived Backend properties. Note that xDP sets jdbc-driver = org.postgresql.Driver, and the jdbc-password is masked. Click Create Catalog.

Step 8 — View the catalog and its schemas

The catalog is created and appears in the metalake as a jdbc-postgresql / relational catalog with status In use. Open postgres_catalog to see its detail: metadata (Provider jdbc-postgresql, Type relational, Auth type PASSWORD, Run-as xstore-system-user), the connection Properties (jdbc-url, jdbc-driver, jdbc-database), and the Schemas discovered in the database — here <schema_1>, public, and test.

In the Backend step, scroll to Additional Properties.
Enter a Property Key and Value and add it. These are merged into the catalog's Gravitino properties alongside the standard jdbc-* keys (for example, to enable SSL).

Edit or delete a PostgreSQL catalog

Open the catalog detail view.
Use Edit catalog (pencil) to change connection settings (URL, credentials, properties), or More actions (⋮) to delete it.
For schema-level changes, use New schema from the catalog view.

Let an xCompute engine query the catalog

Open the catalog and select the Linked compute tab.
Link an xCompute cluster so its engines (Spark, Trino) can query the PostgreSQL catalog's tables.

Reference

Create Catalog wizard steps

Step	Name	What it configures
1	Catalog Type	Relational (PostgreSQL) or Fileset.
2	Provider	The relational engine — select PostgreSQL.
3	Basic Information	Catalog name and optional comment (metalake is fixed).
4	Identity	Which identity owns the credentials (default: System User → `xstore-system-user`).
5	Backend	JDBC URL, driver, username/password, and custom properties.
6	Review	Confirm the summary and derived properties, then create.

Backend fields

Field	Required	Description
JDBC URL	Yes	PostgreSQL JDBC URL, e.g. `jdbc:postgresql://<host>:5432/<database>`.
JDBC Driver	Auto	`org.postgresql.Driver` (pre-filled).
Username	Yes	PostgreSQL username.
Password	Yes	PostgreSQL password.
Additional Properties	No	Custom key-value pairs merged into catalog properties (e.g. SSL options).

Derived backend properties

xDP generates these Gravitino properties for a PostgreSQL catalog:

Property	Value (example)
`jdbc-url`	`jdbc:postgresql://<host>:5432/<database>`
`jdbc-driver`	`org.postgresql.Driver`
`jdbc-database`	the target database
`jdbc-user`	the PostgreSQL username (stored as a secret)
`jdbc-password`	the PostgreSQL password (stored as a secret; masked in the UI)

Best Practices

Info
Tip: Use a dedicated, least-privilege PostgreSQL user scoped to the database and schemas you intend to expose.

Use a read-only role. Grant the connecting user only the access needed to read the schemas you want to catalog.
Enable SSL where required. Add SSL parameters to the JDBC URL or as Additional Properties when connecting over untrusted networks.
Name catalogs by source. A clear catalog name (e.g. postgres_catalog) makes governance and cross-engine queries easier to reason about.
Protect credentials. Never share the database host, username, or password; xDP stores credentials as secrets and masks them in the UI.

What's Next

Apply governance policies to the catalog from the linked xCentral.
Link an xCompute cluster so Spark or Trino can query the PostgreSQL tables.
Onboard more catalogs (Snowflake, Hive, Iceberg, Unity Catalog) into the same metalake to unify discovery and governance.

Last updated on

Was this page helpful?