# Databases and copies

[Wiki](../README.md) / [Nebula Cluster](README.md)

**On this page**

- [Creating and dropping](#creating-and-dropping)
- [How many copies](#how-many-copies)
- [Where the copies are](#where-the-copies-are)
- [Moving a copy](#moving-a-copy)
- [Placing copies by hand](#placing-copies-by-hand)

Database statements are sent to any server and act on the whole cluster.

## Creating and dropping

```cypher
CREATE DATABASE orders;
CREATE DATABASE ledger OPTIONS {replicas: 5};
DROP DATABASE orders;
```

- A new database is held by three servers, each with a vote, chosen from the servers that
  hold the fewest databases.
- Every server serves every database, whether it holds a copy or not.
- A dropped database is deleted from every server that held it. One created later with the
  same name is a new, empty database.
- The default database is kept; it is not dropped.

## How many copies

`replicas` is the number of copies that vote. It is odd: three survive the loss of one
server, five the loss of two. An even number would cost a server and survive no more.

```cypher
ALTER DATABASE orders SET OPTIONS {replicas: 5};
```

Copies are added or taken away to match while the database serves. When the cluster has
fewer servers than a database asks for, the database runs on those there are and is made
up as servers are added.

## Where the copies are

```cypher
SHOW PLACEMENT;
SHOW PLACEMENT FOR DATABASE orders;
CALL gdb.cluster.members('orders');
```

| | Shows |
|---|---|
| `SHOW PLACEMENT` | Which servers hold each database, and whether each copy votes |
| `gdb.cluster.members(database)` | Each member: `node`, `address`, `role` (`leader`, `follower` or `learner`), `voter`, and how far it has got (`position`, `behind`) |

## Moving a copy

The cluster evens its servers out by itself. To move one copy yourself:

```cypher
CALL gdb.cluster.move('orders', 2, 4);
```

The copy is made on server 4 first and only then removed from server 2. If server 2 leads
the database it hands leadership on before its copy goes. The database serves throughout.

## Placing copies by hand

These procedures make one change to one database's members. They are what the cluster
itself uses. Pause it first with `CALL gdb.cluster.pause()`, so that it does not put back
what it would have chosen, and `CALL gdb.cluster.resume()` afterwards.

| Procedure | Does |
|---|---|
| `gdb.cluster.addMember(database, node)` | Gives a server a copy, without a vote |
| `gdb.cluster.promoteMember(database, node)` | Gives a member a vote once it is within 1,000 transactions of the leader |
| `gdb.cluster.removeMember(database, node)` | Takes a server out of the database's group. The leader hands leadership on first |
| `gdb.cluster.transferLeader(database, node)` | Hands leadership to a member that votes |

A change that is refused fails with `Galactus.ClientError.Cluster.ChangeRefused` and says
why.

## Related articles

[Servers](servers.md) · [Property shards](property-shards.md) · [Database administration](../operations/databases.md)
