# Roadmap

<Callout type="info">
This roadmap describes future direction, not dated release commitments. Future
features will continue to use PostgreSQL tables as the source of truth.
</Callout>

## Current Baseline

pgGraph supports PostgreSQL 14 through 18 with a stable documented SQL API and
a defined subset of GQL reads and writes. The current engine provides:

- manual and discovered table/relationship registration, named graphs, grants,
  quotas, and tenant scoping;
- bounded search, traversal, paths, workflows, filters, aggregation, and
  connected-component analytics;
- supported GQL writes that update mapped PostgreSQL tables first, preserving
  constraints, triggers, ACLs, RLS, MVCC, and row identity;
- trigger-log synchronization and scheduled maintenance with compaction,
  repair, and cleanup;
- atomic, validated persisted indexes with crash recovery and retention of the
  last valid index;
- enforced byte, row, work, disk, file, and elapsed-time policies with stable
  resource diagnostics;
- published SQL and GQL feature profiles, packaged playground examples, and
  verified support for PostgreSQL 14 through 18.

The exact supported surfaces are documented in the
[SQL 1.0 profile](/user_guide/sql-profile),
[GQL 1.0 profile](/user_guide/gql-profile), and
[Versioning And Compatibility](/user_guide/versioning-and-compatibility).

## 1.0 Production Baseline

The 1.0 release established these ongoing release requirements:

| Area | Release outcome |
|---|---|
| Documentation | Public quickstart, migration, operations, API, compatibility, and limitations guidance, checked for drift. |
| Packaging | Verified source and PGXN packages for PostgreSQL 14–18, with matching checksums, SBOMs, provenance, and license checks. |
| Release gates | Repeatable release checks with retained logs. |
| Operations | Verified procedures for installation, alpha-to-1.0 migration, rebuild, rollback, backup and restore, crash recovery, cancellation, resource limits, and cleanup. |
| Release evidence | Reviewed evidence tied to the exact release commit before tagging or publication. |

Future 1.x work does not weaken these outcomes. New query syntax, analytics
breadth, and architecture expansion remain post-1.0 directions.

## Post-1.0 Direction

| Area | Direction |
|---|---|
| ISO GQL | Add applicable ISO/IEC 39075:2024 features in vertical slices, each with parser, binder, executor, conformance, ACL/RLS, transaction, resource, and documentation evidence. |
| Costed streaming runtime | Develop canonical typed binding-table IR, statistics, cost/resource planning, alternative physical plans, streaming operators, and spillable blocking work. |
| PostgreSQL 19 and SQL/PGQ | Consume native property-graph definitions without duplicate registration and maintain a separate SQL/PGQ conformance matrix for `GRAPH_TABLE`. |
| Compatibility frontends | Keep openCypher bounded unless a separately measured and maintained compatibility surface is justified. |
| Selective residency and caching | Investigate plan caching, selective projection residency, and workload-aware artifact placement within explicit PostgreSQL resource budgets. |
| Synchronization | Evaluate optional WAL-driven synchronization only if it preserves PostgreSQL as the source of truth and provides safe recovery, privileges, ordering, and bounded retention. |
| Analytics | Move broader whole-graph algorithms into quota-controlled execution with cancellation, progress, and reproducible scorecards. |
| Semantic guidance | Explore pgVector-assisted candidate ranking without placing embedding work in the traversal hot path or making embeddings authoritative. |
| Refactoring | Revisit module or core-crate extraction only when dependency and ownership evidence shows a concrete reliability or maintainability benefit. |
| Distributed execution | Remain research-driven until a PostgreSQL-consistent ownership, transaction, recovery, and operations model is demonstrated. |

## Decision Rules

- Current user-visible limitations belong in [Known Issues](./known-issues).
- Shipped behavior and migrations belong in [Release Notes](./release-notes).
- Public SQL, GQL, configuration, diagnostics, artifacts, and scripts follow the
  documented 1.x compatibility and deprecation policy.
- Features graduate from this roadmap only with production implementation,
  tests, public documentation, and release-gate ownership.