VPU and permissions v1.4.1 (LTS)

Pipeline Designer uses a dedicated Postgres role called visual_pipeline_user (VPU) to execute all pipeline operations against the AI Database (AIDB) extension. Understanding how VPU works is important because it directly affects what pipelines are visible in the Pipeline Designer, what tables pipelines can access, and how permissions must be configured.

What is VPU?

visual_pipeline_user is a Postgres role that you create manually as a prerequisite before using Pipeline Designer. The role is not created automatically. See Getting started -Creating the VPU role for the setup steps. The role has basic connectivity once created, but it does not have the grants needed to read your data or create pipeline objects. You must configure those permissions yourself (see Configuring VPU permissions). Pipeline management operations (creating, updating, and deleting pipelines) run under this role - the agent opens a transaction and switches identity using SET LOCAL ROLE visual_pipeline_user. Pipeline execution also runs as VPU, though the mechanism varies by processing mode (see Executing pipelines - Execution flow for details).

VPU exists for two reasons:

1. Privilege isolation. Pipeline SQL doesn't run with superuser or administrator privileges. If a pipeline operation triggers unexpected behavior in the AIDB extension, the blast radius is limited to what VPU is authorized to access.

2. Pipeline Designer visibility control. Pipeline Designer displays only the pipelines and knowledge bases owned by VPU. This separation keeps pipelines managed through Pipeline Designer distinct from those created through other means (SQL, scripts, third-party tools). Pipeline Designer doesn't attempt to manage pipelines it didn't create, avoiding potential conflicts with incompatible configurations.

For environment setup steps (extension installation, cluster configuration, platform roles, and source table grants), see Getting started.

How VPU affects visibility

When a pipeline is created through Pipeline Designer, AIDB stamps the pipeline's owner_role as visual_pipeline_user. The EDB Postgres AI agent periodically collects pipeline and knowledge base data from AIDB and filters for owner_role = 'visual_pipeline_user'. Only matching objects are reported to the Hybrid Manager (HM) control plane and displayed in the Pipeline Designer.

This has a direct consequence: pipelines and knowledge bases created outside Pipeline Designer aren't visible in Pipeline Designer. If you create a pipeline through SQL (for example, using psql as the edb_admin role), it will function correctly at the database level but won't appear in Pipeline Designer's pipeline list or knowledge base views.

There is no AIDB function to change a pipeline's owner_role after creation. If you need a SQL-created pipeline to appear in the Portal, you must create it while assuming the VPU role. Your Postgres role must have been granted VPU (GRANT visual_pipeline_user TO your_role) to perform the role switch:

-- SET LOCAL ROLE scopes the identity change to the current transaction.
BEGIN;
SET LOCAL ROLE visual_pipeline_user;
SELECT aidb.create_pipeline(...);
COMMIT;

Configuring VPU permissions

VPU doesn't automatically have access to your data tables or the ability to create pipeline objects. The permissions VPU needs depend on the pipeline's processing mode, as described in the overview below. If any required permission is missing, pipeline creation or execution will fail with a permission error.

Required VPU permissions

1. Create destination tables. AIDB creates a destination table (named pipeline_<name>) in the same schema as the source table. VPU needs CREATE ON SCHEMA for that schema. This grant is required for every processing mode.

2. Read source data and create processing triggers. The grant VPU needs to read the source table depends on the processing mode:

   • On Demand mode reads the source table but doesn't attach triggers. VPU only needs SELECT on the source table:

     → WrapCopy

     GRANT SELECT ON <schema>.<source_table> TO visual_pipeline_user;

   • Live and Background modes attach triggers to the source table so that new or updated rows are processed automatically. For these modes, VPU must be granted membership in the source table's owner role:

     → WrapCopy

     GRANT <source_table_owner_role> TO visual_pipeline_user;

     This single grant gives VPU both the read access and the privileges needed to create and delete the processing triggers on the source table. Replace <source_table_owner_role> with the role that owns the source table.

     Membership in the owner role is required rather than a narrower TRIGGER grant because Postgres lets only a table's owner drop triggers on it. The TRIGGER privilege allows creating triggers but not deleting them, so VPU would be unable to clean up its triggers when a pipeline is updated or deleted.

The subsections below show the exact GRANT statements for each topology.

Tables in the public schema

On Postgres 15 and later, CREATE on the public schema is no longer granted to PUBLIC by default. VPU therefore needs an explicit CREATE ON SCHEMA public grant regardless of whether the cluster is managed or self-managed. The aidb_users role grants access to AIDB extension objects but doesn't cover SELECT on user-created tables, schema-level CREATE, or the privileges needed to create and delete processing triggers. See Manage user access with the aidb_users role for how the role works outside of Pipeline Designer.

Connect to the database as an administrator and run the grants for your processing mode.

For On Demand mode:

GRANT SELECT ON public.<source_table> TO visual_pipeline_user;
GRANT CREATE ON SCHEMA public TO visual_pipeline_user;

For Live and Background modes:

GRANT <source_table_owner_role> TO visual_pipeline_user;
GRANT CREATE ON SCHEMA public TO visual_pipeline_user;

Replace <source_table> with the actual table name and <source_table_owner_role> with the role that owns the source table.

Tables in user-created schemas

For tables in custom schemas, you must grant VPU access explicitly. Connect to the database as an administrator and run the grants for your processing mode.

For On Demand mode:

GRANT USAGE ON SCHEMA <schema> TO visual_pipeline_user;
GRANT SELECT ON <schema>.<source_table> TO visual_pipeline_user;
GRANT CREATE ON SCHEMA <schema> TO visual_pipeline_user;

For Live and Background modes:

GRANT USAGE ON SCHEMA <schema> TO visual_pipeline_user;
GRANT <source_table_owner_role> TO visual_pipeline_user;
GRANT CREATE ON SCHEMA <schema> TO visual_pipeline_user;

Replace <schema> and <source_table> with your actual schema and table names, and <source_table_owner_role> with the role that owns the source table. USAGE allows VPU to see objects in the schema. CREATE allows it to create destination tables there.

Tables on PGD clusters

Postgres Distributed (PGD) clusters require the same grants as any other topology, plus additional BDR (Bi-Directional Replication) considerations. All grants must be consistent across every BDR node, not just the write leader. A grant that exists on the write leader but is missing on a subscriber node will cause replication failures when the trigger fires on that node.

Apply the base grants on every BDR node (or use a replicated DDL mechanism).

For On Demand mode:

-- Run on each BDR node:
GRANT USAGE ON SCHEMA <schema> TO visual_pipeline_user;
GRANT SELECT ON <schema>.<source_table> TO visual_pipeline_user;
GRANT CREATE ON SCHEMA <schema> TO visual_pipeline_user;

For Live and Background modes on PGD clusters running AIDB 7.3.2 or later:

-- Run on each BDR node:
GRANT USAGE ON SCHEMA <schema> TO visual_pipeline_user;
GRANT <source_table_owner_role> TO visual_pipeline_user;
GRANT CREATE ON SCHEMA <schema> TO visual_pipeline_user;

For Live and Background modes on PGD clusters running AIDB earlier than 7.3.2, transfer ownership of the source table to VPU instead of granting the owner role:

-- Run on each BDR node:
GRANT USAGE ON SCHEMA <schema> TO visual_pipeline_user;
ALTER TABLE <schema>.<source_table> OWNER TO visual_pipeline_user;
GRANT CREATE ON SCHEMA <schema> TO visual_pipeline_user;

Replace <schema> and <source_table> with your actual schema and table names, and <source_table_owner_role> with the role that owns the source table. For tables in public, omit the USAGE grant.

Trigger handler ownership on PGD clusters

When you enable Live or Background processing, AIDB creates a per-pipeline SECURITY DEFINER wrapper function and sets its owner to the pipeline's owner_role (which is visual_pipeline_user for Portal-created pipelines). BDR enforces ownership constraints on trigger functions attached to replicated tables: it checks that the trigger function owner satisfies replication constraints for the relation on all nodes.

On AIDB 7.3.2 and later, granting VPU the source table's owner role (GRANT <source_table_owner_role> TO visual_pipeline_user) satisfies these constraints. On AIDB versions earlier than 7.3.2, granting ownership of the source table to VPU by having it inherit the owner role is not sufficient. It is necessary to explicitly make VPU owner of the source table:

ALTER TABLE <schema>.<source_table> OWNER TO visual_pipeline_user;

This is broader than the owner-role grant because it makes VPU the owner of the source table. Use it only as a PGD-specific workaround on AIDB versions earlier than 7.3.2. See Trigger function ownership on PGD clusters for more detail on the underlying constraint.

Security and isolation considerations

The preceding sections cover VPU setup and permissions grants. The topics below address the architectural implications of VPU's shared-identity model for security, credential isolation, and object ownership.

Shared identity

All pipelines created through Pipeline Designer run as the same Postgres role. There's no per-HM-user isolation at the database level. HM user A's pipeline and HM user B's pipeline both execute as visual_pipeline_user and have access to the same set of tables. Isolation between users' pipelines is managed at the HM project level (through Pipeline Designer access controls), not at the Postgres level.

This also means there is no per-user audit trail at the Postgres level. All pipeline activity in the database logs appears as operations by visual_pipeline_user.

Shared model credentials

Model credentials (API keys for external inference services) are stored as FDW user mappings and are shared across all database users. Any pipeline on the same database, regardless of which HM user created it, can use any registered model. There is no per-pipeline or per-user credential isolation.

Objects created by VPU

When Pipeline Designer creates a pipeline, VPU becomes the owner of several database objects:

• The pipeline's destination table (for example, pipeline_my_pipeline).

• The knowledge base vector table (if the pipeline includes a KnowledgeBase step).

• Per-pipeline SECURITY DEFINER wrapper functions (for Live and Background processing modes). These wrappers call the actual AIDB trigger handler and are owned by VPU so that they execute with VPU's privileges regardless of the invoking role.

• Pipeline state tracking tables used internally by AIDB.

These objects persist until the pipeline is deleted through Pipeline Designer.

Common VPU issues

"Permission denied for table" during pipeline creation

Cause: VPU is missing one or more of the required permissions for the source table or its schema. For On Demand mode, this is SELECT or CREATE ON SCHEMA. For Live and Background modes, it is membership in the source table's owner role (GRANT <source_table_owner_role> TO visual_pipeline_user) or CREATE ON SCHEMA.

Fix: Grant the required permissions as described in Configuring VPU permissions.

Pipeline created via SQL does not appear in Pipeline Designer

Cause: The pipeline was created under a role other than visual_pipeline_user, so its owner_role doesn't match the Pipeline Designer's filter.

Fix: Recreate the pipeline using SET LOCAL ROLE visual_pipeline_user before calling aidb.create_pipeline(). See How VPU affects visibility for the full procedure.

Pipeline works but knowledge base is not visible

Cause: Same as above. The knowledge base inherits the owner_role from the pipeline. If the pipeline wasn't created under VPU, neither the pipeline nor the KB will appear in Pipeline Designer.

Trigger creation fails on PGD clusters

Cause: When AIDB enables Live or Background processing, it creates a per-pipeline SECURITY DEFINER wrapper function owned by VPU. BDR requires that the trigger function owner satisfies replication constraints on the source table. If VPU lacks the necessary grants on any BDR node, trigger creation fails.

Fix: Apply consistent GRANT statements on all PGD nodes as described in Tables on PGD clusters. On AIDB versions earlier than 7.3.2, the owner-role grant isn't sufficient; see the Trigger handler ownership on PGD clusters fallback for transferring source table ownership to VPU.