Storage Configuration

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

Available Storage Types

TypeStatusBest For
jsonAvailableSingle servers, small to medium scale
mysqlPlannedMulti-server networks, large scale
postgresqlPlannedEnterprise deployments
sqlitePlannedSingle servers, better performance

JSON Storage (Default)

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

Configuration

json
{
  "storage": {
    "type": "json",
    "autoSave": true,
    "autoSaveInterval": 300,
    "backups": {
      "enabled": true,
      "interval": 3600,
      "maxBackups": 24
    }
  }
}

File Locations

text
plugins/HyperPerms/
├── config.json    # Main configuration
├── groups.json    # Group definitions
├── users.json     # User data
├── tracks.json    # Track definitions
└── backups/       # Automatic backups
    ├── backup-2024-01-15-120000.json
    └── backup-2024-01-14-120000.json

File Structure: groups.json

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

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

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
JSON storage is sufficient for most servers. Consider database storage only if you have thousands of users or need multi-server synchronization.

Auto-Save Configuration

json
"storage": {
  "autoSave": true,
  "autoSaveInterval": 300
}
  • autoSave - When enabled, changes are periodically written to disk
  • autoSaveInterval - Seconds between auto-saves (default: 5 minutes)
Changes from commands are always saved immediately. Auto-save handles any pending changes that might be queued.

Backup Configuration

json
"storage": {
  "backups": {
    "enabled": true,
    "interval": 3600,
    "maxBackups": 24
  }
}
  • enabled - Enable automatic backups
  • interval - Seconds between backups (default: 1 hour)
  • maxBackups - Maximum backups to keep (oldest deleted first)

Manual Backups

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

Server SizeIntervalMax Backups
Small (<50 players)3600 (1 hour)24
Medium (50-200 players)1800 (30 min)48
Large (200+ players)900 (15 min)96

Database Storage (Future)

Database storage is planned for a future release and is not yet available.

Planned MySQL Configuration

json
{
  "storage": {
    "type": "mysql",
    "mysql": {
      "host": "localhost",
      "port": 3306,
      "database": "hyperperms",
      "username": "hyperperms",
      "password": "secure-password",
      "tablePrefix": "hp_",
      "poolSize": 10
    }
  }
}

Planned PostgreSQL Configuration

json
{
  "storage": {
    "type": "postgresql",
    "postgresql": {
      "host": "localhost",
      "port": 5432,
      "database": "hyperperms",
      "username": "hyperperms",
      "password": "secure-password",
      "schema": "public",
      "poolSize": 10
    }
  }
}

Benefits of Database Storage

  • Better performance for large datasets
  • Native multi-server synchronization
  • ACID compliance for data integrity
  • Advanced querying capabilities

Migrating Storage

When database storage becomes available, you'll be able to migrate:

text
# Future command
/hp migrate mysql

Manual File Editing

You can manually edit JSON files, but be careful:

  1. Stop the server or unload the plugin first
  2. Create a backup before editing
  3. Validate JSON syntax (use a JSON validator)
  4. Start the server and verify with /hp reload
Invalid JSON will prevent HyperPerms from loading. Always validate your changes before starting the server.

Troubleshooting

Data Not Saving

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

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