Metadata Export & Import

This guide describes how to use GreptimeDB's metadata export and import tools for metadata backup and restoration operations.

For detailed command-line options and advanced configurations, please refer to Metadata Export & Import.

Overview

Export Operations

Export to S3 Cloud Storage

Export metadata from PostgreSQL to S3 for cloud-based backup storage:

greptime cli meta snapshot save \
    --store-addrs 'password=password dbname=postgres user=postgres host=localhost port=5432' \
    --backend postgres-store \
    --s3 \
    --s3-bucket your-bucket-name \
    --s3-region ap-southeast-1 \
    --s3-access-key-id <your-s3-access-key-id> \
    --s3-secret-access-key <your-s3-secret-access-key>

Output: Creates metadata_snapshot.metadata.fb file in the specified S3 bucket.

Export to Local Directory

From PostgreSQL Backend

Export metadata from PostgreSQL to local directory:

greptime cli meta snapshot save \
    --store-addrs 'password=password dbname=postgres user=postgres host=localhost port=5432' \
    --backend postgres-store

From MySQL Backend

Export metadata from MySQL to local directory:

greptime cli meta snapshot save \
    --store-addrs 'mysql://user:[email protected]:3306/database' \
    --backend mysql-store

From etcd Backend

Export metadata from etcd to local directory:

greptime cli meta snapshot save \
    --store-addrs 127.0.0.1:2379 \
    --backend etcd-store

Output: Creates metadata_snapshot.metadata.fb file in the current working directory.

From RaftEngine Backend

note

RaftEngine locks the metadata directory while the standalone instance is running. Stop the standalone instance before exporting.

Export metadata from RaftEngine to local directory:

greptime cli meta snapshot save \
    --store-addrs "raftengine:///path/to/metadata" \
    --backend raft-engine-store

Output: Creates metadata_snapshot.metadata.fb file in the current working directory.

Import Operations

warning

Important: Before importing metadata, ensure the target backend is in a clean state (contains no existing data). Importing to a non-empty backend may result in data corruption or conflicts.

If the target backend is not empty and you do not pass --force, the command logs a warning and exits without restoring anything. It still returns a success exit code, so check the command output rather than assuming the restore ran.

--force only bypasses the non-empty check. It does not clear the target first: the restore writes the keys contained in the snapshot and leaves any other existing keys in place, which is how a restored cluster ends up mixing two generations of metadata. Prefer restoring into an empty backend, then restart the whole cluster and verify catalogs, table routes, and procedures.

Import from S3 Cloud Storage

Restore metadata from S3 backup to PostgreSQL storage backend:

greptime cli meta snapshot restore \
    --store-addrs 'password=password dbname=postgres user=postgres host=localhost port=5432' \
    --backend postgres-store \
    --s3 \
    --s3-bucket your-bucket-name \
    --s3-region ap-southeast-1 \
    --s3-access-key-id <your-s3-access-key-id> \
    --s3-secret-access-key <your-s3-secret-access-key>

Import from Local File

To PostgreSQL Backend

Restore metadata from local backup file to PostgreSQL:

greptime cli meta snapshot restore \
    --store-addrs 'password=password dbname=postgres user=postgres host=localhost port=5432' \
    --backend postgres-store

To MySQL Backend

Restore metadata from local backup file to MySQL:

greptime cli meta snapshot restore \
    --store-addrs 'mysql://user:[email protected]:3306/database' \
    --backend mysql-store

To etcd Backend

Restore metadata from local backup file to etcd:

greptime cli meta snapshot restore \
    --store-addrs 127.0.0.1:2379 \
    --backend etcd-store

To RaftEngine Backend

Restore metadata from local backup file to RaftEngine:

greptime cli meta snapshot restore \
    --store-addrs "raftengine:///path/to/metadata" \
    --backend raft-engine-store