Skip to main content

​
Overview

The metadb upgrade command upgrades an existing Metadb instance to match the current version of the Metadb software. This command handles database schema changes, data migrations, and other version-specific updates.

​
Syntax

metadb upgrade [options]

​
When to Use

Run the upgrade command:
  • After installing a new version of Metadb
  • Before starting the server after a version update
  • As part of your deployment process when updating Metadb
Always stop the Metadb server before running the upgrade command.

​
Options

​
-D, --dir
string
required
Path to the Metadb data directory to upgrade.
metadb upgrade -D /home/metadb/data
​
--force
boolean
Do not prompt for confirmation before starting the upgrade process.
metadb upgrade -D data --force
​
-v, --verbose
boolean
Enable verbose output to see detailed upgrade progress.
metadb upgrade -D data --verbose
​
--trace
boolean
Enable extremely verbose output for debugging (requires METADB_DEV=on).

​
Examples

metadb upgrade -D data

​
Upgrade Process

When you run the upgrade command:
  1. Metadb checks the current instance version
  2. Determines if upgrades are needed
  3. Applies necessary database schema changes
  4. Performs data migrations if required
  5. Updates configuration if needed

​
Typical Workflow

​
Standard Upgrade Procedure

# 1. Stop the running server
metadb stop -D data

# 2. Backup your data (recommended)
pg_dump metadb > metadb_backup.sql

# 3. Run the upgrade
metadb upgrade -D data

# 4. Start the server with the new version
metadb start -D data -l metadb.log

​
Automated Upgrade Script

#!/bin/bash
set -e

DATA_DIR="/home/metadb/data"
LOG_FILE="/home/metadb/metadb.log"

echo "Stopping Metadb server..."
metadb stop -D "$DATA_DIR"

echo "Running upgrade..."
metadb upgrade -D "$DATA_DIR" --force --verbose

echo "Starting Metadb server..."
nohup metadb start -D "$DATA_DIR" -l "$LOG_FILE" &

echo "Upgrade complete!"

​
Upgrade Outcomes

​
Already Up to Date

If no upgrade is needed: 
metadb: "data" is up to date

​
Upgrade Applied

If changes were applied, you’ll see progress information about:
  • Schema modifications
  • Data migrations
  • Configuration updates
The upgrade process may take significant time depending on your database size and the changes required. The database generally remains available to users during most of the upgrade.

​
Database Availability

During the upgrade:
  • The Metadb server must be stopped
  • The underlying PostgreSQL database typically remains available
  • Most upgrade operations are performed at the database level
  • Some long-running migrations may temporarily impact database performance

​
Best Practices

​
Before Upgrading

1

Backup Your Data

Always create a full backup before upgrading:
pg_dump metadb > metadb_backup_$(date +%Y%m%d).sql
2

Check Version Compatibility

Review the release notes for breaking changes:
metadb version
3

Test in Staging

If possible, test the upgrade in a non-production environment first.
4

Schedule Maintenance

Plan for potential downtime, especially for major version upgrades.

​
After Upgrading

1

Verify Server Startup

Check that the server starts without errors:
tail -f metadb.log
2

Test Connectivity

Connect with psql to verify functionality:
psql -X -h localhost -d metadb -p 8550
3

Monitor Performance

Watch for any performance issues after the upgrade.
4

Check Data Sources

Verify that data sources are streaming correctly:
list status;

​
Troubleshooting

​
Upgrade Fails

If the upgrade fails:
  1. Check the error message - Look for specific issues reported
  2. Review logs - Check for detailed error information
  3. Verify database connectivity - Ensure PostgreSQL is accessible
  4. Check permissions - Verify the systemuser has necessary privileges
  5. Restore from backup - If needed, restore your backup and try again

​
Version Incompatibility

If upgrading from a very old version:
  • You may need to upgrade incrementally through intermediate versions
  • Check release notes for migration paths
  • Contact Metadb support for guidance

​
Long-Running Upgrades

For large databases:
  • Upgrade duration depends on data volume
  • Monitor progress with --verbose flag
  • Don’t interrupt the process
  • Plan adequate maintenance windows

​
Rollback Procedure

If you need to rollback after an upgrade: 
# 1. Stop the server
metadb stop -D data

# 2. Restore from backup
psql metadb < metadb_backup.sql

# 3. Reinstall previous Metadb version
# Follow build instructions for the older version

# 4. Start the server with the old version
metadb start -D data -l metadb.log
Rolling back may result in data loss if new data was written after the upgrade. Always test upgrades in staging first.

​
Version Information

Check your current Metadb version: 
metadb version
Example output: 
metadb version 1.4.0

​
Additional Resources

  • Review release notes for version-specific upgrade information
  • Check the GitHub repository for known issues
  • Backup the metadb.conf file in your data directory
The upgrade command is idempotent - you can safely run it multiple times. If the instance is already up to date, no changes will be made.

Build docs developers (and LLMs) love

Get started for freeTalk to us