# Database administration and DBMS procedures

[Wiki](../README.md) / [Operations](README.md)

**On this page**

- [DBMS procedures (server layer)](#dbms-procedures-server-layer)
  - [Managing databases](#managing-databases)

## DBMS procedures (server layer)

When you connect through the **Bolt server**, these are answered at the server
layer (where the instance, users and connection context live). They expose connection and instance metadata to clients.

| Procedure | Description |
|---|---|
| `dbms.components()` | Reports `Neo4j Kernel`, version `4.4.0`, edition `community` as legacy Bolt compatibility metadata; these values are not Galactus product/version identifiers |
| `dbms.showCurrentUser()` | The authenticated user, roles and flags |
| `dbms.clientConfig()` / `dbms.listConfig()` | Client/server config (empty rows) |
| `dbms.procedures()` / `dbms.functions()` | Procedure/function listing (empty rows) |
| `dbms.queryJmx(...)` | JMX metrics (empty rows) |
| `SHOW DATABASES` | Databases accessible to the current user, plus the administrative `system` endpoint |

```cypher
CALL dbms.components() YIELD name, versions, edition RETURN name, versions, edition;
CALL dbms.showCurrentUser() YIELD username, roles RETURN username, roles;
SHOW DATABASES;
```

### Managing databases

The instance hosts many databases (`system`, your home database, plus any you add).
Create and drop them over Bolt with these administration statements:

| Statement | Effect |
|---|---|
| `CREATE DATABASE <name> [IF NOT EXISTS]` | Create and open a new database. `IF NOT EXISTS` makes a pre-existing one a no-op instead of an error. |
| `DROP DATABASE <name> [IF EXISTS]` | Remove a database **and delete its files**. `IF EXISTS` makes a missing one a no-op. The home and `system` databases are protected. |
| `ALTER DATABASE <name> SET ENGINE RESIDENT` | Keep topology and property values in RAM; durable commits still use the shared commit log. |
| `ALTER DATABASE <name> SET ENGINE HYBRID` | Keep topology in RAM while cold base-property values live in the commit log behind the bounded cache. |

```cypher
CREATE DATABASE analytics;
CREATE DATABASE analytics IF NOT EXISTS;
ALTER DATABASE analytics SET ENGINE HYBRID;
DROP DATABASE analytics IF EXISTS;
```

These statements return an empty result set, like other administration
commands. A `<name>`
may be backtick-quoted (`` CREATE DATABASE `my-db` ``). On a durable instance
(`GDB_DATA` set) each database is a subdirectory of the data dir, and databases are
**re-discovered on restart**, so one created at runtime persists across a restart;
`DROP` deletes the files so the drop persists too. (These are server-layer
statements and run as auto-commit — they are not engine transactions.)

The engine selection is persisted in the database directory and is shown in the
final `engine` column of `SHOW DATABASES`. Changing it waits for the database's
current statement or write transaction, converts at a clean boundary, and then
publishes one atomic selection record. Existing connections keep using the same
database handle; no close/reopen is required. Repeating the current selection is
a zero-write no-op.

Creation and drop require their DBMS privileges; changing a user database engine
requires `ALTER DATABASE` for that database or on DBMS. The built-in `admin` has
these permissions. `system` always remains resident and rejects network engine
changes. See [permissions](authentication.md). Use auto-commit statements,
not between `BEGIN` and `COMMIT`. Database names are portable lowercase ASCII
names of 1–63 characters: start with a letter, end with a letter or digit, and
use only letters, digits, `.`, `_` or `-`; operating-system device names are
rejected even when quoted.

## Related articles

[Server configuration](configuration.md) · [Commit durability and recovery](durability.md) · [Backup, restore and transfer](backups.md)
