# 🗄️ Database Setup

You can run NexusProxy without a database, but some systems work better or require persistent storage when you want data to remain after restarts.

***

### Supported Storage Types

NexusProxy supports the following database types:

```yaml
none
mysql
mongodb
mongo
```

Use `none` for memory-only mode.

Use `mysql` or `mongodb` if you want persistent storage.

***

### When Should You Use a Database?

A database is recommended if your network uses features such as:

* Friends
* Known player profiles
* Ignored players
* Private message data
* HelpOp history
* History-backed systems

{% hint style="info" %}
If your network only needs simple proxy commands and temporary features, database storage may not be required.
{% endhint %}

***

### Database Configuration File

Database settings are configured in:

```
plugins/NexusProxy/nexusproxy.yml
```

Look for the storage database section.

Example:

```yaml
storage:
  database:
    type: "none"
```

***

### Memory-Only Mode

Use `none` if you do not want NexusProxy to use a database.

Example:

```yaml
storage:
  database:
    type: "none"
```

This mode is useful for simple setups or test servers.

{% hint style="warning" %}
Memory-only mode does not provide persistent storage for supported systems.

Data that requires persistence may be lost after a restart.
{% endhint %}

***

### MySQL Setup

Use MySQL if you want persistent storage using a SQL database.

Example configuration:

```yaml
storage:
  database:
    type: "mysql"
    mysql:
      host: "127.0.0.1"
      port: 3306
      database: "nexusproxy"
      username: "root"
      password: "password"
      use_ssl: false
      allow_public_key_retrieval: true
```

***

### MySQL Options

#### host

The MySQL server host.

Example for a local MySQL server:

```yaml
host: "127.0.0.1"
```

Example for an external MySQL server:

```yaml
host: "mysql.yournetwork.com"
```

***

#### port

The MySQL server port.

Default MySQL port:

```yaml
port: 3306
```

***

#### database

The database name used by NexusProxy.

Example:

```yaml
database: "nexusproxy"
```

Make sure the database exists before starting the proxy.

***

#### username

The MySQL username.

Example:

```yaml
username: "root"
```

***

#### password

The MySQL password.

Example:

```yaml
password: "your-password"
```

{% hint style="warning" %}
Never share your database password publicly.

Remove private credentials before posting your configuration in support channels.
{% endhint %}

***

#### use\_ssl

Controls whether the MySQL connection should use SSL.

Example:

```yaml
use_ssl: false
```

If your database host requires SSL, set it to:

```yaml
use_ssl: true
```

***

#### allow\_public\_key\_retrieval

This option may be needed by some MySQL 8 setups.

Example:

```yaml
allow_public_key_retrieval: true
```

If your MySQL server does not require it, you can leave it disabled depending on your setup.

***

### MongoDB Setup

Use MongoDB if you want persistent storage using a MongoDB database.

Example configuration:

```yaml
storage:
  database:
    type: "mongodb"
    mongodb:
      uri: "mongodb://localhost:27017"
      database: "nexusproxy"
```

You can also use:

```yaml
storage:
  database:
    type: "mongo"
```

***

### MongoDB Options

#### uri

The MongoDB connection URI.

Example for a local MongoDB server:

```yaml
uri: "mongodb://localhost:27017"
```

Example with authentication:

```yaml
uri: "mongodb://username:password@localhost:27017"
```

***

#### database

The MongoDB database name used by NexusProxy.

Example:

```yaml
database: "nexusproxy"
```

***

### MySQL vs MongoDB

Both MySQL and MongoDB can be used for persistent NexusProxy data.

Use whichever database system fits your network infrastructure better.

| Storage | Recommended When                                            |
| ------- | ----------------------------------------------------------- |
| MySQL   | You already use SQL databases or prefer relational storage. |
| MongoDB | You already use MongoDB or prefer document-based storage.   |
| none    | You do not need persistent data.                            |

***

### Database and Friends

The Friends module works best with database storage.

A database can store:

* Friend relationships
* Friend counts
* Player profile data
* Persistent friend-related information

Redis can help with online/offline friend status, but the database is used for persistent friend data.

{% hint style="info" %}
For cross-proxy networks using Friends, Redis + database storage is recommended.
{% endhint %}

***

### Database and PlaceholderAPI Expansion

If you use the NexusProxy PlaceholderAPI expansion on backend servers, the expansion should use the same database settings as NexusProxy.

This is especially important for friends placeholders.

Velocity plugin:

```yaml
storage:
  database:
    type: "mysql"
    mysql:
      host: "127.0.0.1"
      port: 3306
      database: "nexusproxy"
      username: "root"
      password: "password"
      use_ssl: false
      allow_public_key_retrieval: true
```

PlaceholderAPI expansion:

```yaml
database:
  type: "mysql"
  mysql:
    host: "127.0.0.1"
    port: 3306
    database: "nexusproxy"
    username: "root"
    password: "password"
    use_ssl: false
    allow_public_key_retrieval: true
```

{% hint style="warning" %}
If the PlaceholderAPI expansion uses different database settings, friends placeholders may return `0` or incorrect values.
{% endhint %}

***

### Runtime Libraries

NexusProxy downloads optional database libraries when needed.

These libraries are stored in:

```
plugins/NexusProxy/libraries/
```

This may include:

* MySQL driver
* MongoDB driver
* Other required runtime libraries

{% hint style="info" %}
You normally do not need to manually install database drivers.

NexusProxy handles required runtime libraries when the feature is enabled.
{% endhint %}

***

### Checking Database Status

After configuring the database, restart your proxy or reload NexusProxy.

Then run:

```
/nexusproxy storage
```

Aliases:

```
/nproxy storage
/np storage
```

Use this command to confirm whether the database is connected correctly.

***

### Common Database Issues

#### Database does not connect

Check that:

* The database server is running.
* The host is correct.
* The port is correct.
* The database name is correct.
* The username is correct.
* The password is correct.
* The proxy can reach the database server.

***

#### MySQL authentication fails

Check that:

* The username and password are correct.
* The MySQL user has access to the selected database.
* The database exists.
* `allow_public_key_retrieval` is configured correctly for your MySQL setup.
* `use_ssl` matches your database host requirements.

***

#### MongoDB connection fails

Check that:

* The MongoDB URI is correct.
* The MongoDB server is running.
* Authentication details are correct.
* The selected database name is correct.
* The proxy can reach the MongoDB server.

***

#### Friends placeholders return 0

Check that:

* Database storage is enabled.
* The Friends module is configured correctly.
* Friend data exists in the database.
* Redis is configured if online friend status is needed.
* The PlaceholderAPI expansion uses the same database settings.
* The PlaceholderAPI expansion uses the same Redis settings.

***

### Recommended Production Setup

For a production network using friends, placeholders, and multi-proxy synchronization, the recommended setup is:

* Redis enabled
* MySQL or MongoDB enabled
* Unique `cluster.proxy_id` per proxy
* Same Redis settings on every proxy
* Same database settings on every proxy
* Same Redis and database settings in the PlaceholderAPI expansion

Example:

```yaml
storage:
  redis:
    enabled: true
    host: "127.0.0.1"
    port: 6379
    password: ""
    database: 0
    channel_prefix: "nexusproxy"

  database:
    type: "mysql"
    mysql:
      host: "127.0.0.1"
      port: 3306
      database: "nexusproxy"
      username: "root"
      password: "password"
      use_ssl: false
      allow_public_key_retrieval: true
```

***

### Final Checklist

Before asking for support, verify:

* Database type is correct.
* Database server is running.
* Host and port are correct.
* Database name is correct.
* Username and password are correct.
* The proxy can connect to the database.
* `/nexusproxy storage` shows the database as connected.
* PlaceholderAPI expansion database settings match NexusProxy if you use backend placeholders.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nexusproxy.nemesismc.net/database-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.