sql setup

docs/10_Database.md

@@ -0,0 +1,100 @@
+# Database
+
+Shared MySQL pool, exposed to all plugins via `DatabaseService` from NetworkCore. Use this for durable state that needs to survive restarts and be queried later: player profiles, punishment history, currency balances, leaderboards, anything you'd run a SQL query against.
+
+For ephemeral observability data (counters, latency), use the metrics layer instead. See [04_Metrics.md](04_Metrics.md).
+
+## API
+
+```java
+public interface DatabaseService {
+    DataSource getDataSource();
+    boolean isHealthy();
+    int getActiveConnections();
+    int getIdleConnections();
+    int getTotalConnections();
+}
+```
+
+That's it. We expose the `DataSource` and stay out of your way. Use JDBC directly, jOOQ, MyBatis, JdbcTemplate, whatever you like.
+
+## Getting a connection
+
+Always use try-with-resources so connections return to the pool:
+
+```java
+DatabaseService db = NetworkCore.getInstance().getDatabase();
+if (db == null) {
+    // MySQL disabled in NetworkCore config; degrade gracefully
+    return;
+}
+
+try (Connection c = db.getDataSource().getConnection();
+     PreparedStatement ps = c.prepareStatement("SELECT name, level FROM players WHERE uuid = ?")) {
+    ps.setString(1, uuid.toString());
+    try (ResultSet rs = ps.executeQuery()) {
+        if (rs.next()) {
+            return new PlayerRecord(rs.getString("name"), rs.getInt("level"));
+        }
+    }
+}
+```
+
+Never hold a connection across an RPC call, a thread hop, or a wait. Pool exhaustion is the most common way Hikari-backed plugins fall over.
+
+## Threading
+
+The pool is fully thread-safe. Get a connection from whichever thread needs it. JDBC calls themselves block, so:
+
+- Don't run heavy queries on the Hytale world thread - it stops world ticking.
+- Don't run heavy queries on the MessageBus worker pool - it backs up the bus.
+- Use a dedicated executor or `CompletableFuture.supplyAsync` for I/O-heavy work.
+
+## Schema management
+
+NetworkCore owns the *pool*, not your schema. Each plugin is responsible for creating and migrating its own tables.
+
+Conventions:
+- **Table prefix per plugin.** The Staff plugin prefixes everything with `staff_`. Pick something unique to your plugin so two plugins don't fight over `players`.
+- **Bootstrap on startup.** In your plugin's `start()`, run a `CREATE TABLE IF NOT EXISTS ...` for every table you need. This makes a fresh install just-work without manual setup.
+- **Migrations as numbered scripts.** When you change a schema, add a `migrations/002_add_email_column.sql` and a tiny runner that tracks applied migrations in a `<plugin>_schema_version` table. Don't reach for Flyway/Liquibase until you've added a third migration - those frameworks earn their weight on real projects, not on the second migration.
+
+## Configuration
+
+See the [mysql section in 03_Configuration.md](03_Configuration.md#mysql). Default is `enabled: false` so a server that doesn't have MySQL configured doesn't crash on boot. Flip to `true` once you've put credentials in place via `MYSQL_PASSWORD` env var.
+
+## What you see in /networkcore status
+
+When MySQL is healthy:
+```
+Database: ok (active=2 idle=8 total=10)
+```
+
+When disabled:
+```
+Database: disabled
+```
+
+When configured but failing:
+```
+Database: unhealthy
+```
+
+If you ever see "unhealthy", check the boot log for the connection error and verify host/port/credentials.
+
+## What is *not* in the box
+
+- **No ORM.** Plain `DataSource` only. Pick your own.
+- **No migration framework.** Bootstrap with `CREATE TABLE IF NOT EXISTS` per plugin.
+- **No automatic encryption at rest.** That's MySQL's job, not the plugin's. Use MySQL Enterprise's TDE or AWS RDS encryption.
+- **No read replicas.** Single pool to a single MySQL endpoint. Read replicas are an MySQL Router or ProxySQL concern, not a Hytale plugin concern.
+
+## Sizing the pool
+
+`max_pool_size = 10` is fine for a single server with a handful of plugins. Rules of thumb:
+
+- Each plugin doing heavy queries needs maybe 2-4 connections worth of headroom.
+- The pool is per Hytale-server-instance, not network-wide. If you have 5 servers each with pool=10, MySQL needs to handle 50 concurrent connections.
+- Make sure MySQL's `max_connections` is comfortably above the *sum* of all pools that point at it.
+
+Don't crank `max_pool_size` to "fix" pool exhaustion. Pool exhaustion is almost always a leaked connection or a query that's holding the connection too long. Find the leak, then re-evaluate sizing.