List databases
You can list your databases using the Cypher command SHOW DATABASES
.
Syntax
Command | Syntax |
---|---|
|
|
SHOW DATABASES
output
Depending on what you want to see, you can list:
-
All databases.
-
A particular database.
-
The default database.
-
The home database.
These commands return the following columns:
Column | Description | Type |
---|---|---|
|
The name of the database. Default Output |
|
|
The type of the database: |
|
|
The names of any aliases the database may have. Default Output |
|
|
The database access mode, either |
|
|
The database unique ID. A database must be |
|
|
The server instance ID. |
|
|
Instance address in a clustered DBMS.
The default for a standalone database is |
|
|
The current role of the database ( |
|
|
|
|
|
The expected status of the database.
The value can be either |
|
|
The actual status of the database. Default Output The possible statuses are:
See Database states for more information. |
|
|
A message explaining the status of the database, often explaining why it is not in the correct state. Default Output |
|
|
Show if this is the default database for the DBMS. Default Output
Not returned by |
|
|
Shown if this is the home database for the current user. Default Output
Not returned by |
|
|
Number of primaries for this database reported as running currently.
It is the same as the number of rows where |
|
|
Number of secondaries for this database reported as running currently.
It is the same as the number of rows where |
|
|
The requested number of primaries for this database. May be lower than current if the DBMS is currently reducing the number of copies of the database, or higher if it is currently increasing the number of copies. |
|
|
The requested number of secondaries for this database. May be lower than current if the DBMS is currently reducing the number of copies of the database, or higher if it is currently increasing the number of copies. |
|
|
The date and time at which the database was created. |
|
|
The date and time at which the database was last started. |
|
|
The date and time at which the database was last stopped. |
|
|
Information about the storage engine and the store format. The value is a string formatted as:
A database must be |
|
|
The ID of the last transaction received. A database must be |
|
|
Number of transactions the current database is behind compared to the database on the primary instance.
The lag is expressed in negative integers. In standalone environments, the value is always A database must be |
|
|
The names of any constituents the database may have. Applicable only for composite databases. Default Output |
|
|
The map of options applied to the database. |
|
The results of the SHOW DATABASES
command are filtered according to the ACCESS
privileges of the user.
However, some privileges enable users to see additional databases regardless of their ACCESS
privileges:
-
Users with
CREATE/DROP/ALTER DATABASE
orSET DATABASE ACCESS
privileges can see all standard databases. -
Users with
CREATE/DROP COMPOSITE DATABASE
orCOMPOSITE DATABASE MANAGEMENT
privileges can see all composite databases. -
Users with
DATABASE MANAGEMENT
privilege can see all databases.
If a user has not been granted ACCESS
privilege to any databases nor any of the above special cases, the command can still be executed but it will only return the system
database, which is always visible.
Database states
A database’s currentStatus
can be one of the following:
State | Description |
---|---|
|
The database is running. |
|
The database is not running.
If the |
|
The database is not running, but is about to. |
|
The database is not running anymore, but still has not stopped completely.
No offline operations (e.g. |
|
The database is currently being updated from another instance of Neo4j. |
|
The database has not yet been created. |
|
Only applies to databases in a cluster.
The database is still online but will eventually be offline due to a transfer of its role in the cluster to a different member.
The status is |
|
This state implies an error has occurred.
The database’s underlying store files may be invalid.
For more information, consult the |
|
The database is effectively stopped and its state may not be changed until no longer quarantined.
For more information, consult the |
|
This instance of Neo4j does not know the state of this database. |
Note that for failed databases, the |
Show all available databases
A summary of all available databases can be displayed using the command SHOW DATABASES
.
SHOW DATABASES
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | name | type | aliases | access | address | role | writer | requestedStatus | currentStatus | statusMessage | default | home | constituents | +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | "movies" | "standard" | ["films", "motion pictures"] | "read-write" | "localhost:7687" | "primary" | TRUE | "online" | "online" | "" | FALSE | FALSE | [] | | "neo4j" | "standard" | [] | "read-write" | "localhost:7687" | "primary" | TRUE | "online" | "online" | "" | TRUE | TRUE | [] | | "system" | "system" | [] | "read-write" | "localhost:7687" | "primary" | TRUE | "online" | "online" | "" | FALSE | FALSE | [] | +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
As of Neo4j 5.3, databases hosted on servers that are offline are also returned by the |
Show detailed information for a particular database
In this example, the detailed information for a particular database can be displayed using the command SHOW DATABASE name YIELD *
.
When a YIELD
clause is provided, the full set of columns is returned.
SHOW DATABASE movies YIELD *
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | name | type | aliases | access | databaseID | serverID | address | role | writer | requestedStatus | currentStatus | statusMessage | default | home | currentPrimariesCount | currentSecondariesCount | requestedPrimariesCount | requestedSecondariesCount | creationTime | lastStartTime | lastStopTime | store | lastCommittedTxn | replicationLag | constituents | options | +----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | "movies" | "standard" | ["films", "motion pictures"] | "read-write" | "C066801F54B44EA1520F0FE392B4005AABF42D8DD0A5FD09969B955575D287D5" | "e3063985-e2f4-4728-824b-a7d53779667a" | "localhost:7687" | "primary" | TRUE | "online" | "online" | "" | FALSE | FALSE | 1 | 0 | 1 | 0 | 2023-08-14T10:01:29.074Z | 2023-08-14T10:01:29.074Z | NULL | "record-aligned-1.1" | 3 | 0 | [] | {} | +----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Show the number of databases
The number of distinct databases can be seen using YIELD
and a count()
function in the RETURN
clause.
SHOW DATABASES YIELD name
RETURN count(DISTINCT name) AS count
+-------+ | count | +-------+ | 3 | +-------+
By specifying the name
column and sorting the results by distinct name, only the number of distinct databases are counted, not the number of allocations of databases in a clustered environment.
Show the default database
The default database can be seen using the command SHOW DEFAULT DATABASE
.
SHOW DEFAULT DATABASE
+--------------------------------------------------------------------------------------------------------------------------------------------------------+ | name | type | aliases | access | address | role | writer | requestedStatus | currentStatus | statusMessage | constituents | +--------------------------------------------------------------------------------------------------------------------------------------------------------+ | "neo4j" | "standard" | [] | "read-write" | "localhost:7687" | "primary" | TRUE | "online" | "online" | "" | [] | +--------------------------------------------------------------------------------------------------------------------------------------------------------+
Show the home database
The home database for the current user can be seen using the command SHOW HOME DATABASE
.
SHOW HOME DATABASE
+--------------------------------------------------------------------------------------------------------------------------------------------------------+ | name | type | aliases | access | address | role | writer | requestedStatus | currentStatus | statusMessage | constituents | +--------------------------------------------------------------------------------------------------------------------------------------------------------+ | "neo4j" | "standard" | [] | "read-write" | "localhost:7687" | "primary" | TRUE | "online" | "online" | "" | [] | +--------------------------------------------------------------------------------------------------------------------------------------------------------+
Filter the listed databases
It is also possible to filter and sort the results by using YIELD
, ORDER BY
, and WHERE
.
SHOW DATABASES YIELD name, currentStatus, requestedStatus
ORDER BY currentStatus
WHERE name CONTAINS 'o'
In this example:
-
The number of columns returned has been reduced with the
YIELD
clause. -
The order of the returned columns has been changed.
-
The results are ordered by the
currentStatus
column usingORDER BY
. -
The results have been filtered to only show database names containing
'o'
.
It is also possible to use SKIP
and LIMIT
to paginate the results.
+--------------------------------------------+ | name | currentStatus | requestedStatus | +--------------------------------------------+ | "movies" | "online" | "online" | | "neo4j" | "online" | "online" | +--------------------------------------------+