Managing database aliases for standard databases

Database aliases can be created and managed using a set of Cypher administration commands executed against the system database. The required privileges are described in the The DBMS ALIAS MANAGEMENT privileges. When connected to the DBMS over Bolt, administration commands are automatically routed to the system database.

If a transaction modifies a database alias, other transactions concurrently executing against that alias may be aborted and rolled back for safety. This prevents issues such as a transaction executing against multiple target databases for the same alias.

There are two kinds of database aliases - local and remote:

Local database aliases

A local database alias can only target a database within the same DBMS. It can be used in all Cypher commands in place of the target database. Please note that the local database alias will be resolved while executing the command. Privileges are defined on the target database, and not the local database alias.

Remote database aliases

A remote database alias may target a database from another Neo4j DBMS. It can be used for:

  • Connecting to a database of a remote Neo4j DBMS.
    Remote database aliases require configuration to safely connect to the remote target, which is described in Connecting remote databases. It is not possible to impersonate a user on the remote database or to execute an administration command on the remote database via a remote database alias.

  • USE clauses.

  • Defining the access privileges to the remote database.

  • Introduced in 2025.06 Setting a default Cypher version for queries to the remote database.

Starting with Neo4j 2025.06, a database or remote alias can be assigned a default Cypher version. However, local database aliases cannot be assigned a default Cypher version. They always get the Cypher version of their target database.

When a query is run against a database alias, it will be redirected to the target database. The home database for users can be set to an alias, which will be resolved to the target database on use. Starting with Neo4j 2025.04, a database alias can also be set as the DBMS default database.

This page describes managing database aliases for standard databases. For aliases created as part of a composite database, see Managing database aliases in composite databases.

List database aliases

You can list all available database aliases using the SHOW ALIASES FOR DATABASE command. The command returns a table of all database aliases, whether they belong to a composite database or not.
If you need more details, you can append the command with YIELD *. The YIELD * clause returns the full set of columns. The required privileges are described in the The DBMS ALIAS MANAGEMENT privileges.

Table 1. Available columns
Column Description Type

name

The fully qualified name of the database alias. Default Output

STRING

composite

The name of the composite database this alias belongs to, or null if the alias does not belong to a composite database. Default Output

STRING

database

The name of the target database. Default Output

This column is 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 the CREATE DATABASE, DROP DATABASE, ALTER DATABASE, or SET DATABASE ACCESS privileges can see all standard databases.

  • Users with the CREATE COMPOSITE DATABASE, DROP COMPOSITE DATABASE, or COMPOSITE DATABASE MANAGEMENT privileges can see all composite databases.

  • Users with the DATABASE MANAGEMENT privilege can see all databases.

  • Users can always see the system database.

If a user has not been granted the ACCESS privilege to the target database and none of the above special cases apply, then it is not visible to the user and this column will be null.

STRING

location

The location of the database, either local or remote. Default Output

STRING

url

Target location or null if the target is local. Default Output

STRING

user

User connecting to the remote database or null if the target database is local. Default Output

STRING

driver

The driver options for connection to the remote database or null if the target database is local. List of driver settings allowed for remote database aliases.

MAP

defaultLanguage Introduced in 2025.06

The default language for non-constituent remote database aliases or null if it is a constituent or local database alias.

STRING

properties

Any properties set on the database alias.

MAP

Show all database aliases

To list all database aliases, use the SHOW ALIASES FOR DATABASE command without any additional parameters. This command returns all database aliases, including local and remote aliases, for all databases in the DBMS.

Query
SHOW ALIASES FOR DATABASE
Result
+--------------------------------------------------------------------------------------------+
| name              | composite | database  | location | url                       | user    |
+--------------------------------------------------------------------------------------------+
| "films"           | NULL      | "movies"  | "local"  | NULL                      | NULL    |
| "motion pictures" | NULL      | "movies"  | "local"  | NULL                      | NULL    |
| "movie scripts"   | NULL      | "scripts" | "remote" | "neo4j+s://location:7687" | "alice" |
+--------------------------------------------------------------------------------------------+

Show a specific database alias

To list just one database alias, the SHOW ALIASES command takes an alias name:

Query
SHOW ALIAS films FOR DATABASES
Result
+---------------------------------------------------------+
| name    | composite | database | location | url  | user |
+---------------------------------------------------------+
| "films" | NULL      | "movies" | "local"  | NULL | NULL |
+---------------------------------------------------------+

Show detailed information about all database aliases

To see all columns for all database aliases, use the YIELD * clause with the SHOW ALIASES FOR DATABASE command:

Query
SHOW ALIASES FOR DATABASE YIELD *
Result
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| name              | composite | database  | location | url                       | user    | driver                                                                                                                                                                                                         | defaultLanguage | properties                |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "films"           | NULL      | "movies"  | "local"  | NULL                      | NULL    | NULL                                                                                                                                                                                                           | NULL            | {}                        |
| "motion pictures" | NULL      | "movies"  | "local"  | NULL                      | NULL    | NULL                                                                                                                                                                                                           | NULL            | {namecontainsspace: TRUE} |
| "movie scripts"   | NULL      | "scripts" | "remote" | "neo4j+s://location:7687" | "alice" | {connection_pool_idle_test: PT2M, connection_pool_max_size: 10, logging_level: "INFO", ssl_enforced: TRUE, connection_pool_acquisition_timeout: PT1M, connection_timeout: PT5S, connection_max_lifetime: PT1H} | "CYPHER 25"     | {}                        |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Show the number of database aliases

To see the number of database aliases, use a count() aggregation with YIELD and RETURN.

Query
SHOW ALIASES FOR DATABASE YIELD *
RETURN count(*) as count
Result
+-------+
| count |
+-------+
| 3     |
+-------+

Filter and sort database aliases

You can filter and sort the results of the SHOW ALIASES FOR DATABASE command using the YIELD, ORDER BY, and WHERE clauses. The YIELD clause allows you to specify which columns to return, while the ORDER BY clause sorts the results based on a specified column. The WHERE clause filters the results based on a condition.

Query
SHOW ALIASES FOR DATABASE YIELD name, url, database
ORDER BY database
WHERE name CONTAINS 'e'

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 database column using ORDER BY.

  • The results have been filtered to only show database alias names containing 'e'.

It is also possible to use SKIP and LIMIT to paginate the results.

Result
+-----------------------------------------------------------+
| name              | url                       | database  |
+-----------------------------------------------------------+
| "motion pictures" | NULL                      | "movies"  |
| "movie scripts"   | "neo4j+s://location:7687" | "scripts" |
+-----------------------------------------------------------+

Create database aliases

You can create both local and remote database aliases using the command CREATE ALIAS. For more information on local and remote database aliases as part of a composite database, see Create database aliases in composite databases.

The required privileges are described in the The DBMS ALIAS MANAGEMENT privileges.

Database alias names are subject to the rules specified in the Alias names section.

Create database aliases for local databases

A local database alias targets a database within the same DBMS.

Query
CREATE ALIAS `northwind` FOR DATABASE `northwind-graph-2021`

When you create a local database alias, it shows up in the aliases column provided by the command SHOW DATABASES and in the SHOW ALIASES FOR DATABASE command.

Query
SHOW DATABASE `northwind`
Result
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| name                   | type       | aliases       | access       | address          | role      | writer | requestedStatus | currentStatus | statusMessage | default | home  | constituents |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "northwind-graph-2021" | "standard" | ["northwind"] | "read-write" | "localhost:7687" | "primary" | TRUE   | "online"        | "online"      | ""            | FALSE   | FALSE | []           |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Query
SHOW ALIAS `northwind` FOR DATABASE
Result
+---------------------------------------------------------------------------+
| name        | composite | database               | location | url  | user |
+---------------------------------------------------------------------------+
| "northwind" | NULL      | "northwind-graph-2021" | "local"  | NULL | NULL |
+---------------------------------------------------------------------------+

Use IF EXISTS or OR REPLACE when creating database aliases

The CREATE ALIAS command is optionally idempotent, with the default behavior to fail with an error if the database alias already exists. To work around this, you can append IF EXISTS or OR REPLACE to the command. Both check for any remote or local database aliases.

  • Appending IF NOT EXISTS to the command. This ensures that no error is returned and nothing happens should the database alias already exist.

    Query
    CREATE ALIAS `northwind` IF NOT EXISTS  FOR DATABASE `northwind-graph-2021`

  • Appending OR REPLACE to the command. This means that if the database alias already exists, it will be replaced with the new one.

    Query
    CREATE OR REPLACE ALIAS `northwind` FOR DATABASE `northwind-graph-2021`

    This is equivalent to running DROP ALIAS `northwind` IF EXISTS FOR DATABASE followed by CREATE ALIAS `northwind` FOR DATABASE `northwind-graph-2021`.

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

Set properties for local database aliases

You can set properties for local database aliases using the PROPERTIES clause of the CREATE ALIAS command. These properties can later be used in queries with the graph.propertiesByName() function. For example:

Query
CREATE ALIAS `northwind-2022`
FOR DATABASE `northwind-graph-2022`
PROPERTIES { newestNorthwind: true, index: 3 }

To verify that the properties have been set, use the SHOW ALIASES FOR DATABASE command with the YIELD clause:

Query
SHOW ALIAS `northwind-2022` FOR DATABASE YIELD name, properties
Result
+------------------------------------------------------+
| name             | properties                        |
+------------------------------------------------------+
| "northwind-2022" | {index: 3, newestnorthwind: TRUE} |
+------------------------------------------------------+

Create database aliases for remote databases

A database alias can target a remote database by providing an URL and the credentials of a user on the remote Neo4j DBMS. See Configuring remote database aliases for the necessary configurations.

Since remote database aliases target databases that are not in this DBMS, they do not fetch the default Cypher version from their target like the local database aliases. Instead, they are assigned the version given by db.query.default_language, which is set in the neo4j.conf file. Alternatively, you can specify the version in the CREATE ALIAS or ALTER ALIAS commands. See Set a default Cypher version for remote database aliases and Alter the default Cypher version of a remote database alias for more information.

Query
CREATE ALIAS `remote-northwind` FOR DATABASE `northwind-graph-2020`
AT "neo4j+s://location:7687"
USER alice
PASSWORD 'example_secret'

To view the remote database alias details, use the SHOW ALIASES FOR DATABASE command:

Query
SHOW ALIAS `remote-northwind`
FOR DATABASE
Result
+----------------------------------------------------------------------------------------------------------+
| name               | composite | database               | location | url                       | user    |
+----------------------------------------------------------------------------------------------------------+
| "remote-northwind" | NULL      | "northwind-graph-2020" | "remote" | "neo4j+s://location:7687" | "alice" |
+----------------------------------------------------------------------------------------------------------+

You can also use IF EXISTS or OR REPLACE when creating remote database aliases. It works the same way as described in the Use IF EXISTS or OR REPLACE when creating database aliases section. Both check for any remote or local database aliases.

Create remote database aliases with driver settings

It is possible to override the default driver settings per database alias, which are used for connecting to the remote database.

This is the list of the allowed driver settings for remote database aliases:

You can set these driver settings when creating a remote database alias using the DRIVER clause of the CREATE ALIAS or ALTER ALIAS commands. For example, the following query creates a remote database alias using driver settings connection_timeout and connection_pool_max_size for connecting to the remote database northwind-graph-2020:

Query
CREATE ALIAS `remote-with-driver-settings` FOR DATABASE `northwind-graph-2020`
AT "neo4j+s://location:7687"
USER alice
PASSWORD 'example_secret'
DRIVER {
  connection_timeout: duration({minutes: 1}),
  connection_pool_max_size: 10
}

To view the remote database alias details, including the driver settings, use the SHOW ALIASES FOR DATABASE command with the YIELD * clause:

Query
SHOW ALIAS `remote-with-driver-settings` FOR DATABASE YIELD *
Result
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| name                          | composite | database               | location | url                       | user    | driver                                                   | properties |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "remote-with-driver-settings" | NULL      | "northwind-graph-2020" | "remote" | "neo4j+s://location:7687" | "alice" | {connection_pool_max_size: 10, connection_timeout: PT1M} | {}         |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Set a default Cypher version for remote database aliases

You can set a default Cypher version for remote database aliases using the DEFAULT LANGUAGE clause of the CREATE ALIAS or ALTER ALIAS commands. For example, the following query creates a remote database alias with the default language CYPHER 25:

Query
CREATE ALIAS `remote-with-default-language`
FOR DATABASE `northwind-graph-2020`
  AT "neo4j+s://location:7687"
  USER alice
  PASSWORD 'example_secret'
  DEFAULT LANGUAGE CYPHER 25

To view the remote database alias details, including the default language, use the SHOW ALIASES FOR DATABASE command with the YIELD clause:

Query
SHOW ALIAS `remote-with-default-language` FOR DATABASE YIELD name, defaultLanguage
Result
+--------------------------------------------------+
| name                           | defaultLanguage |
+--------------------------------------------------+
| "remote-with-default-language" | "CYPHER 25"     |
+--------------------------------------------------+

Setting the default language to CYPHER 25 ensures that all queries run on that database will use the version of Cypher 25 that the database is currently running (unless you prepend your queries with CYPHER 5, which overrides this default). For example, a Neo4j 2025.08 database with default language Cypher 25 will use Cypher 25 as it exists in Neo4j 2025.08, including any changes introduced in Neo4j 2025.06, 2025.07, and 2025.08.

Set properties for remote database aliases

You can set properties for remote database aliases using the PROPERTIES clause of the CREATE ALIAS command. These properties can then be used in queries with the graph.propertiesByName() function.

Query
CREATE ALIAS `remote-northwind-2021` FOR DATABASE `northwind-graph-2021` AT 'neo4j+s://location:7687'
USER alice PASSWORD 'password'
PROPERTIES { newestNorthwind: false, index: 6 }

To view the remote database alias properties, use the SHOW ALIASES FOR DATABASE command with the YIELD clause:

Query
SHOW ALIAS `remote-northwind-2021` FOR DATABASE YIELD name, properties
Result
+--------------------------------------------------------------+
| name                    | properties                         |
+--------------------------------------------------------------+
| "remote-northwind-2021" | {index: 6, newestnorthwind: FALSE} |
+--------------------------------------------------------------+

Alter database aliases

You can alter both local and remote database aliases using the ALTER ALIAS command. For all aliases, the command allows you to change the target database and properties of the database alias. For remote aliases, the command also allows you to change the URL, user credentials, default language, or driver settings of the database alias. The required privileges are described in the The DBMS ALIAS MANAGEMENT privileges. Only the clauses used will be altered.

Local database aliases cannot be altered to remote aliases, or vice versa.

Alter a local database alias target

You can alter a local database alias to target a different database using the SET DATABASE TARGET clause of the ALTER ALIAS command. For example:

Query
ALTER ALIAS `northwind`
SET DATABASE TARGET `northwind-graph-2021`

To verify that the local database alias has a new target database, you can use the SHOW DATABASE command. It shows up in the aliases column for the target database. .Query

SHOW DATABASE `northwind-graph-2021`
Result
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| name                   | type       | aliases       | access       | address          | role      | writer | requestedStatus | currentStatus | statusMessage | default | home  | constituents |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "northwind-graph-2021" | "standard" | ["northwind"] | "read-write" | "localhost:7687" | "primary" | TRUE   | "online"        | "online"      | ""            | FALSE   | FALSE | []           |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Alter a remote database alias target

You can alter a remote database alias to target a different remote database using the SET DATABASE TARGET clause of the ALTER ALIAS command. For example:

Query
ALTER ALIAS `remote-northwind`
SET DATABASE TARGET `northwind-graph-2020` AT "neo4j+s://other-location:7687"

Alter a remote database alias credentials and driver settings

You can change the user credentials and driver settings of a remote database alias using the USER, PASSWORD, and DRIVER subclauses of the SET DATABASE clause of the ALTER ALIAS command. For example:

Query
ALTER ALIAS `remote-with-driver-settings`
SET DATABASE
  USER bob
  PASSWORD 'new_example_secret'
  DRIVER {
    connection_timeout: duration({ minutes: 1}),
    logging_level: 'debug'
  }

All driver settings are replaced by the new ones. In this case, by not repeating the driver setting connection_pool_max_size, the value will be deleted and fall back to the default value.

Remove all custom driver settings from a remote database alias

You can remove all custom driver settings from a remote database alias by setting the DRIVER clause to an empty map {}.

Query
ALTER ALIAS `movie scripts` SET DATABASE
DRIVER {}

Alter the default Cypher version of a remote database alias

You can alter the default Cypher version of a remote database alias using the SET DATABASE DEFAULT LANGUAGE clause of the ALTER ALIAS command. For example:

Query
ALTER ALIAS `remote-with-default-language`
SET DATABASE DEFAULT LANGUAGE CYPHER 5

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.

Alter properties of local and remote database aliases

You can alter the properties of a local or remote database alias using the SET DATABASE PROPERTIES clause of the ALTER ALIAS command. For example:

Query
ALTER ALIAS `motion pictures` SET DATABASE PROPERTIES { nameContainsSpace: true, moreInfo: 'no, not really' }
Query
ALTER ALIAS `movie scripts` SET DATABASE PROPERTIES { nameContainsSpace: true }

The updated properties can then be used in queries with the graph.propertiesByName() function.

Use IF EXISTS when altering database aliases

The ALTER ALIAS command is optionally idempotent, with the default behavior to fail with an error if the database alias does not exist. Appending IF EXISTS to the command ensures that no error is returned and nothing happens should the alias not exist.

Query
ALTER ALIAS `no-alias` IF EXISTS SET DATABASE TARGET `northwind-graph-2021`
(no changes, no records)

Delete database aliases

You can delete both local and remote database aliases using the DROP ALIAS command. The required privileges are described in the The DBMS ALIAS MANAGEMENT privileges.

Delete local database aliases

You can delete a local database alias using the DROP ALIAS command. For example:

Query
DROP ALIAS `northwind` FOR DATABASE

To verify that the local database alias has been deleted, you can use the SHOW DATABASES command. The deleted alias will no longer appear in the aliases column.

Query
SHOW DATABASE `northwind-graph-2021`
Result
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| name                   | type       | aliases | access       | address          | role      | writer | requestedStatus | currentStatus | statusMessage | default | home  | constituents |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "northwind-graph-2021" | "standard" | []      | "read-write" | "localhost:7687" | "primary" | TRUE   | "online"        | "online"      | ""            | FALSE   | FALSE | []           |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Delete remote database aliases

You can delete a remote database alias using the DROP ALIAS command. For example:

Query
DROP ALIAS `remote-northwind` FOR DATABASE

To verify that the remote database alias has been deleted, you can use the SHOW ALIASES FOR DATABASE command.

Query
SHOW ALIASES `remote-northwind` FOR DATABASE
Result
+-----------------------------------------------------+
| name | composite | database | location | url | user |
+-----------------------------------------------------+
+-----------------------------------------------------+

Use IF EXISTS when deleting database aliases

The DROP ALIAS command is optionally idempotent, with the default behavior to fail with an error if the database alias does not exist. Inserting IF EXISTS after the alias name ensures that no error is returned and nothing happens should the alias not exist.

Query
DROP ALIAS `northwind` IF EXISTS FOR DATABASE
(no changes, no records)