For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Skip to content

PostgreSQL

Minimum PostgreSQL grants for a Vulcan deployment: source, target, and state schema privileges, by secret_name tier.

This page covers the minimum PostgreSQL permissions needed to run Vulcan. Platform and database administrators use it to grant a Vulcan service account exactly the privileges Vulcan needs, and nothing more.

Vulcan cannot create PostgreSQL databases. All databases must already exist before you grant access; Vulcan only needs permission to connect to existing databases and, when required, create schemas and objects inside them.

PostgreSQL is a single-catalog engine, so cross-database queries are not supported. All source schemas and the Vulcan target schema must reside in the same database. If your sources span multiple databases, use a foreign data wrapper or a different engine.

What Vulcan does

The privileges Vulcan needs, broken down by schema and scope.

Source schemas (read-only)

Privilege
Purpose

SELECT

Reads tables and views referenced by models.

Catalog reads (pg_tables, pg_views, pg_matviews, pg_catalog)

Object introspection. Accessible to all users by default; no special grant is needed.

Model target schema (write)

Privilege
Purpose

CREATE TABLE, DROP TABLE + CREATE TABLE

Full model refresh. Postgres does not support CREATE OR REPLACE TABLE.

DROP VIEW + CREATE VIEW

Semantic layer views and virtual layer promotion.

ALTER TABLE

Column adds and drops when the model schema changes between deployments.

INSERT, MERGE (Postgres 15+; logical merge via INSERT/UPDATE/DELETE on older versions), TRUNCATE, DELETE

Incremental model evaluation.

COMMENT ON TABLE / VIEW / COLUMN

Applied automatically. Requires ownership, which Vulcan has on objects it creates.

State schema (write)

The state schema requires the same grants as the target schema. Vulcan stores internal metadata here, including _snapshots, _environments, and _intervals. By default, this is the same schema as the model target. If state_schema in the gateway config points elsewhere, apply the same write grants to that schema too.

Session-level

Vulcan runs SHOW server_version to check the Postgres version and decide whether to use native MERGE or a logical merge fallback. This requires no special privilege.

Not required here

Item
Reason

CREATE TABLE ... CLONE

Not supported by Postgres. This is a Snowflake-only concept.

Multiple database grants

Postgres is single-catalog; all schemas exist in one database.

Role and user setup

Run this once before applying any grants:

To use a separate login user and a group role instead:

secret_name: postgres-semantic-readonly

Use this tier when Vulcan only exposes PostgreSQL tables or views through the semantic layer. No models run, and no objects are created or written. This is a pure read-only connection.

Database

Schema

Tables and views

Grant SELECT only on the specific objects exposed to the semantic layer:

Or grant across the full schema if all objects are approved:

To cover tables and views created in the future:

What works: Semantic queries over external models. What is blocked: Vulcan cannot create, alter, truncate, delete, or drop any PostgreSQL object.

secret_name: postgres-single-db-full

Use this tier when the source schema and the Vulcan target schema are both inside one PostgreSQL database. It covers every Vulcan model kind (FULL, INCREMENTAL_BY_TIME_RANGE, SCD_TYPE_2, SEED, VIEW), plus semantic layer exposure.

Database

Source schema (read-only)

To cover tables and views added to the source schema in the future:

If models read from more than one schema within the same database, apply the same schema-level grants to each additional source schema.

Repeat the source schema grants above for every additional schema a model reads from.

Vulcan target schema (read/write)

Create the schema if it does not exist, then grant write access:

CREATE on the schema lets Vulcan create tables and views. Because Vulcan's role creates these objects, it automatically owns them and has full access. No additional table-level grants are needed for objects Vulcan creates itself.

If the Vulcan schema already contains objects created by a different role, grant explicit access on those existing objects:

Optional: schema ownership

Ownership lets Vulcan fully manage the schema lifecycle (ALTER, DROP, REPLACE, cleanup) without per-object privilege issues when another role created the objects.

If existing tables or views in the schema were created by a different role, transfer ownership on those objects:

What works: All Vulcan model kinds, semantic layer, and state sync, within a single PostgreSQL database.

Notes

PostgreSQL does not have FUTURE grants. Use ALTER DEFAULT PRIVILEGES to cover objects created after the grants are applied. GRANT ... ON ALL TABLES commands cover only objects that exist at the time the grant runs.

COMMENT ON TABLE and COMMENT ON COLUMN require that the role own the object. Vulcan automatically owns objects it creates in the target schema. For source schema objects, Vulcan does not add comments.

DROP VIEW in Postgres automatically cascades, so dependent objects are also dropped. This is intentional: Vulcan recreates the view immediately after dropping it.

Postgres 15+ supports native MERGE. On older versions, Vulcan falls back to a logical merge using separate INSERT, UPDATE, and DELETE statements within a transaction. The required privileges are the same either way.

Resource
Relationship

Equivalent permission tiers for a Snowflake-backed Vulcan deployment.

Equivalent permission tiers for a Databricks-backed Vulcan deployment.

Equivalent permission tiers for a Dedicated Trino-backed Vulcan deployment.

Equivalent permission tiers for an External Trino-backed Vulcan deployment.

Last updated

Was this helpful?