Update README.md#2414
Merged
jrgemignani merged 1 commit intoapache:masterfrom Apr 27, 2026
Merged
Conversation
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
approved these changes
Apr 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
psycopgv3, also JDBC withautoCommit=false) report that graphs created viaSELECT create_graph(...)appear to succeed but are not visible from new connections. The root cause is standard PostgreSQL behavior, not an AGE bug:LOAD 'age'andSET search_path = ...are session-local and don't need a commit.create_graph(...)and similar calls write toag_catalog(and create schemas/tables). Those writes follow normal transactional visibility rules.LOAD 'age') implicitly opens an outer transaction. A laterwith 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 thecreate_graphwrite 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_graphbypass 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:with conn.transaction():inside an already-open outer transaction).conn.commit()afterLOAD/SET search_path.psycopg.connect(..., autocommit=True).setAutoCommit(true)and explicitcommit()after DDL-like calls.What this PR does not do
drivers/python/README.mdor any driver docs (the mainREADME.mdis the most discoverable place; happy to mirror a shortened version into a driver README if maintainers prefer).Testing
N/A — markdown-only. Rendered the section locally to confirm headings, code fences, and the table display correctly on GitHub.
Checklist