# Known Issues

This page lists known user-visible limitations in pgGraph 1.0. See
[Release Notes](./release-notes) for resolved issues and
[Roadmap](./roadmap) for planned expansion.

## Operations

### External scheduling is required outside the packaged Docker setup

pgGraph exposes bounded, concurrency-safe maintenance entry points, but it does
not run an always-on scheduler inside every PostgreSQL installation. The
packaged Docker image configures `pg_cron`. Other installations must schedule
`graph.run_scheduled_maintenance()` with `pg_cron` or an external scheduler.

Without a scheduler, reads remain available, but pending trigger-sync work,
overlay compaction, and cleanup do not run automatically. Follow the setup,
health, retry, and failure guidance in
[Sync And Maintenance](/user_guide/sync-and-maintenance#scheduled-maintenance).

## Access Control

### Topology reads are builder-scoped, not row-level-security-filtered

`graph.traverse()`, `graph.shortest_path()`, `graph.weighted_shortest_path()`,
and the connected-component functions read the built graph artifact rather
than issuing a fresh SQL scan per call. They check table-level `SELECT`
privilege before returning results, but they do not evaluate row-level
security policies against the calling role, so a role with table-level
`SELECT` can receive coordinates, path membership, and reachability for rows
its own row-level security policy would hide from a direct `SELECT`.
`graph.search()` re-queries source-table properties as the caller and is not
affected.

`graph.build()` fails closed on this by default: registering a table with row
security enabled requires the explicit acknowledgment
`graph.allow_rls_tables = on` (SQLSTATE `55000`, diagnostic `PG021`, otherwise).
This turns the boundary above into a deliberate operator decision rather than
a silent one; it does not add row-level filtering to topology reads. See
[Row-Level Security And Topology Reads](/user_guide/administration-and-security#row-level-security-and-topology-reads)
for the full boundary and mitigation guidance.

### Tenant scope requires the session-setting path under enforcement

For a graph whose tables are registered with `tenant_column` rather than
pinned to a single graph-level tenant, an explicit tenant argument is a
caller-supplied value, not one verified against the calling role's identity.
While `graph.enforce_tenant_scope = on` (the default), pgGraph refuses an
explicit tenant argument for such a graph and requires the session tenant
(`graph.tenant_setting`) instead. pgGraph cannot verify that a session's
tenant setting reflects who is actually connected; that trust boundary
belongs to whatever sets the session GUC before the caller's own queries run.
See [Tenant Scope](/user_guide/administration-and-security#tenant-scope) for
the full boundary and mitigation guidance.

## Query Compatibility

### GQL and openCypher support are bounded profiles

`graph.gql()` implements the generated [GQL 1.0 profile](/user_guide/gql-profile),
not full ISO GQL. `graph.cypher()` accepts only the overlapping compatibility
profile and does not claim full openCypher support. Unsupported constructs fail
with a stable SQLSTATE and actionable guidance rather than being interpreted
with approximate semantics.

SQL/PGQ `GRAPH_TABLE` is not part of the PostgreSQL 14–18 contract. PostgreSQL
19 integration remains on the [Roadmap](./roadmap).

## Resource Scope

### Limits are per operation and backend, not a cluster-wide memory quota

Build, load, query, synchronization, compaction, and supported analytics enforce
their documented byte, row, work, disk, and elapsed-time policies. PostgreSQL's
own buffer cache, executor memory, and other sessions remain governed by
PostgreSQL configuration and operating-system controls. `graph.memory_limit_mb`
therefore does not replace cluster-wide capacity planning.

Use `graph.resource_status()`, `graph.build_resource_status()`, PostgreSQL
`statement_timeout`, and the production-shaped RSS/PSS release evidence when
sizing concurrent workloads. See [Configuration](/user_guide/configuration)
and [Troubleshooting](/user_guide/troubleshooting#query-or-maintenance-hits-a-resource-limit).

## Reporting A New Issue

Include the pgGraph version, PostgreSQL major, platform, exact SQLSTATE and
`PGxxx` diagnostic, relevant `graph.status()`/`graph.resource_status()` output,
and a minimal source schema. Do not include credentials or production data.