Site Replication and Disaster Recovery

MinIO AIStor Tables integrates with site replication so that your Iceberg catalog and warehouse data are available on a disaster-recovery (DR) site. This page describes what replicates, how to monitor replication, and how to fail over and recover after a disaster.

What replicates

When site replication is configured, MinIO AIStor Tables replicates the following to every peer site:

Warehouses and their catalogs
Namespaces
Tables and their data
Default warehouse encryption configuration

Each site runs a dedicated catalog scanner that rebuilds the replica catalog from the replicated data, so a replica matches the primary without manual intervention.

Single replica for AIStor Tables

AIStor Tables site replication supports one primary site and a single disaster-recovery replica.

Warehouse buckets use site replication

Warehouse buckets are managed by site replication. You cannot configure bucket replication on a warehouse bucket; MinIO AIStor rejects the request with a clear error.

Monitor replication

A replica site accepts inbound replication but rejects client writes. Use mc table replicate status to check catalog scanner progress and per-warehouse, per-namespace, and per-table replication state, including how many versions each replica is behind and any missing files:

mc table replicate status myaistor

Fail over to the DR site

If the primary site becomes unavailable, promote the DR site to accept write traffic.

Fence the old primary before promoting

Run mc table replicate failover only after the old primary is fenced. Before promotion, cut client and load-balancer traffic to the old primary (or otherwise ensure it cannot accept writes), and confirm the cutover. Promotion is safe only once fencing and traffic cutover are confirmed: during a network partition, if both sites remain writable they can accept divergent catalog and table changes that must be reconciled when you recover the old primary.

Once the old primary is fenced, promote the DR site:

mc table replicate failover myaistor

Failover completes asynchronously. Monitor its progress with mc table replicate status. Once failover is complete, the promoted site accepts write traffic and the old primary requires manual intervention before it can rejoin.

Recover the old primary after failover

After a failover, the old primary must be demoted back to a replica before it can rejoin the replication group. This is a two-phase process that discards any writes that exist only on the old primary.

Run resync against the old primary

Run the following commands against the old primary site, not the new primary. The rebuild step backs up and deletes the local catalog, discarding writes that exist only on this site.

Open a resync window on the old primary. This site then accepts inbound replication but rejects client writes:
```
mc table replicate resync open myaistor
```
Resync object data from the new primary and wait for it to complete:
```
mc admin replicate resync start NEWPRIMARY myaistor
```
Rebuild the catalog on the old primary from the new primary. This backs up and deletes the local catalog, then rebuilds it on the next scanner cycle. On success, the site becomes a replica:
```
mc table replicate resync rebuild myaistor
```
This command prompts for confirmation. Pass --yes to skip the prompt in automation.

Monitor the rebuild with mc table replicate status.

Additional recovery tools

MinIO AIStor Tables provides additional tools for recovering a replica catalog:

Reset the replica catalog. mc table replicate catalog reset backs up and deletes the replica catalog, then rebuilds it from scratch on the next scanner cycle. Restoring the backup requires manual intervention. This command prompts for confirmation; pass --yes to skip the prompt.
```
mc table replicate catalog reset myaistor
```

Backfill catalog identity. mc table replicate backfill start, backfill status, and backfill cancel manage a catalog identity backfill:

mc table replicate backfill start myaistor
mc table replicate backfill status myaistor
mc table replicate backfill cancel myaistor

Use these tools only when guided by the recovery workflow above or by MinIO support.