Copy a database store
Enterprise Edition

You can use the neo4j-admin database copy command to copy a database, create a compacted/defragmented copy of a database, clean up database inconsistencies, or do a direct migration from Neo4j 4.4 to any 5.x version. neo4j-admin database copy reclaims the unused space, creates a defragmented copy of the data store, and creates the node label and relationship type lookup indexes.

Command limitations

neo4j-admin database copy preserves the node IDs (unless --compact-node-store is used), but the relationships get new IDs.
neo4j-admin database copy is not supported for use on the system database.
neo4j-admin database copy is not supported for use on Composite databases. It must be run directly on the databases that are associated with that Composite database.
neo4j-admin database copy is an IOPS-intensive process. For more information, see Estimating the processing time.

Command

neo4j-admin database copy copies the data store of an existing offline database to a new database.

Syntax

neo4j-admin database copy [-h] [--copy-schema] [--expand-commands] [--force] [--verbose] [--compact-node-store
                          [=true|false]] [--compress[=true|false]] [--additional-config=<file>]
                          [--from-pagecache=<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>

Description

This command creates a copy of a database. If your labels, properties, or relationships contain dots or commas, you can use backticks to quote them, e.g. `My,label`, `My.property`. A file named <database-name>-schema.cypher, containing the schema commands needed to recreate indexes/constraints on the copy, will be created.

You can use the --copy-schema option to automatically copy the schema. Indexes will be built the first time the database is started. This option can copy the schema from any 4.4 and 5.x version to 5.26 LTS and later versions.

Parameters

Table 1. `neo4j-admin database copy` parameters
Parameter	Description
`<fromDatabase>`	Name of database to copy from.
`<toDatabase>`	Name of database to copy to.

You can use the same values for <fromDatabase> and <toDatabase> if you do not need an actual copy of the database. In this case, the database is copied to a temporary location (by default the current working directory or the path as defined by --temp-path), before being moved to replace the original.

Options

The neo4j-admin database copy command has the following options:

Option Description Default

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

Configuration file with additional configuration.

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

By default node store is not compacted on copy since that changes node ids. Please use this option to enforce node store compaction.

false

--compress[=true|false]^[2]

Introduced in 2026.04 Request backup artifact to be compressed. Compression can yield a backup artefact many times smaller, but the exact reduction depends upon many factors, including the database format and the kind of data stored. If disabled, the size of the produced artifact will be approximately equal to the size of the backed-up database. The speed of the copy operation is affected by compression, but which is faster depends upon the relative performance of CPU and storage. If copy speed is important, consider evaluating both options - with compression enabled and disabled.

false

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

A comma-separated list of property keys to include in the copy for nodes with the specified label. Any labels not explicitly mentioned will have all their properties included in the copy. Cannot be combined with --skip-properties or --skip-node-properties.

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

A comma-separated list of labels. All nodes that have ANY of the specified labels will be included in the copy. Cannot be combined with --ignore-nodes-with-labels.

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

A comma-separated list of property keys to include in the copy for relationships with the specified type. Any relationship types not explicitly mentioned will have all their properties included in the copy. Cannot be combined with --skip-properties or --skip-relationship-properties.

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

A comma-separated list of relationship types. All relationships with any of the specified types will be included in the copy. Cannot be combined with --ignore-relationships-with-types.

--copy-schema

Copy the schema instead of generating schema statements, meaning index and constraint definitions. The indexes will be built the first time the database is started.

--expand-commands

Allow command expansion in config value evaluation.

--force

Force the command to run even if the integrity of the database cannot be verified.

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

Introduced in 2025.01 Maximum off-heap memory that the command can use for page cache and various caching data structures to improve performance. Use this option to tune the command memory usage; the command does not use the server.memory.pagecache.size configuration setting for this purpose. Values can be plain numbers, such as 10000000, or, for example, 20G for 20 gigabytes, or 70%, which will amount to 70% of currently free memory on the machine.

90%

--from-path-data=<path>

Path to the databases directory, containing the database directory to source from. It can be used to target databases outside of the installation.

server.directories.data/databases

--from-path-txn=<path>

Path to the transactions directory, containing the transaction directory for the database to source from.

server.directories.transaction.logs.root

-h, --help

Show this help message and exit.

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

A comma-separated list of labels. Nodes that have ANY of the specified labels will not be included in the copy. Cannot be combined with --copy-only-nodes-with-labels.

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

A comma-separated list of relationship types. Relationships with any of the specified relationship types will not be included in the copy. Cannot be combined with --copy-only-relationships-with-types.

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

Introduced in 2025.12 Infinigraph Number of shards of property data that will be created, each shard will be its own database.

0

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

A comma-separated list of labels to ignore.

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

A comma-separated list of property keys to ignore for nodes with the specified label. Cannot be combined with --skip-properties or --copy-only-node-properties.

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

A comma-separated list of property keys to ignore. Cannot be combined with --skip-node-properties, --copy-only-node-properties, --skip-relationship-properties or --copy-only-relationship-properties.

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

A comma-separated list of property keys to ignore for relationships with the specified type. Cannot be combined with --skip-properties or --copy-only-relationship-properties.

--source-format=<format>

Introduced in 2026.03 Source format can be either a plain database directory/files structure (database) or a backup artifact (backup). Uses the --temp-path location to keep any intermediate state.

database

--source-location=<path>

Introduced in 2026.03 Location for source backup artifact data. Used together with --source-format=backup.

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

Introduced in 2025.12 Target format can be either a plain database directory/files structure (database) or a backup artifact (backup). Uses the --temp-path location to keep any intermediate state.

database

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

Introduced in 2025.12 Location for target backup artifact data. Used together with --target-format=backup.

--temp-path=<path>

Path to a directory to be used as a staging area when the source and target databases are the same. Default is the current directory.

--to-format=<format>

Set the format for the new database. Must be one of same, standard, high_limit, aligned, block. same will use the same format as the source.

If you go from high_limit to standard or aligned, there is no validation that the data will actually fit.

same

--to-path-data=<path>

Path to the databases directory, containing the database directory to target from.

server.directories.data/databases

--to-path-schema=<path>

Path to directory to create the schema commands file in. Default is the current directory.

--to-path-txn=<path>

Path to the transactions directory containing the transaction directory for the database to target from.

server.directories.transaction.logs.root

--verbose

Enable verbose output.

1. See Neo4j Admin and Neo4j CLI → Configuration for details.

2. For using this option with sharded property databases, see Property Sharding → Data import.

Enterprise Edition

The block format is the default format for all newly created databases as long as they do not have the db.format setting specified. For more information on the block format, see Store formats.

Neo4j 2025.01 introduces a dual-named option --from-pagecache, --max-off-heap-memory=<size>, which enhances the functionality of the --from-pagecache=<size> option.

The new option determines the maximum amount of off-heap memory available during the copy process for reading and writing, instead of specifying how much cache to allocate when reading the source.

For details, see Improving the performance.

Note that the --from-pagecache option may be removed in future versions.

Examples

The following examples show how to use neo4j-admin database copy to copy a database, filter out data while copying a database, and further compact an existing database. For examples of how to use neo4j-admin database copy to create a sharded property database, see Resharding databases.

Copying the data store of a database

You can use neo4j-admin database copy to copy the data store of a database, for example, neo4j.

Stop the database named neo4j:
```
STOP DATABASE neo4j
```

Copy the data store from neo4j to a new database called database-copy.

If you do not need an actual copy of the database, you can use the same values for <fromDatabase> and <toDatabase>. The command replaces the original database with the newly created copy.

You can use the --copy-schema option to automatically copy the schema. Indexes will be built the first time the database is started. This option copies the schema from any 4.4 and 5.x version to 5.26 LTS and later versions.

For previous versions, you need to manually recreate the schema using the Cyher statements saved in the file <database-name>-schema.cypher.

bin/neo4j-admin database copy neo4j database-copy

Verify that the database has been successfully copied:
```
ls -al ../data/databases
```
Copying a database does not automatically create it. Therefore, it will not be visible if you do SHOW DATABASES at this point.
Create the copied database.
```
CREATE DATABASE database-copy
```
Verify that the new database is online.
```
SHOW DATABASES
```

Filtering data while copying a database

You can use neo4j-admin database copy to filter out any unwanted data while copying a database, for example, by removing nodes, labels, properties, and relationships.

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

The command creates a copy of the database neo4j but without the nodes with the labels :Cat and :Dog.

Labels are processed independently, i.e., the filter ignores any node with a label :Cat, :Dog, or both.

For a detailed example of how to use neo4j-admin database copy to filter out data for sharding a database, see Sharding data with the copy command.

Further compacting an existing database

You can use the command neo4j-admin database copy with the argument -compact-node-store to further compact the store of an existing database.
This example uses the same values for <toDatabase> and <fromDatabase>, which means that the command will compact the database in place by creating a new version of the database. After running the command, you need to recreate the indexes using the generated script. If the database belongs to a cluster, you also need to reseed the cluster from that server. For more information, see Designated seeder.

Note that even though there is only one database copy in the end, you still need double the space during the operation.

Stop the database named neo4j:
```
STOP DATABASE neo4j
```

Compact the neo4j database using the command:

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

--temp-path can be used to specify a different directory to use as a temporary staging area. If omitted, the current working directory will be used.

For previous versions, you need to manually recreate the schema using the Cyher statements saved in the file <database-name>-schema.cypher.

Start the neo4j database. This is the newly created version of the database.
```
START DATABASE neo4j
```

For a detailed example of how to reclaim unused space, see Reclaim unused space.

Copy the data store from a backup
Introduced in 2026.03

The following example assumes that you have a backup (created with the neo4j-admin database backup command) of your existing database foo in an AWS S3 bucket.

Before copying the database store from a backup, you do not need to stop or drop the database foo.

You can specify any differential backup in the chain. Then the entire chain up to that point must be located in the same folder as the specified diff. The chain will be found in the folder and all changes in that chain up to the point specified will be part of the result database from the copy operation. If not, the command will fail due to incomplete chain.

--source-location and --source-format cannot be used together with --from-path-data and/or --from-path-txn due to the conflict in trying to supply data from two different locations at once.

The copy command does not copy over users and roles metadata. You have to copy and re-apply them manually.

Copy the data from a backup of your standard database foo into a backup for the database foo-restored.
```
neo4j-admin database copy foo foo-restored --source-location=s3://bucket/folder/foo.backup --source-format=backup --copy-schema --target-location=s3://bucket/folder --target-format=backup
```
Copying a database does not automatically create it. Therefore, it will not be visible if you do SHOW DATABASES at this point.

Run the following command to create the database foo-restored by seeding it from your backup folder in the AWS S3 bucket:

Introduced in 2025.06

CREATE DATABASE foo-restored
OPTIONS {seedUri: “s3://bucket/folder/”};

CREATE DATABASE foo-restored
OPTIONS {existingData: 'use', seedUri: “s3://bucket/folder/”};

Verify that the new database is online by running the following command:
```
SHOW DATABASES;
```
After the new database is online, you can drop the old database foo.

Run the following command to drop the old database foo:
```
DROP DATABASE foo;
```

Estimating the processing time

Estimations for how long the neo4j-admin database copy command takes can be made based on the following:

Neo4j, like many other databases, does IO in 8K pages.
Your disc manufacturer will have a value for the maximum IOPS it can process.

For example, if your disc manufacturer has provided a maximum of 5000 IOPS, you can reasonably expect up to 5000 such page operations a second. Therefore, the maximal theoretical throughput you can expect is 40MB/s (or 144 GB/hour) on that disc. You may then assume that the best-case scenario for running neo4j-admin database copy on that 5000 IOPS disc is that it takes at least 1 hour to process a 144 GB database. ^[3]

However, it is important to remember that the process must read 144 GB from the source database, and must also write to the target store (assuming the target store is of comparable size). Additionally, there are internal processes during the copy that reads/modifies/writes the store multiple times. Therefore, with an additional 144 GB of both read and write, the best-case scenario for running neo4j-admin database copy on a 5000 IOPS disc is that it takes at least 3 hours to process a 144 GB database.

Finally, it is also important to consider that in almost all Cloud environments, the published IOPS value may not be the same as the actual value, or be able to continuously maintain the maximum possible IOPS. The real processing time for this example could be well above that estimation of 3 hours.

Improving the performance

You can improve the performance of the copy process by specifying the memory limit. Neo4j 2025.01 introduces an option --from-pagecache, --max-off-heap-memory=<size> to replace the old --from-pagecache=<size> option.

The new option controls how much off-heap memory the copy process may use in addition to the heap size the JVM is given. Values can be plain numbers, such as 10000000, or 20G for 20 gigabytes. It can also be specified as a percentage of the available memory, for example 70%.

Starting from 2025.01, to configure the off-heap memory value, you can use either the old name --from-pagecache=<size> or the new one --max-off-heap-memory=<size>.

Using --from-pagecache=<size>

bin/neo4j-admin database copy neo4j copy --from-pagecache=95%

Using --max-off-heap-memory=<size>

bin/neo4j-admin database copy neo4j copy --max-off-heap-memory=95%

Glossary

allocator: A component in the cluster that allocates databases to servers according to the topology constraints specified and an allocation strategy.
asynchronous replication: Asynchronous replication is used by secondary copies to poll for new transactions, which means they cannot be guaranteed to have received the most recent transactions. This enables efficient scale-out of read-performance.
Aura instance: A fully-managed DBMS represented by a single instance ID, that is running in the Neo4j Aura cloud.
auto-commit transaction: An automatically committed transaction that contains a single query.
Bolt protocol: Bolt is a protocol used for interaction between Neo4j instances and drivers.
bookmark: A marker the client can request from the cluster to ensure that it is able to read its own writes so that the application’s state is consistent and only databases that have a copy of the bookmark are permitted to respond.
category (Bloom): A category is based on a node label and is defined in a Perspective as a way of visually distinguishing nodes with the same label(s).
causal consistency: All servers in a cluster agree on the order in which transactions take place. The position of a server on the causal chain can be guaranteed using a bookmark.
cluster: A Neo4j DBMS that spans multiple servers working together to increase fault tolerance and/or read scalability. Databases on a cluster may be configured to replicate across servers in the cluster thus achieving read scalability or high availability.
client application: Software that interacts with a Neo4j server.
commit: A commit is the successful completion of a transaction, which ensures durability of any changes made. For more details, visit Operations Manual → Transaction management.
composite database: Composite databases are the means to access partitioned graph data with a single Cypher query.
constraint: Constraints are sets of data modeling rules that ensure the data is consistent and reliable.
Cypher®: Neo4j’s graph query language.
data model: A data model defines how information is organized in a database. A good data model will make querying and understanding your data easier. In Neo4j, the data models have a graph structure.
database: A database is a container used by the DBMS to manage and store graph data. The physical structure of data is controlled by the database.
database vs graph: Databases are the physical containers of graph data. Graphs are the logical structure of data in Neo4j.
Database Management System: Database Management System, or DBMS, capable of managing multiple databases. A DBMS may run on a single server, or span several servers configured as a cluster.
database schema: The prescribed property existence and datatypes for nodes and relationships.
deallocate: An act of removing a database from a server or a server from a cluster without loss of data or reduced fault tolerance.
degree (of a node): The number of relationships of a specific node; loops are counted twice.
disaster recovery: A manual intervention to restore availability of a cluster, or databases within a cluster.
driver: A software library that provides access to Neo4j from a particular programming language.
election: In the event that the Raft leader becomes unresponsive, followers automatically trigger an election and vote for a new leader.
entity: A node or a relationship.
expression (Cypher): A component of a Cypher query which produces values. It may be used in projections, as a predicate, or when setting properties on graph elements.
fabric: Fabric is the architectural design of a unified system that provides a single access point to local or distributed graph data.
fault tolerance: A guarantee that a cluster can maintain a database’s persistence and availability in the event of one or more servers failing.
follower: A primary copy of a database acting as a follower, receives and acknowledges synchronous writes from the leader.
Generative AI (GenAI): A type of artificial intelligence (AI) system that generates text, images, or other media in response to prompts.
graph: A logical representation of a set of nodes where some pairs are connected by relationships.
index: Data structure that improves read performance of a database.
knowledge graph: A specific type of graph that has an organizing principle so that a user (or a computer system) can reason about the underlying data. The organizing principle provides an additional layer of structure that adds context to support knowledge discovery.
label: Marks a node as a member of a named and indexed subset. A node may be assigned zero or more labels.
leader: A single primary copy of a database is designated as the leader. It receives all write transactions from clients and replicates writes synchronously to followers and asynchronously to secondary copies of the database.
main database: In terms of Neo4j Enterprise Studio, the database(s) containing the user’s data. Can exist in the same Neo4j deployment as the tool asset database.
motif: A description of a specific pattern within a graph.
node: A node represents an entity or discrete object in your graph data model. Nodes can be connected by relationships, hold data in properties, and are classified by labels.
operator: A symbol representing a mathematical or logical operation.
parameter: Named value provided when running a Cypher statement.
path: A sequence of nodes and the relationships connecting them, that does not contain duplicate relationships. Several paths can match a pattern.
pattern: A specific arrangement of nodes and relationships that can be matched in a graph. A pattern follows a motif.
perspective (Bloom): A Perspective defines a certain business view or domain that can be found in the target Neo4j graph. A single Neo4j graph can be viewed through different Perspectives, each tailored for a different business purpose.
primary: A copy of the database that is able to process write transactions and is eligible to be elected as a leader. It participates in fault tolerant writes as it is part of the majority required to acknowledge and commit write transactions.
primary vs secondary: In a cluster, databases can operate in either primary or secondary mode. Primary databases are able to process write and read transactions, ensuring fault tolerance. Secondary databases are replicated asynchronously from primaries, and their main purpose is to provide read scaling within the cluster.
project (Aura): An isolated environment in the unified Aura console that contains its own database instances, configurations, and resources. Preceded by tenant in the classic Aura console.
property: Properties are key-value pairs that are used for storing data on nodes and relationships.
query (Cypher): A statement that retrieves or writes information to a database.
Raft group: A group of servers that are participating in hosting a particular database in primary mode.
Raft group member: A server that is participating in a Raft group. A server can be a member of one or more groups.
Raft log: A shared log between all Raft group members that is guaranteed to be consistently updated and viewed by those members. The log contains both database data and operational state of the Raft group.
Raft protocol: The networking mechanism that enables a database to replicate its data across multiple servers to give high availability for accessing the data and high durability to the data stored.
read scaling: Distributing query load by creating additional database copies hosted in secondary mode (read-only).
relationship: A relationship represents a connection between nodes in your graph data model. Relationships connect a source node to a target node, hold data in properties, and are classified by type.
secondary: An asynchronously replicated copy of the database that provides read scaling within the cluster.
seed: A seed is a database dump or a full backup used to create a database on a cluster. This is sometimes called seeding.
server: A physical machine, a virtual machine, or a container running an instance of Neo4j. Servers can be standalone or part of a cluster.
session: A causally linked sequence of transactions.
session consistency: An alternative name for Neo4j’s causal consistency.
standalone: A single server running Neo4j and not part of a cluster.
synchronous replication: Synchronous replication requires the leader primary to replicate a transaction and block the commit until a quorum of the follower primaries acknowledges that the transaction is successfully replicated. Once the transaction is replicated, the commit is allowed to proceed. This ensures data durability and consistency within the cluster.
system database: A database used by Neo4j to store system information.
tenant (Aura): An isolated environment in the classic Aura console that contains its own database instances, configurations, and resources. Replaced by project in the unified Aura console.
tool asset database: In terms of Neo4j Enterprise Studio, the database where tools' assets are stored. This can be in the same Neo4j deployment as the main database(s) or in a separate deployment.
topology: A configuration that describes how the copies of a database should be spread across the servers in a cluster, see primary mode and secondary mode.
transaction: A transaction comprises a unit of work performed against a database. It is treated in a coherent and reliable way, independent of other transactions. Transactions comply with the ACID consistency model (atomic, consistent, isolated, and durable).

3. The calculations are based on MB/s = (IOPS * B) ÷ 10^6, where B is the block size in bytes; in the case of Neo4j, this is 8000. GB/hour can then be calculated from (MB/s * 3600) ÷ 1000.

Copy a database storeEnterprise Edition

Command

Syntax

Description

Parameters

Options

Examples

Copying the data store of a database

Filtering data while copying a database

Further compacting an existing database

Copy the data store from a backupIntroduced in 2026.03

Estimating the processing time

Improving the performance

Glossary

Copy a database store
Enterprise Edition

Copy the data store from a backup
Introduced in 2026.03