# GreptimeDB 元信息导出和导入工具

> 介绍 GreptimeDB 的元数据导出和导入工具，用于数据库元信息的备份和恢复，包括命令语法、选项、常见使用场景

# GreptimeDB 元信息导出和导入工具

本指南描述了如何使用 GreptimeDB 的元信息导出和导入工具进行元数据库备份和恢复。

有关详细的命令行选项和高级配置，请参阅 [元数据导出和导入](/reference/command-lines/utilities/metadata.md)。

:::note
- 如果 Metasrv 使用 PostgreSQL 后端并设置了 `meta_schema_name`，需要通过 `--meta-schema-name` 传入相同的 schema。不传时，CLI 读写的是连接 `search_path` 中的元数据表，可能不是 Metasrv 使用的那张表。
- `--backend-tls-mode` 默认为 `disable`。如果元数据存储要求 TLS，需要设置 `--backend-tls-mode` 及相关的 `--backend-tls-*` 参数。
:::

## 概述

## 导出操作

### 导出到 S3 云存储

将元数据从 PostgreSQL 导出到 S3 云存储，用于云备份存储：

```bash
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>
```

**输出**: 在指定的 S3 桶中创建 `metadata_snapshot.metadata.fb` 文件。

### 导出到本地目录

#### 从 PostgreSQL 后端导出

将元数据从 PostgreSQL 导出到本地目录：

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

#### 从 MySQL 后端导出

将元数据从 MySQL 导出到本地目录：

```bash
greptime cli meta snapshot save \
    --store-addrs 'mysql://user:password@127.0.0.1:3306/database' \
    --backend mysql-store
```

#### 从 etcd 后端导出

将元数据从 etcd 导出到本地目录：

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

**输出**: 在当前工作目录中创建 `metadata_snapshot.metadata.fb` 文件。

#### 从 RaftEngine 后端导出

:::note
RaftEngine 在 standalone 实例运行期间会锁定元数据目录，请在导出前停止 standalone 实例。
:::

将元数据从 RaftEngine 导出到本地目录：

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

**输出**: 在当前工作目录中创建 `metadata_snapshot.metadata.fb` 文件。

## 导入操作

:::warning
**重要**: 在导入元数据之前，请确保目标存储后端的对应表中没有**任何数据**，否则可能会导致元数据损坏。

如果目标后端非空且**未**传 `--force`，命令只会打印一条警告便退出，不恢复任何数据，而退出码仍为成功。因此必须查看命令输出，不能想当然地认为恢复已经完成。

`--force` 只会跳过非空检查，不会清空目标后端。恢复时，快照中的键会直接写入，其他已有键仍会保留，因此可能导致元数据不一致。建议恢复到一个空的目标后端，并在重启集群后检查 catalog、表路由和 Procedure 状态。
:::

### 从 S3 云存储导入

从 S3 备份恢复元数据到 PostgreSQL 存储后端：

```bash
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>
```

### 从本地文件导入

#### 导入到 PostgreSQL 后端

从本地备份文件恢复元数据到 PostgreSQL：

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

#### 导入到 MySQL 后端

从本地备份文件恢复元数据到 MySQL:

```bash
greptime cli meta snapshot restore \
    --store-addrs 'mysql://user:password@127.0.0.1:3306/database' \
    --backend mysql-store
```

#### 导入到 etcd 后端

从本地备份文件恢复元数据到 etcd：

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

#### 导入到 RaftEngine 后端

从本地备份文件恢复元数据到 RaftEngine：

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