Managing 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.

Listing composite databases

The type column returned by the SHOW DATABASES command will display which databases are composite databases.

Query
SHOW DATABASES
Result
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| name      | type        | aliases            | access       | address          | role      | writer | requestedStatus | currentStatus | statusMessage | default | home  | constituents       |
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "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 description of all the returned column of this command, ways in which the SHOW DATABASE command can be filtered, and details about the privileges required for the command, see listing standard databases.

For composite databases, the constituents column is particularly interesting as it lists the aliases that make up the composite database.

Query
SHOW DATABASE library YIELD name, constituents
Result
+--------------------------------+
| name      | constituents       |
+--------------------------------+
| "library" | ["library.sci-fi"] |
+--------------------------------+

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 Managing 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.

Use IF NOT EXISTS or OR REPLACE when creating composite databases

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.

Stop composite databases

Databases can be stopped using the command STOP DATABASE.

Query
STOP DATABASE inventory

Both standard databases and composite databases can be stopped using this command.

The status of the stopped database can be seen using the command SHOW DATABASE name.

Query
SHOW DATABASE inventory YIELD name, requestedStatus, currentStatus
Result
+-----------------------------------------------+
| name        | requestedStatus | currentStatus |
+-----------------------------------------------+
| "inventory" | "offline"       | "offline"     |
+-----------------------------------------------+

Start composite databases

Databases can be started using the command START DATABASE.

Query
START DATABASE inventory

Both standard databases and composite databases can be started using this command.

The status of the started database can be seen using the command SHOW DATABASE name.

Query
SHOW DATABASE inventory YIELD name, requestedStatus, currentStatus
Result
+-----------------------------------------------+
| name        | requestedStatus | currentStatus |
+-----------------------------------------------+
| "inventory" | "online"        | "online"      |
+-----------------------------------------------+

Delete composite databases

Composite databases can be deleted using the command DROP COMPOSITE DATABASE name. This command will fail if the targeted database is not a composite database.

Query
DROP COMPOSITE DATABASE inventory

It is also possible to use the shorter command DROP DATABASE name for composite databases, but this command will drop any database and not fail in case the targeted database is not a composite database.

Drivers and applications

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.