复制数据库存储
企业版

您可以使用 neo4j-admin database copy 命令来复制数据库、创建数据库的压缩/碎片整理副本、清理数据库不一致性，或者从 Neo4j 4.4 直接迁移到任何 5.x 版本。neo4j-admin database copy 会回收未使用的空间，创建数据存储的碎片整理副本，并创建节点标签和关系类型查找索引。

命令限制

  • neo4j-admin database copy 会保留节点 ID（除非使用了 --compact-node-store），但关系会获得新的 ID。

  • neo4j-admin database copy 不支持在 system 数据库上使用。

  • neo4j-admin database copy 不支持在 复合数据库 (Composite databases) 上使用。它必须直接在与该复合数据库关联的数据库上运行。

  • neo4j-admin database copy 是一个 IOPS 密集型进程。有关更多信息，请参阅 预估处理时间。

命令

neo4j-admin database copy 将现有离线数据库的数据存储复制到新数据库。

语法

neo4j-admin database copy [-h] [--copy-schema] [--expand-commands] [--force] [--verbose] [--compact-node-store[=true|false]]
                             [--additional-config=<file>] [--from-pagecache, --max-off-heap-memory=<size>]
                             [--property-shard-count=<propertyShardCount>] [--source-format=<format>] [--source-location=<path>] [--target-format=<format>] [--target-location=<path>]
                             [--temp-path=<path>] [--to-format=<format>]
                             [--to-path-schema=<path>] [--copy-only-node-properties=<label.property>[,<label.property>...]]...
                             [--copy-only-nodes-with-labels=<label>[,<label>...]]... [--copy-only-relationship-properties=<relationship.
                             property>[,<relationship.property>...]]... [--copy-only-relationships-with-types=<type>[,<type>...]]...
                             [--ignore-nodes-with-labels=<label>[,<label>...]]... [--ignore-relationships-with-types=<type>[,<type>...]]...
                             [--skip-labels=<label>[,<label>...]]... [--skip-node-properties=<label.property>[,<label.property>...]]...
                             [--skip-properties=<property>[,<property>...]]... [--skip-relationship-properties=<relationship.property>[,
                             <relationship.property>...]]... [--from-path-data=<path> --from-path-txn=<path>] [--to-path-data=<path>
                             --to-path-txn=<path>] <fromDatabase> <toDatabase>

描述

此命令创建一个数据库副本。如果您的标签、属性或关系包含点或逗号，可以使用反引号进行引用，例如 `My,label`, `My.property`。系统将创建一个名为 <database-name>-schema.cypher 的文件，其中包含在副本上重新创建索引/约束所需的模式命令。

您可以使用 --copy-schema 选项自动复制模式。索引将在数据库首次启动时构建。此选项可以将任何 4.4 和 5.x 版本的模式复制到 5.26 LTS 及更高版本。

参数

表 1. neo4j-admin database copy 参数
参数 描述

<fromDatabase>

要复制的来源数据库名称。

<toDatabase>

要复制到的目标数据库名称。

如果您不需要数据库的实际副本，可以使用相同的 <fromDatabase> 和 <toDatabase> 值。在这种情况下，数据库会被复制到临时位置（默认为当前工作目录或由 --temp-path 定义的路径），然后再移动以替换原数据库。

选项

neo4j-admin database copy 命令具有以下选项

表 2. neo4j-admin database copy 选项
选项 描述 默认

--additional-config=<file>[1]

包含额外配置的配置文件。

--compact-node-store[=true|false]

默认情况下，节点存储在复制时不进行压缩，因为这会改变节点 ID。请使用此选项强制执行节点存储压缩。

false

--copy-only-node-properties=<label.property>[,<label.property>…​]

一个逗号分隔的属性键列表，用于包含具有指定标签的节点的副本。任何未明确提及的标签将包含其所有属性。不能与 --skip-properties 或 --skip-node-properties 结合使用。

--copy-only-nodes-with-labels=<label>[,<label>…​]

一个逗号分隔的标签列表。所有具有指定标签中任意一个的节点都将包含在副本中。不能与 --ignore-nodes-with-labels 结合使用。

--copy-only-relationship-properties=<relationship.property>[,<relationship.property>…​]

一个逗号分隔的属性键列表，用于包含具有指定类型的关系的副本。任何未明确提及的关系类型将包含其所有属性。不能与 --skip-properties 或 --skip-relationship-properties 结合使用。

--copy-only-relationships-with-types=<type>[,<type>…​]

一个逗号分隔的关系类型列表。所有具有指定类型中任意一个的关系都将包含在副本中。不能与 --ignore-relationships-with-types 结合使用。

--copy-schema

复制模式而不是生成模式语句，即索引和约束定义。索引将在数据库首次启动时构建。

--expand-commands

允许在配置值评估中进行命令扩展。

--force

即使无法验证数据库的完整性，也强制执行该命令。

--from-pagecache, --max-off-heap-memory=<size>

2025.01 引入 命令可用于页缓存和各种缓存数据结构以提高性能的最大内存。值可以是纯数字（例如 10000000），或者如 20G（代表 20 GB），也可以是 70%（代表机器当前空闲内存的 70%）。

90%

--from-path-data=<path>

数据库目录的路径，其中包含要作为来源的数据库目录。它可用于指向安装目录之外的数据库。

server.directories.data/databases

--from-path-txn=<path>

事务目录的路径，其中包含要作为来源的数据库的事务目录。

server.directories.transaction.logs.root

-h, --help

显示此帮助消息并退出。

--ignore-nodes-with-labels=<label>[,<label>…​]

一个逗号分隔的标签列表。具有指定标签中任意一个的节点将不会包含在副本中。不能与 --copy-only-nodes-with-labels 结合使用。

--ignore-relationships-with-types=<type>[,<type>…​]

一个逗号分隔的关系类型列表。具有指定关系类型中任意一个的关系将不会包含在副本中。不能与 --copy-only-relationships-with-types 结合使用。

--property-shard-count=<propertyShardCount>[2]

2025.12 引入 将要创建的属性数据分片数量，每个分片都将是一个独立的数据库。

0

--skip-labels=<label>[,<label>…​]

一个要忽略的逗号分隔的标签列表。

--skip-node-properties=<label.property>[,<label.property>…​]

一个要为指定标签的节点忽略的逗号分隔属性键列表。不能与 --skip-properties 或 --copy-only-node-properties 结合使用。

--skip-properties=<property>[,<property>…​]

一个要忽略的逗号分隔属性键列表。不能与 --skip-node-properties, --copy-only-node-properties, --skip-relationship-properties 或 --copy-only-relationship-properties 结合使用。

--skip-relationship-properties=<relationship.property>[,<relationship.property>…​]

一个要为指定类型的关系忽略的逗号分隔属性键列表。不能与 --skip-properties 或 --copy-only-relationship-properties 结合使用。

--source-format=<format>

2026.03 引入 源格式可以是普通数据库目录/文件结构 (database) 或备份工件 (backup)。使用 --temp-path 位置来保留任何中间状态。

database

--source-location=<path>

2026.03 引入 源备份工件数据的位置。与 --source-format=backup 一起使用。

--target-format=<format>[2]

2025.12 引入 目标格式可以是普通数据库目录/文件结构 (database) 或备份工件 (backup)。使用 --temp-path 位置来保留任何中间状态。

database

--target-location=<path>[2]

2025.12 引入 目标备份工件数据的位置。与 --target-format=backup 一起使用。

--temp-path=<path>

当源数据库和目标数据库相同时用作暂存区的目录路径。默认为当前目录。

--to-format=<format>

设置新数据库的格式。必须是 same, standard, high_limit, aligned, block 之一。same 表示使用与源相同的格式。

如果从 high_limit 转换为 standard 或 aligned，则不会验证数据是否实际能够容纳。

same

--to-path-data=<path>

数据库目录的路径，其中包含要作为目标进行操作的数据库目录。

server.directories.data/databases

--to-path-schema=<path>

用于创建模式命令文件的目录路径。默认为当前目录。

--to-path-txn=<path>

事务目录的路径，其中包含要作为目标进行操作的数据库的事务目录。

server.directories.transaction.logs.root

--verbose

启用详细输出。
1. 有关详细信息，请参阅 Neo4j Admin 和 Neo4j CLI → 配置。
2. 有关详细信息，请参阅 属性分片 → 重新分片数据库。
企业版

只要未指定 db.format 设置，block 格式即为所有新创建数据库的默认格式。有关 block 格式的更多信息，请参阅 存储格式。

Neo4j 2025.01 引入了一个双重命名选项 --from-pagecache, --max-off-heap-memory=<size>，增强了 --from-pagecache=<size> 选项的功能。

新选项决定了复制过程中可用于读写的最大堆外内存量，而不是指定读取源时分配多少缓存。

有关详细信息，请参阅 提高性能。

请注意，--from-pagecache 选项可能会在未来版本中移除。

示例

以下示例展示了如何使用 neo4j-admin database copy 来复制数据库、在复制过程中过滤数据以及进一步压缩现有数据库。有关如何使用 neo4j-admin database copy 创建属性分片数据库的示例，请参阅 重新分片数据库。

复制数据库的数据存储

您可以使用 neo4j-admin database copy 来复制数据库的数据存储，例如 neo4j。

  1. 停止名为 neo4j 的数据库

    STOP DATABASE neo4j

  2. 将数据存储从 neo4j 复制到一个名为 database-copy 的新数据库。

    如果您不需要数据库的实际副本，则可以使用相同的 <fromDatabase> 和 <toDatabase> 值。该命令将用新创建的副本替换原始数据库。

    您可以使用 --copy-schema 选项自动复制模式。索引将在数据库首次启动时构建。此选项可将任何 4.4 和 5.x 版本的模式复制到 5.26 LTS 及更高版本。

    对于以前的版本，您需要使用保存在 <database-name>-schema.cypher 文件中的 Cypher 语句手动重新创建模式。

    		 
    bin/neo4j-admin database copy neo4j database-copy

  3. 验证数据库是否已成功复制

    ls -al ../data/databases

    复制数据库不会自动创建它。因此，如果您此时执行 SHOW DATABASES，它将不可见。

  4. 创建已复制的数据库。

    CREATE DATABASE database-copy

  5. 验证新数据库是否在线。

    SHOW DATABASES

在复制数据库时过滤数据

您可以使用 neo4j-admin database copy 在复制数据库时过滤掉任何不需要的数据，例如删除节点、标签、属性和关系。

bin/neo4j-admin database copy neo4j copy --ignore-nodes-with-labels="Cat,Dog"

该命令创建了数据库 neo4j 的副本，但不包含带有 :Cat 和 :Dog 标签的节点。

标签是独立处理的，即过滤器会忽略任何带有 :Cat、:Dog 或两者兼有的节点。

有关如何使用 neo4j-admin database copy 过滤数据以进行数据库分片的详细示例，请参阅 使用 copy 命令对数据进行分片。

进一步压缩现有数据库

您可以使用带有参数 -compact-node-store 的 neo4j-admin database copy 命令来进一步压缩现有数据库的存储。
此示例对 <toDatabase> 和 <fromDatabase> 使用相同的值，这意味着该命令将通过创建数据库的新版本来就地压缩数据库。运行命令后，您需要使用生成的脚本重新创建索引。如果数据库属于集群，您还需要从该服务器重新播种集群。有关详细信息，请参阅 指定播种机。

请注意，即使最终只有一个数据库副本，但在操作过程中您仍然需要两倍的空间。

  1. 停止名为 neo4j 的数据库

    STOP DATABASE neo4j

  2. 使用以下命令压缩 neo4j 数据库

    bin/neo4j-admin database copy neo4j neo4j --compact-node-store --temp-path=<my-prefered-staging-area>

    --temp-path 可用于指定用作临时暂存区的不同目录。如果省略，将使用当前工作目录。

    您可以使用 --copy-schema 选项自动复制模式。索引将在数据库首次启动时构建。此选项可将任何 4.4 和 5.x 版本的模式复制到 5.26 LTS 及更高版本。

    对于以前的版本，您需要使用保存在 <database-name>-schema.cypher 文件中的 Cypher 语句手动重新创建模式。

  3. 启动 neo4j 数据库。这是新创建的数据库版本。

    START DATABASE neo4j

有关如何回收未使用空间的详细示例，请参阅 回收未使用的空间。

预估处理时间

基于以下条件，可以预估 neo4j-admin database copy 命令所需的时间：

  • Neo4j 与许多其他数据库一样，以 8K 页的形式执行 IO 操作。

  • 您的磁盘制造商会提供其可处理的最大 IOPS 值。

例如，如果您的磁盘制造商提供的最大值为 5000 IOPS，您可以合理预期每秒最多进行 5000 次此类页操作。因此，该磁盘上您可以预期的最大理论吞吐量为 40MB/s（或 144 GB/小时）。那么您可以假设，在该 5000 IOPS 磁盘上运行 neo4j-admin database copy 的最佳情况是处理 144 GB 数据库至少需要 1 小时。[3]

然而，重要的是要记住，该过程必须从源数据库读取 144 GB，并且还必须写入目标存储（假设目标存储的大小相当）。此外，在复制过程中存在读取/修改/写入存储多次的内部过程。因此，由于额外有 144 GB 的读写操作，在 5000 IOPS 磁盘上运行 neo4j-admin database copy 的最佳情况是处理 144 GB 数据库至少需要 3 小时。

最后，还需要考虑在几乎所有云环境中，公布的 IOPS 值可能与实际值不符，或者可能无法持续维持最大可能的 IOPS。此示例的实际处理时间可能远远超过 3 小时的预估。

提高性能

您可以通过指定内存限制来提高复制过程的性能。Neo4j 2025.01 引入了选项 --from-pagecache, --max-off-heap-memory=<size> 来替换旧的 --from-pagecache=<size> 选项。

新选项控制了复制过程除了 JVM 分配的堆大小之外还可以使用的堆外内存量。值可以是纯数字（例如 10000000），或者如 20G（代表 20 GB）。它也可以指定为可用内存的百分比，例如 70%。

从 2025.01 开始，要配置堆外内存值，您可以使用旧名称 --from-pagecache=<size> 或新名称 --max-off-heap-memory=<size>。

使用 --from-pagecache=<size>
bin/neo4j-admin database copy neo4j copy --from-pagecache=95%
使用 --max-off-heap-memory=<size>
bin/neo4j-admin database copy neo4j copy --max-off-heap-memory=95%
3. 计算基于 MB/s = (IOPS * B) ÷ 10^6，其中 B 是字节为单位的块大小；在 Neo4j 的情况下，这是 8000。然后可以从 (MB/s * 3600) ÷ 1000 计算 GB/小时。