> ## Documentation Index
> Fetch the complete documentation index at: https://pumpkings.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring LiricHomes: Storage, Limits, and Backups

> Full reference for config.yml: storage backend, home-backend mode, default home limits, cancel keyword, and automatic backup settings.

All of LiricHomes' core behaviour is controlled through `plugins/LiricHomes/config.yml`. The file is generated automatically on first server start with sensible defaults — SQLite storage, a three-home limit, and daily backups. This page walks through every setting so you can tune the plugin to fit your server's exact requirements.

## Full config.yml

```yaml theme={null}
# LiricHomes - Main Configuration

# ─────────────────────────────────────────────────────────────
#  STORAGE
#  Supported types: MYSQL, MARIADB, POSTGRESQL, SQLITE, YAML
# ─────────────────────────────────────────────────────────────
storage:
  type: SQLITE            # Change to MYSQL, MARIADB, POSTGRESQL, or YAML as needed
  host: "127.0.0.1"
  port: 3306
  database: "minecraft"
  username: "root"
  password: ""
  pool-settings:
    max-pool-size: 10
    min-idle: 2
    max-lifetime: 1800000

# ─────────────────────────────────────────────────────────────
#  HOME BACKEND
# ─────────────────────────────────────────────────────────────
home-backend: PLUGIN      # PLUGIN | ESSENTIALS

# Sync homes created via /sethome into LiricHomes storage.
# Only applies when home-backend: PLUGIN
sync-essentials-homes: true

# ─────────────────────────────────────────────────────────────
#  HOME LIMITS  ⚠ Only applies when home-backend: PLUGIN
# ─────────────────────────────────────────────────────────────
default-home-limit: 3

# ─────────────────────────────────────────────────────────────
#  CHAT INTERACTION
# ─────────────────────────────────────────────────────────────
cancel-keyword: "cancelar"

# ─────────────────────────────────────────────────────────────
#  AUTOMATIC BACKUPS
# ─────────────────────────────────────────────────────────────
backups:
  enabled: true
  interval-hours: 24
  max-backups: 7
```

## Storage Settings

The `storage` block defines where LiricHomes persists home data.

| Field      | Default     | Description                                                                    |
| ---------- | ----------- | ------------------------------------------------------------------------------ |
| `type`     | `SQLITE`    | Storage backend. One of `MYSQL`, `MARIADB`, `POSTGRESQL`, `SQLITE`, or `YAML`. |
| `host`     | `127.0.0.1` | Database server hostname or IP. Not used by SQLite or YAML.                    |
| `port`     | `3306`      | Database port. Not used by SQLite or YAML.                                     |
| `database` | `minecraft` | Database (schema) name. Not used by SQLite or YAML.                            |
| `username` | `root`      | Database user. Not used by SQLite or YAML.                                     |
| `password` | *(empty)*   | Database password. Not used by SQLite or YAML.                                 |

### Connection Pool Settings

The `pool-settings` sub-block controls the SQL connection pool and is relevant only for MySQL, MariaDB, and PostgreSQL.

| Field           | Default   | Description                                                    |
| --------------- | --------- | -------------------------------------------------------------- |
| `max-pool-size` | `10`      | Maximum number of connections kept open simultaneously.        |
| `min-idle`      | `2`       | Minimum number of idle connections maintained in the pool.     |
| `max-lifetime`  | `1800000` | Maximum lifetime of a connection in milliseconds (30 minutes). |

<Note>
  For SQLite and YAML backends, all `pool-settings` values are ignored. SQLite stores data at `plugins/LiricHomes/database.db` with no server required.
</Note>

<Tabs>
  <Tab title="SQLite (default)">
    ```yaml theme={null}
    storage:
      type: SQLITE
    ```

    No other fields are needed. The database file is created automatically.
  </Tab>

  <Tab title="MySQL / MariaDB">
    ```yaml theme={null}
    storage:
      type: MYSQL       # or MARIADB
      host: "127.0.0.1"
      port: 3306
      database: "minecraft"
      username: "lirichomes"
      password: "strongpassword"
      pool-settings:
        max-pool-size: 10
        min-idle: 2
        max-lifetime: 1800000
    ```

    Create the database and user in MySQL/MariaDB before starting the server. LiricHomes creates the `liric_homes` table automatically.
  </Tab>

  <Tab title="PostgreSQL">
    ```yaml theme={null}
    storage:
      type: POSTGRESQL
      host: "127.0.0.1"
      port: 5432
      database: "minecraft"
      username: "lirichomes"
      password: "strongpassword"
      pool-settings:
        max-pool-size: 10
        min-idle: 2
        max-lifetime: 1800000
    ```

    PostgreSQL uses port `5432` by default instead of `3306`.
  </Tab>

  <Tab title="YAML (flat-file)">
    ```yaml theme={null}
    storage:
      type: YAML
    ```

    Homes are stored as individual YAML files inside the plugin's data folder. Suitable for very small servers or development environments only.
  </Tab>
</Tabs>

## Home Backend

The `home-backend` field controls how LiricHomes stores and sources home data.

### `PLUGIN` (recommended)

```yaml theme={null}
home-backend: PLUGIN
sync-essentials-homes: true
```

LiricHomes owns the home data. Homes are written to the configured SQL or YAML backend. When `sync-essentials-homes` is `true`, homes created or deleted through EssentialsX commands (`/sethome`, `/delhome`) are automatically mirrored into the LiricHomes database.

Use this mode on any server where you want full control over home storage, limits, and backups.

### `ESSENTIALS`

```yaml theme={null}
home-backend: ESSENTIALS
```

LiricHomes acts as a display and GUI layer only. EssentialsX remains the source of truth for home data. LiricHomes reads homes directly from EssentialsX and shows them in the GUI, but does not write to its own database.

<Warning>
  In `ESSENTIALS` mode, home limits are controlled by EssentialsX permission nodes (`essentials.sethome.multiple.X`), **not** by `liric.homes.vip.<N>`. The `default-home-limit` setting in `config.yml` is ignored. Backup and data migration commands are also unavailable in this mode.
</Warning>

## Home Limits

```yaml theme={null}
default-home-limit: 3
```

This value applies to any player who does not hold a `liric.homes.vip.<N>` permission node. It is only evaluated when `home-backend: PLUGIN`.

You can override the limit per rank or per player using permission nodes. See the [Permissions](/homes/permissions) page for the full priority chain.

## Cancel Keyword

```yaml theme={null}
cancel-keyword: "cancelar"
```

When a player is prompted to type something in chat — such as a new home name or display name — they can abort the action by typing the cancel keyword. Change this to any word that suits your server's language or style (for example, `"cancel"` or `"abort"`).

## Automatic Backups

```yaml theme={null}
backups:
  enabled: true
  interval-hours: 24
  max-backups: 7
```

| Field            | Default | Description                                                                                                                  |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `enabled`        | `true`  | Whether automatic backups run on the configured interval.                                                                    |
| `interval-hours` | `24`    | Hours between each automatic backup (24 = once per day).                                                                     |
| `max-backups`    | `7`     | Maximum number of backup files to keep. When this limit is reached, the oldest backup is deleted automatically to make room. |

<Tip>
  With the defaults, LiricHomes keeps a rolling seven-day history of your home data. You can also create a manual backup at any time with `/adminhomes backup create [name]`. See the [Storage](/homes/storage) page for full backup command reference.
</Tip>