VPU and permissions Innovation Release

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. Every pipeline requires three permissions on the database, described in the overview below. If any of these are missing, pipeline creation or execution will fail with a permission error.

Required VPU permissions

1. Read source data. VPU must have SELECT on the source table so it can read the rows that the pipeline processes.

2. 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.

3. Install processing triggers. Live and Background processing modes attach triggers to the source table so that new or updated rows are processed automatically. VPU needs TRIGGER on the source table for these modes. (On Demand mode doesn't use triggers and doesn't require this grant.)

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 table-level TRIGGER.

Connect to the database as an administrator and run:

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

Replace <source_table> with the actual table name. The TRIGGER grant is only required for Live and Background processing modes. If you use On Demand mode exclusively, you can omit it.

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:

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;
GRANT TRIGGER ON <schema>.<source_table> TO visual_pipeline_user;

Replace <schema> and <source_table> with your actual schema and table names. USAGE allows VPU to see objects in the schema. CREATE allows it to create destination tables there. As with the public schema, the TRIGGER grant is only required for Live and Background processing modes.

Tables on PGD clusters

Postgres Distributed (PGD) clusters require the same three 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):

-- 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;
GRANT TRIGGER ON <schema>.<source_table> TO visual_pipeline_user;

Replace <schema> and <source_table> with your actual schema and table names. 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.

The narrow GRANT TRIGGER shown above is the intended approach. If BDR still rejects the trigger because VPU can't satisfy replication constraints, you can fall back to transferring ownership of the source table to VPU:

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

This is broader than intended because it makes VPU the owner of the source table, not just a role with trigger privileges on it. Use it only as a PGD-specific workaround when the narrow TRIGGER grant is insufficient. 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 (SELECT, CREATE ON SCHEMA, or TRIGGER) for the source table or its 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. If the narrow TRIGGER grant is insufficient due to BDR replication constraints, see the Trigger handler ownership on PGD clusters fallback.