Demo

This page runs the upgrade procedure from start to finish on a real cluster, with the actual commands and output, upgrading a 2.16 cluster that contains a graph. The two installations are:

export OLD=/usr/local/agensgraph-2.16   OLDDATA=$OLD/data
export NEW=/usr/local/agensgraph-2.17   NEWDATA=$NEW/data

Starting point. The 2.16 cluster has a database agdb containing a social graph with three person vertices and two knows edges:

$ $OLD/bin/psql -U postgres -d agdb
agens=# SELECT version();
 PostgreSQL 16.9 (AgensGraph 2.16) on x86_64-pc-linux-gnu ...

agens=# SET graph_path = social;
SET
agens=# MATCH (a:person)-[k:knows]->(b:person)
        RETURN a.name AS from_p, b.name AS to_p, k.since AS since ORDER BY from_p;
 from_p  |  to_p   | since
---------+---------+-------
 "Alice" | "Bob"   | 2015
 "Bob"   | "Carol" | 2020
(2 rows)
agens=# \q

Step 1 — stop the old server.

$ $OLD/bin/pg_ctl -D $OLDDATA stop
waiting for server to shut down.... done
server stopped

Step 2 — initialize the new 2.17 cluster.

$ $NEW/bin/initdb -D $NEWDATA -U postgres --encoding=UTF8
...
Success. You can now start the database server.

Step 3 — check compatibility.

$ $NEW/bin/pg_upgrade -b $OLD/bin -B $NEW/bin -d $OLDDATA -D $NEWDATA -U postgres --check
Performing Consistency Checks
-----------------------------
Checking cluster versions                                     ok
Checking database user is the install user                    ok
Checking database connection settings                         ok
Checking for prepared transactions                            ok
Checking data type usage                                      ok
Checking for presence of required libraries                   ok
Checking for new cluster tablespace directories               ok

*Clusters are compatible*

Step 4 — run the upgrade.

$ $NEW/bin/pg_upgrade -b $OLD/bin -B $NEW/bin -d $OLDDATA -D $NEWDATA -U postgres
Performing Upgrade
------------------
...
Restoring database schemas in the new cluster                 ok
Copying user relation files                                   ok
...
Upgrade Complete
----------------

Step 5 — start the new server.

$ $NEW/bin/pg_ctl -D $NEWDATA -l $NEW/logfile start
waiting for server to start.... done
server started

Step 6 — verify the graph survived. Connect to the upgraded cluster and run the same query as the starting point — the data is identical, now on 2.17:

$ $NEW/bin/psql -U postgres -d agdb
agens=# SELECT version();
 PostgreSQL 17.10 (AgensGraph 2.17) on x86_64-pc-linux-gnu ...

agens=# SET graph_path = social;
SET
agens=# MATCH (a:person)-[k:knows]->(b:person)
        RETURN a.name AS from_p, b.name AS to_p, k.since AS since ORDER BY from_p;
 from_p  |  to_p   | since
---------+---------+-------
 "Alice" | "Bob"   | 2015
 "Bob"   | "Carol" | 2020
(2 rows)

Step 7 — rebuild statistics and remove the old cluster.

$ $NEW/bin/vacuumdb -U postgres --all --analyze-in-stages
$ ./delete_old_cluster.sh

The social graph — its labels, vertices, edges, and all properties — is carried over to the 2.17 cluster unchanged.