crprashant opened a new pull request, #2414:
URL: https://github.com/apache/age/pull/2414
## 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:
- A table showing which AGE statements are session-local vs. transactional
catalog writes.
- An explanation of the psycopg "savepoint gotcha" (`with
conn.transaction():` inside an already-open outer transaction).
- A **broken** psycopg v3 example reproducing the behavior reported in #2195.
- Two **working** psycopg v3 fixes:
- Explicit `conn.commit()` after `LOAD` / `SET search_path`.
- `psycopg.connect(..., autocommit=True)`.
- A short JDBC note covering both `setAutoCommit(true)` and explicit
`commit()` after DDL-like calls.
- A one-line rule of thumb and a link back to #2195.
## 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
- [x] Documentation-only change
- [x] References the original issue (#2195)
- [x] No breaking changes
- [x] No code or schema changes
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
