first commit

2026-01-15 22:38:46 +03:00
commit a70e9b7a79
58 changed files with 3980 additions and 0 deletions
--- a/docs/ru/api-query.md
+++ b/docs/ru/api-query.md
@@ -0,0 +1,33 @@
+# Query API (RU)
+
+Raw SQL через `api.query()` с биндингом параметров.
+
+## Execute
+
+```java
+int rows = api.query().execute(
+    "UPDATE players SET level = level + 1 WHERE id = ?",
+    java.util.Collections.singletonList(1)
+);
+```
+
+## Query
+
+```java
+List<String> names = api.query().query(
+    "SELECT name FROM players WHERE level >= ?",
+    java.util.Collections.singletonList(10),
+    rs -> rs.getString("name")
+);
+```
+
+## Транзакции
+
+```java
+try (Transaction tx = api.beginTransaction()) {
+    tx.execute("UPDATE players SET level = level + 1 WHERE id = ?", java.util.Collections.singletonList(1));
+    tx.commit();
+} catch (Exception ex) {
+    // rollback при ошибке
+}
+```
--- a/docs/ru/api-schema.md
+++ b/docs/ru/api-schema.md
@@ -0,0 +1,35 @@
+# Schema API (RU)
+
+Помощники для создания и обновления таблиц.
+
+## Пример: create table
+
+```java
+import com.andrewkydev.database.schema.ColumnSpec;
+import com.andrewkydev.database.schema.IndexSpec;
+import com.andrewkydev.database.schema.TableSpec;
+
+TableSpec table = TableSpec.builder("players")
+    .column(ColumnSpec.builder("id", "BIGINT").primaryKey(true).autoIncrement(true).nullable(false).build())
+    .column(ColumnSpec.builder("name", "VARCHAR(32)").nullable(false).build())
+    .index(new IndexSpec("players_name_idx", java.util.Arrays.asList("name"), false))
+    .build();
+
+api.schema().createTable(table);
+```
+
+## Методы
+
+```java
+api.schema().createDatabase("primalix");
+api.schema().dropDatabase("primalix");
+api.schema().createTable(spec);
+api.schema().dropTable("players");
+api.schema().addColumn("players", ColumnSpec.builder("level", "INT").build());
+api.schema().updateColumn("players", ColumnSpec.builder("level", "INT").nullable(false).build());
+api.schema().dropColumn("players", "level");
+api.schema().addIndex("players", new IndexSpec("players_name_idx", java.util.Arrays.asList("name"), false));
+api.schema().dropIndex("players", "players_name_idx");
+```
+
+У всех методов есть async версии с `CompletableFuture`.
--- a/docs/ru/config.md
+++ b/docs/ru/config.md
@@ -0,0 +1,40 @@
+# Конфигурация
+
+Файл `config.yml`:
+
+```yaml
+driver: "mysql"
+host: "localhost"
+port: 3306
+database: "primalix"
+username: "root"
+password: ""
+adminDatabase: "postgres"
+autoTransactions: true
+
+pool:
+  maxPoolSize: 10
+  minIdle: 2
+  connectionTimeoutMs: 30000
+  idleTimeoutMs: 600000
+  maxLifetimeMs: 1800000
+```
+
+## Поля
+
+- `driver`: `mysql` или `postgres`.
+- `host`: адрес БД.
+- `port`: порт БД.
+- `database`: основная база.
+- `username`: логин.
+- `password`: пароль.
+- `adminDatabase`: PostgreSQL админ‑база для create/drop database.
+- `autoTransactions`: оборачивать schema операции в транзакцию.
+
+## Pool
+
+- `maxPoolSize`: максимум соединений.
+- `minIdle`: минимум idle.
+- `connectionTimeoutMs`: таймаут подключения.
+- `idleTimeoutMs`: таймаут простоя.
+- `maxLifetimeMs`: максимальная жизнь соединения.
--- a/docs/ru/orm-query.md
+++ b/docs/ru/orm-query.md
@@ -0,0 +1,43 @@
+# ORM Query Builder (RU)
+
+Fluent builder над ORM.
+
+## База
+
+```java
+List<PlayerModel> top = api.orm().query(PlayerModel.class)
+    .where("level >= ?", 10)
+    .orderBy("level DESC")
+    .limit(10)
+    .list();
+```
+
+## Fluent Conditions
+
+```java
+import static com.andrewkydev.database.orm.Conditions.*;
+
+List<PlayerModel> players = api.orm().query(PlayerModel.class)
+    .where(eq("status", "ACTIVE").and(gt("level", 10)))
+    .orderBy("level DESC")
+    .list();
+```
+
+## Join + Group By + Having
+
+```java
+List<PlayerModel> rows = api.orm().query(PlayerModel.class)
+    .select("players.*")
+    .join("LEFT JOIN clans ON clans.id = players.clan_id")
+    .where("players.level >= ?", 10)
+    .groupBy("players.id")
+    .having("COUNT(clans.id) > ?", 0)
+    .orderBy("players.level DESC")
+    .limit(10, 0)
+    .list();
+```
+
+## Select Columns
+
+Если выбираете часть колонок, маппятся только они.
+Остальные поля остаются дефолтными.
--- a/docs/ru/orm-schema.md
+++ b/docs/ru/orm-schema.md
@@ -0,0 +1,30 @@
+# ORM Schema (RU)
+
+`OrmSchema` строит `TableSpec` на основе аннотаций.
+
+## Пример
+
+```java
+import com.andrewkydev.database.orm.OrmSchema;
+import com.andrewkydev.database.schema.SqlDialect;
+import com.andrewkydev.database.schema.TableSpec;
+
+TableSpec spec = OrmSchema.fromEntity(PlayerModel.class, SqlDialect.MYSQL);
+api.schema().createTable(spec);
+```
+
+## Маппинг типов
+
+По умолчанию:
+
+- `String` -> `VARCHAR(length)`
+- `int`/`Integer` -> `INT`
+- `long`/`Long` -> `BIGINT`
+- `short`/`Short` -> `SMALLINT`
+- `boolean`/`Boolean` -> `BOOLEAN` (PostgreSQL) или `TINYINT(1)` (MySQL)
+- `float`/`Float` -> `FLOAT`
+- `double`/`Double` -> `DOUBLE`
+- `UUID` -> `UUID` (PostgreSQL) или `CHAR(36)` (MySQL)
+- `@DbJson` -> `JSON` (MySQL) или `JSONB` (PostgreSQL)
+
+`@DbColumn(length, unique, nullable)` применяется автоматически.
--- a/docs/ru/orm.md
+++ b/docs/ru/orm.md
@@ -0,0 +1,119 @@
+# ORM (RU)
+
+Легковесный ORM: поля мапятся в колонки, без сложных связей.
+Есть sync и async версии.
+
+## Аннотации
+
+- `@DbEntity(table = "players")` - имя таблицы. По умолчанию snake_case.
+- `@DbColumn(name = "username")` - имя колонки.
+- `@DbColumn(type = "VARCHAR(32)")` - SQL тип для генерации схемы.
+- `@DbColumn(length = 32, unique = true, nullable = false)` - влияет на schema генерацию.
+- `@DbId(autoIncrement = true)` - primary key.
+- `@DbJson` - JSON поле.
+- `@DbTransient` - игнорировать поле.
+
+## Пример сущности
+
+```java
+@DbEntity(table = "players")
+public class PlayerModel {
+    @DbId(autoIncrement = true)
+    private long id;
+
+    @DbColumn(name = "username", nullable = false, unique = true, length = 32)
+    private String name;
+
+    @DbColumn
+    private int level;
+
+    @DbJson
+    private java.util.Map<String, Object> metadata;
+
+    @DbTransient
+    private String temp;
+
+    public PlayerModel() {
+    }
+}
+```
+
+## CRUD
+
+```java
+EntityManager orm = api.orm();
+
+orm.insert(entity);
+orm.update(entity);
+orm.delete(entity);
+PlayerModel player = orm.findById(PlayerModel.class, 1L);
+List<PlayerModel> all = orm.findAll(PlayerModel.class);
+PlayerModel one = orm.findOneWhere(PlayerModel.class, "level >= ?", java.util.Collections.singletonList(10));
+List<PlayerModel> many = orm.findWhere(PlayerModel.class, "level >= ?", java.util.Collections.singletonList(10));
+List<PlayerModel> paged = orm.findWhere(PlayerModel.class, "level >= ?", java.util.Collections.singletonList(10), "level DESC", 10, 0);
+long count = orm.count(PlayerModel.class, "level >= ?", java.util.Collections.singletonList(10));
+boolean exists = orm.exists(PlayerModel.class, "username = ?", java.util.Collections.singletonList("Steve"));
+int deleted = orm.deleteWhere(PlayerModel.class, "level < ?", java.util.Collections.singletonList(1));
+```
+
+## Query Builder
+
+```java
+EntityManager orm = api.orm();
+
+List<PlayerModel> top = orm.query(PlayerModel.class)
+    .where("level >= ?", 10)
+    .orderBy("level DESC")
+    .limit(10)
+    .list();
+
+boolean exists = orm.query(PlayerModel.class)
+    .where("username = ?", "Steve")
+    .exists();
+```
+
+## Fluent Conditions
+
+```java
+import static com.andrewkydev.database.orm.Conditions.*;
+
+List<PlayerModel> players = orm.query(PlayerModel.class)
+    .where(eq("status", "ACTIVE").and(gt("level", 10)))
+    .list();
+```
+
+## Join, Group By, Having
+
+```java
+List<PlayerModel> rows = orm.query(PlayerModel.class)
+    .select("players.*")
+    .join("LEFT JOIN clans ON clans.id = players.clan_id")
+    .groupBy("players.id")
+    .having("COUNT(clans.id) > ?", 0)
+    .list();
+```
+
+Если выбрать часть колонок, маппятся только они, остальные остаются дефолтными.
+
+## Auto ID
+
+Если `@DbId(autoIncrement = true)` и id пустой (0/null),
+`insert()` получает generated keys и прописывает id в объект.
+
+## Type Adapters
+
+UUID уже поддержан. Для других типов:
+
+```java
+orm.registerAdapter(SomeType.class, new TypeAdapter<SomeType>() {
+    @Override
+    public Object toDatabase(SomeType value) {
+        return value == null ? null : value.toString();
+    }
+
+    @Override
+    public SomeType fromDatabase(Object value) {
+        return value == null ? null : SomeType.parse(value.toString());
+    }
+});
+```
--- a/docs/ru/overview.md
+++ b/docs/ru/overview.md
@@ -0,0 +1,34 @@
+# Overview (RU)
+
+Database - SQL plugin for Lumi with MySQL/PostgreSQL, HikariCP pooling,
+schema helpers, raw SQL, and a lightweight ORM with fluent query builder.
+
+## Установка
+
+1. Соберите jar через Gradle.
+2. Поместите jar в папку plugins сервера.
+3. Запустите сервер один раз для генерации `config.yml`.
+
+## Доступ к API
+
+```java
+import com.andrewkydev.database.DatabaseProvider;
+import com.andrewkydev.database.DatabaseApi;
+
+DatabaseApi api = DatabaseProvider.get();
+```
+
+## Основные возможности
+
+### Auto ID после insert
+
+Если у поля есть `@DbId(autoIncrement = true)` и id пустой (0 или null),
+`insert()` получает generated keys и прописывает id в объект.
+
+### Snake case по умолчанию
+
+Если не задано `@DbEntity`/`@DbColumn`, имена берутся в snake_case.
+
+### Удобные ORM методы
+
+Доступны `findOneWhere`, `deleteWhere` и `findWhere` с сортировкой/лимитом/offset.