> For the complete documentation index, see [llms.txt](https://docs.spoof.dev/asteroid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spoof.dev/asteroid/configuration/database.md).

# Database

Asteroid stores your fake player profiles (usernames and skins) and other persistent data in a database. You choose which kind.

```yaml
database:
  type: "sqlite"
  prevent-duplicate-connections: true
  mysql:
    host: 'host'
    database: 'database'
    username: 'username'
    password: 'password'
    port: 3306
    ssl: false
  mongodb:
    uri: "mongodb://user:password@host:port/authdb"
```

## Choosing a type

| Type      | Best for                                             | Setup needed                             |
| --------- | ---------------------------------------------------- | ---------------------------------------- |
| `sqlite`  | Single servers or small setups. This is the default. | None. Stores everything in a local file. |
| `mysql`   | Sharing profiles across multiple servers.            | A MySQL server.                          |
| `mongodb` | Setups that already use MongoDB.                     | A MongoDB server.                        |

If you run one server, `sqlite` is simplest and needs no configuration. If you run a network and want the same profiles everywhere, use `mysql` or `mongodb`.

## MySQL

| Field      | What it goes in                                                                  |
| ---------- | -------------------------------------------------------------------------------- |
| `host`     | The MySQL server address. You can include the port as `host:port` if you prefer. |
| `database` | The database name Asteroid should use.                                           |
| `username` | The MySQL user.                                                                  |
| `password` | That user's password.                                                            |
| `port`     | The MySQL port, usually 3306.                                                    |
| `ssl`      | Whether to connect over SSL.                                                     |

Asteroid creates the table it needs automatically the first time it connects.

## MongoDB

The connection URI format is `mongodb://[username:password@]host[:port]/[authenticationDatabase]`, for example `mongodb://admin:secretpass@localhost:27017/asteroid`.

## Preventing duplicate connections across servers

When several servers share the same `mysql` or `mongodb` database, you do not want the same fake profile online on two servers at once, since observant players could notice the same name in two places.

```yaml
prevent-duplicate-connections: true
```

When this is on:

* When a fake connects, its profile is marked as connected in the shared database.
* Other servers see the mark and skip that profile, so it is live on only one server at a time.
* When the fake leaves, the profile is freed.
* If a server crashes while holding profiles, they are released automatically after a short timeout, so nothing stays locked forever.

This has no effect on `sqlite`, because each server has its own local file. Leave it on for shared databases. There is no downside.

## Fixing stale profiles

Over time, some profiles can become invalid (a name change, a banned account). Clean the database with the AsteroidDatabaseFixer tool: <https://github.com/Asteroid-Enterprise/AsteroidDatabaseFixer>