Downsizing a db to 1 PRIMARY topology

Nov 20, 2025
Knowledge

Details

ALTER DATABASE commands can be used to change a database's topology in a cluster. When it comes to downsizing a database's topology, specifically the number of PRIMARY servers in the topology (as only PRIMARY servers participate in Raft consensus operations), this can be done as long as the servers and their current modeConstraints and hosting restrictions allow it. A majority quorum is also needed for this operation, but in a way that is dynamic as the topology scales down.

Majority quorum when downsizing a database's topology

In Neo4j, majority quorum is required for any commit operation, and this includes membership changes. Membership changes still happen implicitly even in the latest versions of Neo4j, but since Neo4j 5.x, database topology is explicitly set through database administration commands (if not using configured defaults).

Quorum must be maintained when reducing the PRIMARY topology of a database; however, as the topology downsizes, quorum shrinks as well, allowing for downsizing down to a minimum of 2 PRIMARY servers.

As an example, if we had a 5 PRIMARY topology for the "neo4j" database, and we executed the following:

ALTER SERVER neo4j SET TOPOLOGY 2 PRIMARIES

then at first glance, one might think this is impossible, as you would lose 3 servers out of 5, losing majority quorum. However, this operation is possible because the number for quorum shrinks as the topology shrinks, and it is a gradual operation.

We can go from 5 PRIMARY servers to 3 PRIMARIES and maintain quorum, and now our cluster topology (and membership) is 3 servers. For this new membership set of 3 servers, the majority quorum is 2 servers, so we can freely downscale to 2 PRIMARIES.

However, the majority quorum of 2 servers is....2 servers. We cannot shrink to 1 server without losing quorum, and the allocator does not allow us to perform this operation.

Downsizing to 1 PRIMARY topology

As described above, we cannot use ALTER DATABASE commands to reach our desired 1 PRIMARY topology, but we can use other means. Our documentation on altering database topology provides one set of steps that involve a bit of manual work:

It is not possible to automatically transition to a topology with a single primary host. Attempting to do so results in an error.

However, it is possible to manually do this transition:

The first step is to back up the database, see Backup and restore for more information.

Once the database is backed up, the next step is to drop the database. See Delete databases for more details.

The last step is to either seed a cluster from the backup with the new topology, or to restore the backup on a single server. See Seed a cluster further on for information on seeding.

There is one other approach that can shortcut the work here, though we still highly recommend taking a backup of your database first, as a failsafe.

In Neo4j 5.24, the recreateDatabase() procedure was added. For a specified database, the procedure allows you to set the desired topology and the seeding servers (or seeding URI) that hold the database data that will be used to seed the other servers needed to fulfil that topology.

Because recreateDatabase() is creating a new database on the cluster instead of altering an existing database, it does not need to observe or obey quorum for the about-to-be-recreated database (however, note that the system database must still maintain quorum so it can commit the topology changes).

This allows us to freely recreate the database to only 1 PRIMARY topology in the cluster. The recreateDatabase() command should also preserve any RBAC data (users, roles, privileges, etc) associated with that database, so we don't need to manually restore database metadata the way we would if we were restoring from a backup.

To note, it is also for these same reasons that we can use the recreateDatabase() procedure in our disaster recovery steps if we should irretrievably lose quorum for a clustered database.

Unlike shrinking down to 1 PRIMARY topology, we can freely scale up the size of a cluster without any special steps using only ALTER DATABASE commands to increase the topology.

NOTE: Do not use recreateDatabase() procedure for "system" database