Skip to main content
BetterHud can store player data in either local YAML files or a MySQL database.

​
File Structure

Database configuration is located at:
  • plugins/BetterHud/database.yml

​
Configuration Options

database.yml
type: yml
info:
  host: localhost
  database: betterhud
  name: root
  password: your_password_here
​
type
string
default:"yml"
required
Storage type. Options:
  • yml - Local YAML files
  • mysql - MySQL database

​
MySQL Settings

​
info.host
string
default:"localhost"
MySQL server hostname or IP address
​
info.database
string
default:"betterhud"
Database name
​
info.name
string
default:"root"
MySQL username
​
info.password
string
required
MySQL password

​
YAML Storage (Default)

Simple file-based storage for small servers: 
type: yml
Player data is stored in:
  • plugins/BetterHud/players/
Recommended for: Single servers, small player counts (under 1000 players)

​
MySQL Storage

Database storage for large servers and networks:
database.yml
type: mysql
info:
  host: localhost
  database: betterhud
  name: minecraft_user
  password: secure_password_here
Recommended for: Large servers, multi-server networks, player counts over 1000

​
MySQL Setup

1

Create Database

Create a MySQL database for BetterHud:
CREATE DATABASE betterhud;
CREATE USER 'minecraft_user'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON betterhud.* TO 'minecraft_user'@'localhost';
FLUSH PRIVILEGES;
2

Configure BetterHud

Update database.yml with your MySQL credentials:
type: mysql
info:
  host: localhost
  database: betterhud
  name: minecraft_user
  password: secure_password
3

Restart Server

Restart your server. BetterHud will automatically create the required tables.

​
Network Setup

For multi-server networks, all servers can share one MySQL database: 
# Server 1
type: mysql
info:
  host: 192.168.1.100
  database: betterhud_network
  name: network_user
  password: network_password

# Server 2
type: mysql
info:
  host: 192.168.1.100  # Same database
  database: betterhud_network
  name: network_user
  password: network_password

​
Migration

​
YAML to MySQL

1

Backup Data

Backup your plugins/BetterHud/players/ directory
2

Setup MySQL

Configure MySQL as shown above
3

Change Type

Change type: yml to type: mysql in database.yml
4

Restart

Restart the server. Player data will be migrated automatically on first join.

​
MySQL to YAML

Downgrading from MySQL to YAML will require players to rejoin for data export.

​
Performance

​
YAML Storage

  • ✅ Simple setup
  • ✅ No external dependencies
  • ❌ Slower with many players
  • ❌ No network sync

​
MySQL Storage

  • ✅ Fast with many players
  • ✅ Network synchronization
  • ✅ Better reliability
  • ❌ Requires MySQL server
  • ❌ More complex setup

​
Troubleshooting

Check MySQL is running and credentials are correct:
mysql -u minecraft_user -p -h localhost
Grant proper privileges to the MySQL user:
GRANT ALL PRIVILEGES ON betterhud.* TO 'minecraft_user'@'%';
FLUSH PRIVILEGES;
Check the auto-save-time setting in config.yml:
auto-save-time: 300  # Save every 5 minutes

​
See Also

Main Config

Configure auto-save intervals

API Reference

DatabaseManager API

HudPlayer

Player data methods

Troubleshooting

Common database issues

Build docs developers (and LLMs) love

Get started for freeTalk to us