HyDB - Professional SQLite Database API for Hytale

📊 Overview

HyDB is a professional base plugin for Hytale that provides a comprehensive SQLite database API for persistent data storage. It allows other plugins to easily store and retrieve data without managing database connections themselves.

Think of it as a database service layer - install HyDB once, and all your other plugins can use it for reliable, fast, thread-safe data storage.

✨ Key Features

🗄️ Database Management

SQLite with JDBC - Industry-standard embedded database (no external server needed)
Per-World & Global Databases - Store data globally across all worlds or per-world
Automatic Connection Management - HyDB handles all database lifecycle
File-Based Storage - Each plugin gets its own database file for complete isolation

⚡ Performance & Safety

Async Operations - Non-blocking database calls using Java 25 virtual threads
Thread-Safe - Safe concurrent access from multiple plugins/threads
Connection Pooling - Efficient resource management
WAL Mode - Write-Ahead Logging for better performance

🔧 Complete API

Full CRUD Operations - Create, Read, Update, Delete with simple API
Schema Migrations - Version and upgrade database schemas automatically
Transaction Support - Execute multiple operations atomically
Blob Storage - Store binary data (images, files, serialized objects)
Query Builder - Fluent API for constructing complex SQL queries
Prepared Statements - Built-in SQL injection protection

🎮 In-Game Admin Commands

/hydb list - View all databases with file sizes
/hydb info <db> - Show database details and statistics
/hydb tables <db> - List all tables with row counts
/hydb query <db> "SQL" - Execute SELECT queries for debugging
Read-only queries ensure data safety

📦 Installation

Download HyDB-1.0.0.jar
Place in your server's mods folder
Restart your server
Done! Other plugins can now use HyDB

Requirements:

Hytale Server (latest version)
Java 25+

👨‍💻 For Plugin Developers

Quick Start

// Get the API
HyDBAPI api = HyDBPlugin.getAPI();

// Get or create a database
Database db = api.getGlobalDatabase("myplugin");

// Create a table
db.createTable("users",
    "id INTEGER PRIMARY KEY AUTOINCREMENT",
    "uuid TEXT NOT NULL UNIQUE",
    "username TEXT NOT NULL",
    "coins INTEGER DEFAULT 0"
);

// Insert data (async)
Map<String, Object> data = new HashMap<>();
data.put("uuid", player.getUniqueId().toString());
data.put("username", player.getName());
data.put("coins", 100);

db.insertAsync("users", data).thenAccept(rows -> {
    System.out.println("Player data saved!");
});

// Query data (async)
db.queryFirstAsync("SELECT * FROM users WHERE uuid = ?", playerUUID.toString())
    .thenAccept(user -> {
        if (user != null) {
            int coins = (int) user.get("coins");
            // Use the data
        }
    });

Database Scope

// Global database - shared across all worlds (economy, player stats)
Database global = api.getGlobalDatabase("economy");

// Per-world database - isolated per world (claims, regions)
Database world = api.getWorldDatabase(world, "claims");

🎯 Use Cases

Perfect for plugins that need:

✅ Economy Systems - Player balances, shops, transactions
✅ Player Statistics - Stats tracking, leaderboards, achievements
✅ Land Claims - Territory ownership, permissions
✅ Custom Game Modes - Game state, progression tracking
✅ Social Features - Friends lists, guilds, parties
✅ Admin Tools - Bans, warnings, action logs
✅ RPG Systems - Character data, skills, inventory
✅ Any Persistent Data - Anything that needs to survive restarts

🏗️ Architecture

Database Structure

HyDB/
├── global/              # Global databases
│   ├── economy.db       # Economy plugin
│   ├── stats.db         # Stats plugin
│   └── yourplugin.db    # Your plugin
└── worlds/              # Per-world databases
    ├── world1/
    │   └── claims.db
    └── world2/
        └── claims.db

Each plugin gets its own database file containing multiple tables, providing:

Complete data isolation
Easy backup/restore
Independent scaling
No table name conflicts

📖 Documentation

Included files:

README.md - Complete API documentation with examples
COMMANDS.md - Admin command reference
QUICK_START.md - Quick reference guide
EXAMPLE_USAGE.java - Full working example plugin
DATABASE_STRUCTURE.md - Architecture details

🔒 Safety Features

Read-Only Admin Commands - Query commands only allow SELECT/PRAGMA
SQL Injection Protection - Prepared statements throughout
Automatic Rollback - Transaction failures roll back automatically
Error Handling - Comprehensive error messages and logging

🛠️ Technical Details

Language: Java 25 with modern features (virtual threads, switch expressions)
Database: SQLite 3.47.1.0 with JDBC
Build: Simple bash build script (no complex build tools)
Dependencies: Bundled (SQLite JDBC, SLF4J)
Size: ~14MB (includes all dependencies)

🌟 Why Use HyDB?

For Server Owners

✅ Install once, benefits all plugins ✅ Centralized database management ✅ In-game debugging commands ✅ Better server performance (shared connection pooling)

For Plugin Developers

✅ No database management code needed ✅ Simple, intuitive API ✅ Async operations prevent lag ✅ Well-documented with examples ✅ Schema migration support

📊 Comparison

Feature	HyDB	JSON Files	Custom DB Code
Easy to Use	✅ Simple API	✅ Very Simple	❌ Complex
Performance	✅ Fast	❌ Slow	✅ Fast
Queries	✅ SQL	❌ Limited	✅ SQL
Thread-Safe	✅ Yes	❌ No	⚠️ Depends
Async	✅ Built-in	❌ Manual	⚠️ Manual
Migrations	✅ Built-in	❌ Manual	⚠️ Manual
Transactions	✅ Built-in	❌ No	✅ Yes

🚀 Example Plugins Using HyDB

The download includes a complete example plugin showing:

Database setup with migrations
Player data management
Transaction-based operations
Query builder usage
Best practices

📝 License

Open source - free to use for Hytale servers and plugin development.

🤝 Support & Contributing

Issues: Report bugs or request features
Documentation: Comprehensive guides included
Examples: Working code samples provided

🎉 Get Started Today!

Install HyDB on your server
Other plugins can immediately use the API
Use /hydb commands for debugging and monitoring
Enjoy reliable, fast database storage!

Version: 1.0.0 Compatibility: Hytale (current version) Mod Author: Oceride

Making data persistence simple and powerful for Hytale plugins! This is a required dependency / backend database mod.

Image Generated by GPT-4