feat(extensions): Add Apache AGE graph database extension

[jpabbuehl]

Summary

Add support for Apache AGE (A Graph Extension), bringing graph database capabilities and the Cypher query language to PGlite.

What is AGE?

Apache AGE is a PostgreSQL extension that adds:

• Graph data model: Nodes (vertices) and relationships (edges)
• Cypher query language: Industry-standard graph query language
• Hybrid queries: Combine SQL and Cypher in the same database

Usage

import { PGlite } from '@electric-sql/pglite'
import { age } from '@electric-sql/pglite/age'

const pg = new PGlite({ extensions: { age } })

// Create a graph
await pg.exec("SELECT ag_catalog.create_graph('social');")

// Create nodes and relationships
await pg.exec(SELECT * FROM ag_catalog.cypher('social', $$ CREATE (alice:Person {name: 'Alice'})-[:KNOWS]->(bob:Person {name: 'Bob'}) RETURN alice, bob $$) as (alice ag_catalog.agtype, bob ag_catalog.agtype);)

// Query the graph
const result = await pg.query(SELECT * FROM ag_catalog.cypher('social', $$ MATCH (p:Person)-[:KNOWS]->(friend:Person) RETURN p.name, friend.name $$) as (person ag_catalog.agtype, friend ag_catalog.agtype);)## Changes

New Files

File	Description
packages/pglite/src/age/index.ts	Extension wrapper with initialization
packages/pglite/tests/age.test.ts	Comprehensive test suite (43 tests)
docs/extensions/age.md	User documentation with examples

Modified Files

File	Change
packages/pglite/package.json	Add ./age export
packages/pglite/tsup.config.ts	Add src/age/index.ts entry point
packages/pglite/scripts/bundle-wasm.ts	Add age path replacement

Technical Details

Extension Initialization

The wrapper handles:

1. CREATE EXTENSION IF NOT EXISTS age
2. LOAD 'age' (activates Cypher parser hooks)
3. SET search_path (includes ag_catalog for operator class resolution)
4. Hook verification (ensures Cypher parsing works)

32-bit WASM Compatibility

AGE required patches for PGlite's 32-bit WASM environment. The postgres-pglite PR includes AGE as a submodule from a fork with these patches.

Documentation

Full documentation added at docs/extensions/age.md:

• Installation and setup
• Quick start guide
• Complete social network example
• Cypher syntax reference
• Known limitations

Limitations

• load_labels_from_file() not available (no filesystem in WASM)
• Large graphs may hit WASM memory limits
• CPU-intensive for complex graph traversals

Related PRs

• postgres-pglite build changes: electric-sql/postgres-pglite@REL_17_5_WASM-pglite-builder...jpabbuehl:postgres-pglite:feat/age-extension
• AGE 32-bit compatibility (upstream): apache/age@master...jpabbuehl:age:feat/32bit-wasm-support

Checklist

• TypeScript compiles without errors
• All 43 tests pass (pnpm test)
• ESM and CJS builds work
• Documentation added
• Package exports configured
• Browser testing (pnpm test:web)

[tdrz]

@jpabbuehl Thank you for this! We are having a bit of time off atm, but we'll have a look at this as soon as we're back.

I know it's a lot to ask, but would it be possible to upstream your changes for 32bit support to the official AGE repo?

[jpabbuehl]

apache/age#2286

Here it is.

[tdrz]

@jpabbuehl We really like this but we are not quite ready to link to individual's repos. It would be great to have that PR merged on the Apache repo. Will comment there as well.

One other option would be for us to make a fork of the main repo and apply your changes there. The issue with this approach is that we'll be left maintaining it and we are tight on resources...