> ## 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.

# Storage Backends and Backup Management in LiricHomes

> Covers all storage options — SQLite, MySQL, MariaDB, PostgreSQL, YAML — and the full backup command reference for LiricHomes data management.

LiricHomes gives you full control over where home data lives. You can choose from four SQL engines or a flat-file YAML backend, switch between them by changing a single line in `config.yml`, and rely on the built-in backup system to protect your data automatically. This page explains each storage option and documents every backup command.

## Supported Storage Backends

| Type         | Use Case                                | Setup Required                             |
| ------------ | --------------------------------------- | ------------------------------------------ |
| `SQLITE`     | Default; small-to-medium servers        | None — file created automatically          |
| `MYSQL`      | Shared database across server instances | Existing MySQL server and credentials      |
| `MARIADB`    | Drop-in MySQL alternative               | Existing MariaDB server and credentials    |
| `POSTGRESQL` | Enterprise-grade relational storage     | Existing PostgreSQL server and credentials |
| `YAML`       | Development or ultra-small servers      | None — files created automatically         |

### SQLite

SQLite is the default and recommended option for standalone servers. LiricHomes creates the database file at:

```
plugins/LiricHomes/database.db
```

No database server is needed. The connection is managed internally and there are no credentials to configure. Simply leave `type: SQLITE` in `config.yml` and you're done.

### MySQL and MariaDB

For servers that share a database with other plugins or run across multiple instances (BungeeCord/Velocity networks), MySQL or MariaDB provides a centralised store. Fill in your connection details in `config.yml`:

```yaml theme={null}
storage:
  type: MYSQL         # or MARIADB
  host: "127.0.0.1"
  port: 3306
  database: "minecraft"
  username: "lirichomes"
  password: "yourpassword"
  pool-settings:
    max-pool-size: 10
    min-idle: 2
    max-lifetime: 1800000
```

LiricHomes creates the `liric_homes` table inside the specified database on first start. Make sure the database and user exist before starting the server:

```sql theme={null}
CREATE DATABASE minecraft;
CREATE USER 'lirichomes'@'localhost' IDENTIFIED BY 'yourpassword';
GRANT ALL PRIVILEGES ON minecraft.* TO 'lirichomes'@'localhost';
FLUSH PRIVILEGES;
```

### PostgreSQL

PostgreSQL uses port `5432` by default. Everything else works the same as MySQL:

```yaml theme={null}
storage:
  type: POSTGRESQL
  host: "127.0.0.1"
  port: 5432
  database: "minecraft"
  username: "lirichomes"
  password: "yourpassword"
```

### YAML (Flat-File)

YAML mode stores each player's homes as individual files in the plugin's data folder. It requires no database server, but it does not scale well for large servers and cannot be migrated easily. Use it only for development environments or very small servers.

```yaml theme={null}
storage:
  type: YAML
```

<Warning>
  YAML storage does not support the automatic backup system. If you need backup protection, switch to SQLite or a SQL backend.
</Warning>

## Connection Pooling

For all SQL backends, LiricHomes manages a connection pool automatically. The `pool-settings` block in `config.yml` controls pool behaviour:

| Setting         | Default   | Description                                                                                         |
| --------------- | --------- | --------------------------------------------------------------------------------------------------- |
| `max-pool-size` | `10`      | Maximum simultaneous connections open to the database.                                              |
| `min-idle`      | `2`       | Minimum number of idle connections kept alive.                                                      |
| `max-lifetime`  | `1800000` | Maximum connection lifetime in milliseconds (30 minutes). Set below your database's `wait_timeout`. |

## Backup System

LiricHomes includes a built-in backup system that creates point-in-time snapshots of your home data. Backups work with SQLite, MySQL, MariaDB, and PostgreSQL backends.

### Automatic Backups

Configure automatic backups in `config.yml`:

```yaml theme={null}
backups:
  enabled: true
  interval-hours: 24   # Create a backup every 24 hours
  max-backups: 7       # Keep up to 7 backups; oldest is deleted when limit is exceeded
```

With the defaults, LiricHomes maintains a rolling seven-day backup history. When a new automatic backup would exceed `max-backups`, the oldest backup is deleted automatically.

### Backup Commands

All backup commands require the `liric.adminhomes.backup` permission (default: op).

| Command                            | Description                                                                |
| ---------------------------------- | -------------------------------------------------------------------------- |
| `/adminhomes backup create [name]` | Creates a backup immediately. If `[name]` is omitted, a timestamp is used. |
| `/adminhomes backup list`          | Lists all available backups with their creation dates.                     |
| `/adminhomes backup <name>`        | Restores the named backup, replacing all current home data.                |
| `/adminhomes backup delete <name>` | Permanently deletes the named backup.                                      |

#### Creating a Backup

```bash theme={null}
/adminhomes backup create pre-migration
```

This creates a named backup called `pre-migration`. Using descriptive names makes it easier to identify the right backup when you need to restore.

#### Restoring a Backup

```bash theme={null}
/adminhomes backup list
/adminhomes backup pre-migration
```

<Warning>
  Restoring a backup replaces all current home data. Create a fresh backup before restoring if you want to keep the current state. After restoring, it is recommended to reload or restart the server to ensure the restored data is fully in memory.
</Warning>

#### Deleting a Backup

```bash theme={null}
/adminhomes backup delete pre-migration
```

Deletion is permanent and cannot be undone.

## Migrating from EssentialsX

If you are switching from EssentialsX's built-in home storage to LiricHomes' own database, run the migration command after setting `home-backend: PLUGIN` in `config.yml`:

```bash theme={null}
/adminhomes datamigrate Essentials
```

This command reads every home from EssentialsX's data files and imports them into the LiricHomes database. The process is non-destructive — EssentialsX's own files are not modified. Migration progress is reported in the console and in chat, showing the number of players and homes processed.

<Tip>
  Run `/adminhomes backup create before-migration` before starting the migration so you have a clean rollback point if anything goes wrong.
</Tip>