Create composite databases

Composite databases are managed using Cypher® administrative commands. Note that it is not possible to modify access options or database topologies for composite databases as these are inherited from the constituent databases. For information about modifying access options, see Alter database access mode. For information about about topologies for databases, see Create databases in a cluster.

Drivers and client applications connect to composite databases just like standard databases. For more information, see the manuals for the different Neo4j drivers and applications.

Create a composite database

Composite databases can be created using CREATE COMPOSITE DATABASE.

Composite database names are subject to the same rules as standard databases. One difference is however that the deprecated syntax using dots without enclosing the name in backticks is not available. Both dots and dashes need to be enclosed within backticks when using composite databases.

Having dots (.) in the composite database names is not recommended. This is due to the difficulty of determining if a dot is part of the composite database name or a delimiter for a database alias in a composite database.
Query
CREATE COMPOSITE DATABASE inventory

When a composite database has been created, it shows up in the listing provided by the command SHOW DATABASES.

Query
SHOW DATABASES
Result
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| name        | type        | aliases            | access       | address          | role      | writer | requestedStatus | currentStatus | statusMessage | default | home  | constituents       |
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "inventory" | "composite" | []                 | "read-only"  | "localhost:7687" | NULL      | FALSE  | "online"        | "online"      | ""            | FALSE   | FALSE | []                 |
| "library"   | "composite" | []                 | "read-only"  | "localhost:7687" | NULL      | FALSE  | "online"        | "online"      | ""            | FALSE   | FALSE | ["library.sci-fi"] |
| "neo4j"     | "standard"  | []                 | "read-write" | "localhost:7687" | "primary" | TRUE   | "online"        | "online"      | ""            | TRUE    | TRUE  | []                 |
| "sci-fi"    | "standard"  | ["library.sci-fi"] | "read-write" | "localhost:7687" | "primary" | TRUE   | "online"        | "online"      | ""            | FALSE   | FALSE | []                 |
| "system"    | "system"    | []                 | "read-write" | "localhost:7687" | "primary" | TRUE   | "online"        | "online"      | ""            | FALSE   | FALSE | []                 |
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

For a full description of the columns returned by this command, and how to sort the results by specific columns, see List databases.

To create database aliases in the composite database, give the composite database as a namespace for the alias. For information about creating aliases in composite databases, see Managing aliases in composite databases.

Create composite databases with IF NOT EXISTS or OR REPLACE

The CREATE COMPOSITE DATABASE command is optionally idempotent, with the default behavior to fail with an error if the database already exists. There are two ways to circumvent this behavior.

First, appending IF NOT EXISTS to the command ensures that no error is returned and nothing happens should the database already exist.

Query
CREATE COMPOSITE DATABASE inventory IF NOT EXISTS

This will not create a new composite database, because a composite database with the name inventory already exists.

Second, adding OR REPLACE to the command will result in any existing database being deleted and a new one being created.

Query
CREATE OR REPLACE COMPOSITE DATABASE inventory

This is equivalent to running DROP DATABASE inventory IF EXISTS followed by CREATE COMPOSITE DATABASE inventory.

The behavior of IF NOT EXISTS and OR REPLACE apply to both standard and composite databases (e.g. a composite database may replace a standard database or another composite database).

The IF NOT EXISTS and OR REPLACE parts of these commands cannot be used together.

Set a default Cypher version for a composite database

You can set the default Cypher version for a composite database when creating it. If not specified, the default language for the composite database is set to the default language of the DBMS. For example:

Query
CREATE COMPOSITE DATABASE inventory DEFAULT LANGUAGE CYPHER 5

This command creates a composite database named inventory with the default language set to Cypher 5.

To view the default Cypher version of each database in the DBMS, run the command SHOW DATABASES with the YIELD clause and specify the defaultLanguage column. For example:

Query
SHOW DATABASES YIELD name, defaultLanguage
Table 1. Result
name defaultLanguage

"neo4j"

"CYPHER 25"

"library"

"CYPHER 5"

"inventory"

"CYPHER 5"

"sci-fi"

"CYPHER 5"

"system"

"CYPHER 25"

Rows: 5

For more information about other options for configuring the Cypher version, see Configure the Cypher default version.

Setting the default language to CYPHER 5 ensures that all queries run on that database will use the version of Cypher 5 as it existed at the time of the Neo4j 2025.06 release (unless you prepend your queries with CYPHER 25, which overrides this default). Any changes introduced after the 2025.06 release will not affect the semantics of the query.