Skip to content

Update README.md#2414

Merged
jrgemignani merged 1 commit intoapache:masterfrom
crprashant:master
Apr 27, 2026
Merged

Update README.md#2414
jrgemignani merged 1 commit intoapache:masterfrom
crprashant:master

Conversation

@crprashant
Copy link
Copy Markdown
Contributor

Summary

Adds a new "Using AGE with Non-Autocommit Clients (psycopg, JDBC, etc.)" section to the main README.md, documenting how PostgreSQL transaction semantics apply to AGE's DDL-like functions (create_graph, create_vlabel, create_elabel, drop_graph, etc.).

This is the "acceptable fallback" resolution proposed in #2195.

Refs #2195

Why

Users of non-autocommit clients (most commonly psycopg v3, also JDBC with autoCommit=false) report that graphs created via SELECT create_graph(...) appear to succeed but are not visible from new connections. The root cause is standard PostgreSQL behavior, not an AGE bug:

  1. LOAD 'age' and SET search_path = ... are session-local and don't need a commit.
  2. create_graph(...) and similar calls write to ag_catalog (and create schemas/tables). Those writes follow normal transactional visibility rules.
  3. In psycopg v3, the very first statement (LOAD 'age') implicitly opens an outer transaction. A later with conn.transaction(): block then runs as a savepoint inside that outer transaction, not as a new top-level transaction. Releasing a savepoint is not a commit — so the create_graph write never becomes visible to other sessions until the outer transaction is explicitly committed (or the connection is closed on a clean commit path).

Since making create_graph bypass transactional visibility would violate ACID, the right fix is to document the requirement clearly, which is what this PR does.

What this PR adds

A new section in README.md (placed between Post Installation and Quick Start) containing:

What this PR does not do

  • No code changes — documentation only.
  • Does not modify drivers/python/README.md or any driver docs (the main README.md is the most discoverable place; happy to mirror a shortened version into a driver README if maintainers prefer).
  • Does not change AGE's actual transactional behavior.

Testing

N/A — markdown-only. Rendered the section locally to confirm headings, code fences, and the table display correctly on GitHub.

Checklist

docs: Clarify transaction/commit semantics with non-autocommit clients

Adds a "Using AGE with Non-Autocommit Clients" section explaining
PostgreSQL transaction visibility rules as they apply to AGE DDL-like
functions (create_graph, create_vlabel, etc.), with broken/fixed
psycopg v3 examples and a JDBC note.

Refs apache#2195
@jrgemignani jrgemignani merged commit 22f4c94 into apache:master Apr 27, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants