Archive Upgrade

This guide describes the general procedure for upgrading a Mina archive database from Berkeley to Mesa. The same steps apply to every Mesa deployment (preflight, devnet, mainnet) — only the archive package version differs.

Mesa preflight hard fork completed

The Mesa preflight network hard-forked at 2026-04-27 13:00 UTC. The post-fork chain runs 4.0.0-preflight-3f038cb, which raises the transaction protocol version to 5.0.0. Pre-fork builds — including the stop-slot release 4.0.0-preflight-stop-2967b39 — are no longer compatible.

When upgrading a preflight archive database, install the matching mina-archive-mesa=4.0.0-preflight-3f038cb package so the archive node speaks the new transaction protocol.

Choosing the Mesa archive version

The commands below use <MESA_VERSION> as a placeholder for the archive build you want to install. Substitute the tag that matches your target network:

• Preflight network — use 4.0.0-preflight-3f038cb (post-hard-fork; transaction protocol v5.0.0). See Preflight Network for the full release matrix.
• Devnet / mainnet — use the Mesa release tag published for that network when it is announced.

To successfully upgrade the archive database to Mesa, you must ensure that your environment meets the foundational requirements.

Upgrade host

• PostgreSQL database for database server
• If you use Docker, then any of the supported OS by Mina (bullseye, focal, noble, bookworm or jammy) with at least 32 GB of RAM
• gsutil application from Google Cloud Suite in version 5 or later
• (Optional) Docker in version 23.0 or later

Archive database

One of the most obvious prerequisites is a Mainnet database. If you don't have an existing database with Devnet/Mainnet archive data, you can always download it from the O1Labs Google Cloud bucket.

Upgrade process

Upgrade script

Assuming that you have a PostgreSQL database with Mainnet archive data, in order to upgrade it to Mesa version, you need to run SQL upgrade script. We put all efforts to make the upgrade process as smooth as possible. Script can be run on archive node which is online or offline. Script can be run multiple times, it will skip steps that were already completed. It also performs sanity checks before each step to ensure that the upgrade process is successful. Finally it creates new table (version) in the database to keep track of the upgrade process.

Getting the script

You can find the SQL upgrade script in the Mina repository on GitHub. Make sure to download the latest version of the script before proceeding. You can download the script directly using the following command:

curl -O https://raw.githubusercontent.com/MinaProtocol/mina/refs/heads/mesa/src/app/archive/upgrade_to_mesa.sql

We also ship the script in the Mina archive Docker image and Debian package.

docker run --rm gcr.io/o1labs-192920/mina-archive:<MESA_VERSION>-bookworm-mesa cat /etc/mina/archive/upgrade-to-mesa.sql > upgrade-to-mesa.sql

# Setup the Mina repository and install the archive package.
# Repository setup (apt sources, GPG key, channel) is network-specific —
# see Preflight Network for the preflight pin, or your network's release notes.

apt-get install mina-archive-mesa=<MESA_VERSION>

# View the upgrade and downgrade scripts
cat /etc/mina/archive/upgrade-to-mesa.sql
cat /etc/mina/archive/downgrade-to-berkeley.sql

Running the script

Database Backup

Before running the upgrade script, backup your archive database. The upgrade modifies the database schema.

pg_dump -U <username> <database> > berkeley-archive-backup.sql

To run the upgrade script, execute the following command:

psql -U <username> -d <database> -f upgrade-to-mesa.sql

Make sure to replace <username> and <database> with your actual PostgreSQL username and database name.

Rollback

You can rollback the upgrade process by restoring the database from a backup taken before running the upgrade script. Another is to run rollback script which is part of the upgrade script. It will drop all tables and other database objects created by the upgrade script. It will also update the version table to reflect the rollback.

Running the rollback script

To run the rollback script, you need to execute the following command:

psql -U <username> -d <database> -f /etc/mina/archive/downgrade-to-berkeley.sql

Make sure to replace <username> and <database> with your actual PostgreSQL username and database name.

Post-upgrade steps

After successfully running the upgrade script, you DO NOT need to restart your archive node or Rosetta API. Changes in upgrade script are backward compatible and will be picked up by the archive node and Rosetta API automatically.

Verification with the Archive Hardfork Toolbox

The mina-archive-hardfork-toolbox is a dedicated CLI tool for verifying the integrity of archive database upgrades and fork transitions. It is shipped with the Mina archive package and available as a standalone binary.

For full details, see the toolbox README.

All commands below require a --postgres-uri flag in the format:

postgresql://<user>:<password>@<host>:<port>/<database>

Step 1: Pre-fork validation (before the fork)

Verify the fork block candidate is valid before the network halts.

Check that the fork block is in the best chain:

mina-archive-hardfork-toolbox fork-candidate is-in-best-chain \
  --postgres-uri <uri> \
  --fork-state-hash <hash> \
  --fork-height <height> \
  --fork-slot <slot>

Verify the fork block has enough confirmations:

mina-archive-hardfork-toolbox fork-candidate confirmations \
  --postgres-uri <uri> \
  --latest-state-hash <hash> \
  --fork-slot <slot> \
  --required-confirmations <n>

Verify no commands were executed after the fork block (ensures a clean fork point):

mina-archive-hardfork-toolbox fork-candidate no-commands-after \
  --postgres-uri <uri> \
  --fork-state-hash <hash> \
  --fork-slot <slot>

Find the last block with transactions (useful for identifying the fork point):

mina-archive-hardfork-toolbox fork-candidate last-filled-block \
  --postgres-uri <uri>

Step 2: Verify the schema upgrade

After running upgrade-to-mesa.sql, verify the database schema was upgraded correctly:

mina-archive-hardfork-toolbox verify-upgrade \
  --postgres-uri <uri> \
  --protocol-version <version> \
  --migration-version <version>

You can also verify manually by checking the version table:

psql -U <username> -d <database> -c "SELECT * FROM version;"

If the upgrade was successful, the version table will contain an entry with the expected version number and a recent timestamp.

Step 3: Post-fork validation

After the fork activates and the Mesa chain is running, validate the fork block and its ancestry:

mina-archive-hardfork-toolbox validate-fork \
  --postgres-uri <uri> \
  --fork-state-hash <hash> \
  --fork-slot <slot>

Step 4: Mark the canonical chain (if needed)

If you need to mark the chain leading to a specific block as canonical for the new protocol version:

mina-archive-hardfork-toolbox convert-chain-to-canonical \
  --postgres-uri <uri> \
  --target-block-hash <state-hash> \
  --protocol-version <transaction>.<network>.<patch>

Optionally use --stop-at-slot <slot> to limit how far back in history the marking goes.

Typical workflow

1. Before the fork: run fork-candidate commands to validate the fork block
2. After running the upgrade script: run verify-upgrade to confirm the schema upgrade
3. After the fork activates: run validate-fork to confirm data integrity
4. For full archive verification: run the Archive Replayer to replay all transactions and compare the resulting ledger against the official fork config

If you encounter any issues, reach out to the Mina community on Discord or GitHub Discussions.

Full Archive Verification with the Replayer

The toolbox commands above verify the schema and fork block integrity, but they do not verify every transaction in the archive. For complete end-to-end verification, use the Archive Replayer — a tool that replays all transactions from genesis (or a checkpoint) through the fork point, recomputing the ledger state and comparing it against the official fork config.

The replayer is not limited to upgrade-time use. It is an ongoing verification tool that can be run at any time to confirm your archive database faithfully represents the canonical chain. After the Mesa upgrade, you can continue running it against Mesa blocks to detect any data corruption or missing blocks.

See Archive Replayer for usage, flags, and examples.

Database Schema Changes

For details on the database schema changes between Berkeley and Mesa, see the Appendix.