Storage Configuration

HyperPerms supports multiple storage backends for persisting permission data. This guide covers available options and their configuration.

Available Storage Types

JSON Storage (Default)

JSON storage is the default backend. It stores all data in human-readable JSON files in the mod directory.

Configuration

{
  "storage": {
    "type": "json"
  }
}

File Locations

mods/com.hyperperms_HyperPerms/
├── config.json    # Main configuration
├── groups.json    # Group definitions
├── users.json     # User data
├── tracks.json    # Track definitions
└── backups/       # Automatic backups
    ├── backup-2026-01-15-120000.json
    └── backup-2026-01-14-120000.json

File Structure: groups.json

{
  "default": {
    "displayName": "Default",
    "weight": 0,
    "prefix": "&7",
    "suffix": null,
    "prefixPriority": 0,
    "suffixPriority": 0,
    "permissions": [
      {
        "permission": "chat.use",
        "value": true,
        "expiry": null,
        "contexts": {}
      }
    ],
    "parents": []
  },
  "vip": {
    "displayName": "VIP",
    "weight": 20,
    "prefix": "&a[VIP] ",
    "suffix": null,
    "prefixPriority": 0,
    "suffixPriority": 0,
    "permissions": [
      {
        "permission": "chat.color",
        "value": true,
        "expiry": null,
        "contexts": {}
      }
    ],
    "parents": ["default"]
  }
}

File Structure: users.json

{
  "853c80ef-3c37-49fd-aa49-938b674adae6": {
    "uuid": "853c80ef-3c37-49fd-aa49-938b674adae6",
    "username": "Steve",
    "primaryGroup": "vip",
    "groups": ["vip"],
    "permissions": [],
    "customPrefix": null,
    "customSuffix": null
  }
}

File Structure: tracks.json

{
  "staff": {
    "name": "staff",
    "groups": ["helper", "mod", "admin", "owner"]
  },
  "donor": {
    "name": "donor",
    "groups": ["vip", "vip-plus", "mvp"]
  }
}

Advantages

• No external dependencies
• Human-readable and editable
• Easy to backup and restore
• Simple to set up

Limitations

• Not ideal for very large datasets
• No native multi-server sync
• File I/O can be slower than database

Manual Backups

# Create a manual backup
/hp backup create my-backup

# List available backups
/hp backup list

# Restore from backup
/hp backup restore my-backup

Backup Strategy Recommendations

SQLite Storage

SQLite provides better performance than JSON for single servers and enables analytics tracking and audit logs. The SQLite JDBC driver is not bundled with HyperPerms to keep the JAR small (2.4MB vs 15MB).

Driver Installation

1. Download the SQLite JDBC driver from sqlite-jdbc releases
2. Place the downloaded JAR in mods/com.hyperperms_HyperPerms/lib/
3. Restart the server

Configuration

{
  "storage": {
    "type": "sqlite"
  }
}

MariaDB/MySQL Storage

MariaDB/MySQL storage provides full database support with HikariCP connection pooling, ideal for multi-server networks. Compatible with both MariaDB and MySQL.

Configuration

{
  "storage": {
    "type": "mariadb",
    "mariadb": {
      "host": "localhost",
      "port": 3306,
      "database": "hyperperms",
      "user": "hyperperms",
      "password": "secure-password",
      "useSSL": false
    }
  }
}

Features

• Full CRUD for users, groups, and tracks
• HikariCP connection pooling for optimal performance
• Backup and restore via JSON dump strategy
• Native multi-server synchronization

Migrating Storage

You can migrate between storage backends using the migrate command:

/hp migrate mariadb
/hp migrate sqlite
/hp migrate json

Manual File Editing

You can manually edit JSON files, but be careful:

1. Stop the server or unload the mod first
2. Create a backup before editing
3. Validate JSON syntax (use a JSON validator)
4. Start the server and verify with /hp reload

Troubleshooting

Data Not Saving

• Check file permissions on the mod directory
• Ensure disk space is available
• Look for errors in console logs
• Try /hp reload to force a reload

Corrupted JSON Files

• Restore from the latest backup
• Check for JSON syntax errors
• Use a JSON validator to find issues

Backup Restore Fails

• Verify the backup file exists and is readable
• Check that backup isn't corrupted
• Ensure you have the correct permissions

See Also

• Main Configuration
• General Commands (backup commands)
• Troubleshooting Guide