134 lines
7.8 KiB
Markdown
134 lines
7.8 KiB
Markdown
# Persistence & Database
|
|
|
|
**Packages:** `me.bobert.netneutrality.db` (session/migration),
|
|
`me.bobert.netneutrality.db` (entities, repositories, services).
|
|
**Resources:** `hibernate.cfg.xml`, `db/migration/V1__initial_schema.sql`,
|
|
`db/migration/V2__task_type_id.sql`.
|
|
|
|
## Stack
|
|
|
|
| Concern | Technology |
|
|
|------------|-------------------------------------------------------------------------------|
|
|
| ORM | Hibernate 7.1.9 (Jakarta JPA) |
|
|
| Engine | MariaDB 11 (per `docker-compose.yml`), MySQL Connector/J 9.7.0 driver, InnoDB |
|
|
| Pooling | HikariCP (via `hibernate-hikaricp`) |
|
|
| Migrations | Flyway 11.20.3 (`flyway-core` + `flyway-mysql`) |
|
|
|
|
Configuration is externalized via `Settings` (env vars / `bot.properties`):
|
|
`MYSQL_HOST`, `MYSQL_PORT`, `MYSQL_USER`, `MYSQL_PASSWORD`, `MYSQL_DATABASE`.
|
|
|
|
## Session & migration lifecycle
|
|
|
|
Both are wired in at [startup](architecture.md#startup-lifecycle):
|
|
|
|
1. **`SessionManager.getSessionFactory()`** — lazily builds the Hibernate `SessionFactory`. It reads
|
|
the static config from `hibernate.cfg.xml` (dialect `MySQLDialect`, driver
|
|
`com.mysql.cj.jdbc.Driver`, the Hikari connection provider, and the mapped entity list) and
|
|
overrides the JDBC url/user/password from environment variables:
|
|
|
|
```java
|
|
settings.put(Environment.JAKARTA_JDBC_URL,
|
|
String.format("jdbc:mysql://%s:%s/%s", dbHost, dbPort, dbName));
|
|
settings.put(Environment.JAKARTA_JDBC_USER, dbUser);
|
|
settings.put(Environment.JAKARTA_JDBC_PASSWORD, dbPass);
|
|
```
|
|
|
|
2. **`DatabaseMigration.migrate()`** — runs `flyway.migrate()` against the same database, applying the
|
|
versioned scripts under `src/main/resources/db/migration/` (starting with
|
|
`V1__initial_schema.sql`). The Flyway Maven plugin (`flyway-dev.sh`/`.ps1`) is available for local
|
|
development, using `FLYWAY_URL` / `FLYWAY_USER` / `FLYWAY_PASSWORD`.
|
|
|
|
3. **`SessionManager.shutdown()`** — destroys the service registry / releases the pool on shutdown.
|
|
|
|
Repositories obtain sessions through the factory; transactional access uses helpers in
|
|
[`JpaUtils`](utilities-and-bootstrap.md) (open session, run in a transaction, close).
|
|
|
|
## Entity catalog
|
|
|
|
Entities live in `me.bobert.netneutrality.db.entities` and are prefixed with `O`. `OGuild` is the hub
|
|
of a star-shaped model; most other tables reference `guild_id` with `ON DELETE CASCADE`.
|
|
|
|
| Entity | Table | Key | Relationships / notes |
|
|
|-----------------|------------------|--------------------------|--------------------------------------------------------------------------------------------------------|
|
|
| `OGuild` | `guilds` | `guild_id` (String) | Central entity; one-to-many with settings, blacklist, log messages, logging. |
|
|
| `OGuildSetting` | `guild_settings` | `id` (auto int) | Many-to-one `OGuild`; key/value guild settings. |
|
|
| `OBlacklist` | `blacklist` | `id` (auto int) | Many-to-one `OGuild`; blacklisted words. |
|
|
| `OLogging` | `logging` | `OLoggingId` (composite) | Composite key `guild_id` + `channel_id`; `@MapsId` to `OGuild`; debug/error log channel config. |
|
|
| `OLoggingId` | — (embeddable) | — | `@Embeddable`/`@IdClass` for the composite key. |
|
|
| `OLogMessage` | `log_message` | `id` (auto int) | Many-to-one `OGuild`; message logging history. |
|
|
| `OTask` | `tasks` | `id` (auto int) | [Persistable task](tasks.md#31-persistable-tasks) state; unique `task_id`, `task_class` holds the logical `typeId`, JSON `payload`. |
|
|
| `OWebUser` | `web_users` | `id` (String) | Web dashboard user (tokens/expiry). *Present in schema & code but not listed in `hibernate.cfg.xml`.* |
|
|
|
|
### ER overview
|
|
|
|
```
|
|
┌───────────────┐
|
|
│ OGuild │ (guilds.guild_id)
|
|
└───────┬───────┘
|
|
┌───────────┬───────┼────────────┬─────────────┐
|
|
▼ ▼ ▼ ▼ ▼
|
|
OGuildSetting OBlacklist OLogging OLogMessage (…)
|
|
guild_settings blacklist logging log_message
|
|
(FK guild) (FK guild) (PK guild+ (FK guild)
|
|
channel)
|
|
|
|
OTask (tasks) OWebUser (web_users) ── standalone
|
|
```
|
|
|
|
`OTask` and `OWebUser` are not tied to the guild graph.
|
|
|
|
## Repository layer
|
|
|
|
A lightweight generic repository pattern is used.
|
|
|
|
- **`Repository<O>`** (interface) — generic CRUD: `findAll()`, `findById(String)`, `save(O)` (via
|
|
`session.merge()`), `deleteBy(String)`.
|
|
- **`BlacklistRepository`** — find-by-guild and case-insensitive word lookups.
|
|
- **`GuildRepository`** — CRUD for guilds.
|
|
- **`GuildSettingRepository`** — set/get setting values; removes rows that equal the default value.
|
|
- **`MessageRepository`** — message logging / edit history.
|
|
- **`TaskRepository`** — CRUD for `OTask` rows (used by the task persistence flow).
|
|
|
|
## Service layer
|
|
|
|
Services wrap repositories with business logic and **caching**.
|
|
|
|
- **`GuildService`** — gateway for guild operations; caches one `GuildService` per guild id
|
|
(`ConcurrentHashMap`); `findOrCreate` guarantees a guild row exists; `deleteGuild()` on leave;
|
|
`isDebugEnabled()` / debug-channel helpers used by [`EventsHandler`](events.md) and
|
|
[`LogHandler`](utilities-and-bootstrap.md#loghandler).
|
|
- **`BlacklistService`** — maintains a `blacklistCache` (guild id → set of words) for fast message
|
|
filtering.
|
|
- **`GuildSettingService`** — reads/writes guild settings backed by [`GSettings`](#gsettings); caches
|
|
values in `settingsCache` and reloads on change; used by the
|
|
[web API settings endpoints](web-api.md).
|
|
- **`TaskService`** — serializes [`PersistableTask`](tasks.md#31-persistable-tasks) instances to JSON
|
|
for the `tasks` table, keyed by the task's stable `typeId()` in `task_class`, and reconstructs them
|
|
at startup via [`PersistableTaskRegistry`](tasks.md#persistabletaskregistry--discovery-and-restore).
|
|
Rows with an unknown `task_class` are logged and skipped.
|
|
|
|
## GSettings
|
|
|
|
`GSettings` is an **enum** of the available per-guild configuration keys and their defaults:
|
|
|
|
| Setting | Default |
|
|
|-------------------------|---------|
|
|
| `MUSIC_ROLE` | (none) |
|
|
| `MUSIC_CHANNEL` | (none) |
|
|
| `MUSIC_VOLUME` | `30` |
|
|
| `MUSIC_MAXPLAYLISTSIZE` | `20` |
|
|
|
|
`GuildSettingService` looks up an `OGuildSetting` row by the enum `name()`; if no row exists for a
|
|
guild/setting, the enum's `defaultValue` is used. This is how `MusicCommand` obtains the guild's music
|
|
role/channel and how `ConfigureCommand` persists changes.
|
|
|
|
## Schema (`V1__initial_schema.sql`)
|
|
|
|
The initial migration creates the tables backing the entities above (`guilds`, `guild_settings`,
|
|
`blacklist`, `logging`, `log_message`, `tasks`, `web_users`), with `guild_id` foreign keys and
|
|
`ON DELETE CASCADE` from the guild-scoped tables to `guilds`. Subsequent schema changes should be
|
|
added as new `V3__…`, `V4__…` Flyway scripts in the same directory.
|
|
|
|
`V2__task_type_id.sql` rewrites `tasks.task_class` from the old fully-qualified class names to the
|
|
stable logical `typeId` (e.g. `emoji-reaction-role`), so previously persisted rows remain loadable.
|