# AgensGraph: PostgreSQL with Graph and Relational Queries

> AgensGraph is a transactional multi-model database for applications that need SQL, openCypher, and partial ISO/GQL access within a PostgreSQL-derived platform. It is most relevant when graph traversal and relational data must share transactions and a single database engine.

**skaiworldwide-oss/agensgraph** — AgensGraph, a transactional graph database based on PostgreSQL

- Repository: https://github.com/skaiworldwide-oss/agensgraph
- Website: https://www.skaiworldwide.com/resource
- Stars: 1,512 · Forks: 160
- Language: C
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/skaiworldwide-oss-agensgraph

## Why AgensGraph Combines SQL and openCypher

AgensGraph addresses applications whose useful data does not fit one query model cleanly. A team may already store accounts, orders, permissions, and audit records in relational tables, then need to traverse relationships such as people, organizations, or dependencies through a graph model. AgensGraph is based on PostgreSQL and supports ANSI-SQL, openCypher, and partial ISO/GQL support. Its central claim is that SQL and Cypher queries can be used within a single query rather than requiring separate database engines and application-side joins.

The intended users are developers and database teams that need graph traversal alongside familiar relational features. The README lists ACID transactions, multi-version concurrency control, stored procedures, triggers, constraints, monitoring, and JSON data models. Those features matter when graph reads or writes must participate in the same transactional system as relational records. The project is not merely a graph query library attached to PostgreSQL. It presents itself as a transactional graph database built from the PostgreSQL RDBMS, with `main` as the development branch and release lines such as `v2.<N>` associated with PostgreSQL major versions.

The scope is narrower than the wording “multi-model” may first suggest. The available documentation describes relational and graph data together, but it does not provide a complete catalog of supported PostgreSQL extensions, compatibility guarantees for every PostgreSQL feature, or a formal compatibility matrix for external clients. Those details belong in an adoption review because they determine how much of an existing PostgreSQL installation can be retained.

## AgensGraph Query and Storage Architecture

The documented architecture places graph operations inside a PostgreSQL-derived engine. Graph data uses vertex and edge label hierarchies, and the query language can express relationships with openCypher patterns such as `(a)-[:KNOWS]->(b)`. Relational queries remain available through ANSI-SQL. This arrangement lets a query connect relational context with graph traversal, although the README does not show a complete mixed-query example.

The repository includes PostgreSQL source directories such as `src/`, `contrib/`, `doc/`, `config/`, and build files including `configure`, `GNUmakefile.in`, and `meson.build`. That layout indicates a substantial database implementation rather than a thin client package. It also explains why the project has a source compilation path and why GNU make behavior matters. The top-level `Makefile` searches for a GNU make implementation and tells the builder to run `configure` first.

AgensGraph also adds graph-aware planner behavior through `ag_graphmeta`. This catalog records connected combinations of edge, start, and end labels. With `auto_gather_graphmeta` enabled, the planner propagates label constraints through an entire MATCH pattern. For example, a known `:Person` node can restrict adjacent edge types and reachable destination labels. A labelled edge can also restrict the endpoint labels. The README describes this as arc-consistency over the pattern, using `ag_graphmeta` as the legal-combination relation. Impossible patterns can be proved empty before a scan occurs.

This optimization is useful for queries that contain at least one labelled element. It is not a blanket solution for every graph pattern. Undirected and variable-length edge scans have documented exceptions, and a pattern with no labelled element has no anchor for pruning. In those cases, the documentation says AgensGraph falls back to a full scan.

## Docker Installation and First AgensGraph Session

The README gives a Docker quick start. It pulls the `skaiworldwide/agensgraph` image, creates a container named `agensgraph`, maps host port `5455` to the container's PostgreSQL port `5432`, and sets the database variables used by the image. The image defaults to the `latest` tag, so an operator who needs a fixed release should verify the tag choice before using the command in production.

Pull the documented image first:

```bash
docker pull skaiworldwide/agensgraph
```

The pull should complete before starting the container. The next command uses the exact credentials and database name shown in the README.

```bash
docker run \
    --name agensgraph \
    -p 5455:5432 \
    -e POSTGRES_USER=postgres \
    -e POSTGRES_PASSWORD=agens \
    -e POSTGRES_DB=agens \
    -d \
    skaiworldwide/agensgraph
```

Connect through the container with the `agens` client and the `agens` database:

```bash
docker exec -it agensgraph agens -d agens -U postgres
```

That reaches an interactive AgensGraph client session. The README does not give a first Cypher statement, a sample graph-creation script, or a connection example for an external host. The exposed host port is `5455`, while the client command executes inside the container and does not specify a host or port. For a first real use, an operator would need to follow the documentation for creating graph data and issuing queries; the README does not establish the exact creation syntax.

The repository's `README.md` directs source-build users to `INSTALL.md`. The README does not reproduce that installation procedure, so no source-build command should be inferred from the Docker tutorial.

## Graph Analytics Tuning and Planner Pruning

AgensGraph documents a workload-sensitive tuning issue. PostgreSQL defaults are described as suited to small relational queries, while graph analytics involving neighbourhood aggregation, degree calculations, and multi-hop traversal can create large hash or sort operations. The documented starting point increases memory and parallelism, but the settings are not universal recommendations.

The first relevant setting is `work_mem`. AgensGraph notes that this memory is allocated per sort or hash node, per connection. A value of `256MB` can therefore become expensive when several clients execute large operations concurrently. The README also gives `maintenance_work_mem = 1GB`, `effective_cache_size` at approximately 70% of RAM, `random_page_cost = 1.1` for SSDs, and worker limits for parallelism. Those values are examples and placeholders, not a portable production configuration.

The documentation gives two application methods:

```sql
SET auto_gather_graphmeta = on;
```

This enables maintenance and planner pruning. For persistent configuration, the README says to apply settings with `ALTER SYSTEM SET ...;` and then run `SELECT pg_reload_conf();`, or edit `postgresql.conf`. The exact persistent tuning commands are not supplied, so they are not reproduced here.

Pruning can materially change execution plans without changing results. For a pattern such as `(a:Person)-[r]->(c)`, the planner can use connectivity metadata to narrow the edge types and destination labels. This is especially relevant when an application omits labels but can anchor the pattern elsewhere. It does not remove the need to inspect plans or measure memory use. Parallel workers can help large full-edge scans but add startup overhead for short point reads and single-hop operations. The README specifically advises running `ANALYZE` after bulk-loading a graph so traversal joins have accurate planner statistics.

## Operational Boundaries and Upgrade Surface

AgensGraph carries the operational complexity of a database platform rather than that of a small embedded graph library. The repository includes a broad PostgreSQL-style source tree, build configuration, documentation, and extension areas. The top-level `Makefile` depends on GNU make and requires `configure` to have run before normal build targets. A deployment based on a source build therefore needs to account for the documented PostgreSQL build requirements rather than treating installation as a single package install.

Versioning follows release lines. The README states that `main` is the development branch, `v2.<N>` is the release line on PostgreSQL `<N>`, and `prod` is the newest release of the newest line. It also says to build from a tag, not from `prod`. That distinction matters for repeatability. The README lists `v2.17.0` as the latest shown release and says releases can use names such as `v2.18.4.0`, while the repository's last push was on 2026-10-16. The repository is not archived, but its maintenance status should be judged from that dated activity rather than from broad feature language.

The LICENSE is a concrete adoption constraint. GitHub cannot classify it as one of its standard license types, and the repository points to the `LICENSE` file. This article does not interpret the terms. Any organization evaluating AgensGraph should read that file for source modification, distribution, support, and commercial-use conditions.

There is also a clear scale boundary. AgensGraph is suitable when graph and relational transactions belong together. It is a poor fit when the application needs only a graph API, cannot operate a PostgreSQL-derived server, or expects an unrestricted compatibility claim for existing PostgreSQL workloads. The README does not document a simple uninstall procedure, external client matrix, or rollback process, so those items should be verified in the project's installation documentation and release process before migration.

## AgensGraph Compared with a Separate Graph Service

The practical alternative is a separate graph database alongside a relational database. That arrangement can give each system a focused API and independent scaling, but it introduces cross-database coordination when a business transaction must update both SQL and graph data. AgensGraph takes a different approach: it keeps both models in one PostgreSQL-derived engine and permits SQL and Cypher in the same query context.

The trade-off is operational and conceptual. AgensGraph may simplify atomic application logic when relational records and graph relationships must remain consistent in one transaction. A separate service can be easier for teams whose graph workload is independent, whose graph platform has specialized tooling, or whose relational and graph operations do not need one atomic boundary. The README does not compare query latency, storage size, driver support, or operational overhead with any named product, so no performance conclusion can be drawn from it.

The source-build surface is another distinction. AgensGraph exposes PostgreSQL build files and a source installation guide, while a managed or separately hosted graph service would normally shift compilation to its provider. That statement concerns deployment ownership, not a comparison of features. AgensGraph is the more relevant candidate when minimizing cross-service coordination matters more than adopting a graph-specific platform outside the PostgreSQL ecosystem.

## Conclusion

Adopt AgensGraph when transactional SQL and graph traversal must share one database and your team can operate a PostgreSQL-derived server. Do not choose it solely for an unlabelled graph pattern, because the README documents fallback scans in that case. Verify the custom LICENSE, the build path in INSTALL.md, and the workload-specific memory settings before committing to production.

## FAQ

### How do I install AgensGraph with Docker?

The README documents pulling `skaiworldwide/agensgraph`, starting a container mapped from host port `5455` to container port `5432`, and connecting with `docker exec -it agensgraph agens -d agens -U postgres`. The image defaults to the `latest` tag.

### Can AgensGraph run SQL and openCypher queries together?

Yes. The README says AgensGraph supports ANSI-SQL and openCypher and allows SQL and Cypher queries within a single query. It also states that support for ISO/GQL is partial.

### What does `auto_gather_graphmeta` do?

According to the README, setting `auto_gather_graphmeta` to `on` enables maintenance and planner pruning based on connectivity recorded in `ag_graphmeta`. It can restrict scans using labels known elsewhere in a MATCH pattern, but the documented pruning does not apply in the same way to undirected or variable-length edge scans.

### What license does AgensGraph use?

The repository describes its license as custom, and GitHub cannot classify it under a standard license category. The `LICENSE` file is the authoritative project file to review.

## Sources

- [Issues](https://github.com/skaiworldwide-oss/agensgraph/issues)
- [Project website](https://www.skaiworldwide.com/resource)
- [README](https://github.com/skaiworldwide-oss/agensgraph/blob/main/README.md)
- [Releases](https://github.com/skaiworldwide-oss/agensgraph/releases)
- [skaiworldwide-oss/agensgraph on GitHub](https://github.com/skaiworldwide-oss/agensgraph)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/skaiworldwide-oss-agensgraph