Extract platform-neutral SQL backend initialization

AdvancedCore/pom.xml

@@ -387,6 +387,12 @@
             <version>5.22.0</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.xerial</groupId>
+            <artifactId>sqlite-jdbc</artifactId>
+            <version>3.53.4.0</version>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>com.nickuc.login</groupId>
             <artifactId>api</artifactId>

AdvancedCore/src/main/java/com/bencodez/advancedcore/core/user/storage/sql/SqlBackendLogger.java

@@ -0,0 +1,12 @@
+package com.bencodez.advancedcore.core.user.storage.sql;
+
+public interface SqlBackendLogger {
+    SqlBackendLogger NO_OP = new SqlBackendLogger() {
+        @Override public void info(String message) {}
+        @Override public void warn(String message, Throwable error) {}
+    };
+
+    void info(String message);
+
+    void warn(String message, Throwable error);
+}

AdvancedCore/src/main/java/com/bencodez/advancedcore/core/user/storage/sql/SqlUserBackend.java

@@ -0,0 +1,34 @@
+package com.bencodez.advancedcore.core.user.storage.sql;
+
+import java.util.List;
+import java.util.Objects;
+import java.util.UUID;
+import java.util.function.Consumer;
+
+import com.bencodez.advancedcore.api.user.UserStorage;
+import com.bencodez.advancedcore.core.user.storage.SqlUserStorage;
+
+public interface SqlUserBackend extends AutoCloseable {
+    /** Materialized compatibility API is intentionally bounded by concrete SQL backends. */
+    int MAX_MATERIALIZED_USERS = 100_000;
+
+    UserStorage storageType();
+
+    SqlUserStorage user(UUID uuid);
+
+    List<UUID> enumerateUsers();
+
+    /**
+     * Streaming enumeration for large historical user tables. Concrete SQL backends
+     * override this to avoid first materializing every UUID in heap.
+     */
+    default void forEachUser(Consumer<UUID> consumer) {
+        Objects.requireNonNull(consumer, "consumer");
+        enumerateUsers().forEach(consumer);
+    }
+
+    boolean isOpen();
+
+    @Override
+    void close();
+}

AdvancedCore/src/main/java/com/bencodez/advancedcore/core/user/storage/sql/SqlUserBackendFactory.java

@@ -0,0 +1,30 @@
+package com.bencodez.advancedcore.core.user.storage.sql;
+
+import java.nio.file.Path;
+import java.util.Collection;
+import java.util.Objects;
+
+import com.bencodez.advancedcore.api.user.usercache.keys.UserDataKey;
+import com.bencodez.simpleapi.sql.mysql.config.MysqlConfig;
+
+/**
+ * Constructs SQL user backends from explicit platform-neutral inputs. Native
+ * platform adapters are responsible for translating their configuration and
+ * data-directory concepts before calling this factory.
+ */
+public final class SqlUserBackendFactory {
+    private SqlUserBackendFactory() {
+    }
+
+    public static SqliteUserBackend sqlite(Path dataDirectory, String databaseName, String tableName,
+            Collection<? extends UserDataKey> keys, SqlBackendLogger logger) {
+        Objects.requireNonNull(keys, "keys");
+        return new SqliteUserBackend(dataDirectory, databaseName, tableName, SqlUserSchema.fromKeys(keys), logger);
+    }
+
+    public static MysqlUserBackend mysql(String baseTableName, MysqlConfig config,
+            Collection<? extends UserDataKey> keys, SqlBackendLogger logger) {
+        Objects.requireNonNull(keys, "keys");
+        return new MysqlUserBackend(baseTableName, config, SqlUserSchema.fromKeys(keys), logger);
+    }
+}

AdvancedCore/src/main/java/com/bencodez/advancedcore/core/user/storage/sql/SqlUserSchema.java

@@ -0,0 +1,81 @@
+package com.bencodez.advancedcore.core.user.storage.sql;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Objects;
+
+import com.bencodez.advancedcore.api.user.usercache.keys.UserDataKey;
+import com.bencodez.advancedcore.api.user.usercache.keys.UserDataKeyBoolean;
+import com.bencodez.advancedcore.api.user.usercache.keys.UserDataKeyInt;
+import com.bencodez.simpleapi.sql.DataType;
+
+public final class SqlUserSchema {
+    public static final String UUID_COLUMN = "uuid";
+
+    public record ColumnDefinition(String name, String sqlType, DataType dataType) {
+        public ColumnDefinition {
+            Objects.requireNonNull(name, "name");
+            Objects.requireNonNull(sqlType, "sqlType");
+            Objects.requireNonNull(dataType, "dataType");
+            if (name.isBlank()) throw new IllegalArgumentException("Column name cannot be blank");
+            if (sqlType.isBlank()) throw new IllegalArgumentException("SQL type cannot be blank");
+        }
+    }
+
+    private final Map<String, ColumnDefinition> columnsByLowerName;
+
+    private SqlUserSchema(Map<String, ColumnDefinition> columnsByLowerName) {
+        this.columnsByLowerName = Collections.unmodifiableMap(new LinkedHashMap<>(columnsByLowerName));
+    }
+
+    public static Builder builder() { return new Builder(); }
+
+    public static SqlUserSchema fromKeys(Collection<? extends UserDataKey> keys) {
+        Builder builder = builder();
+        for (UserDataKey key : Objects.requireNonNull(keys, "keys")) {
+            DataType type = DataType.STRING;
+            if (key instanceof UserDataKeyInt) type = DataType.INTEGER;
+            else if (key instanceof UserDataKeyBoolean) type = DataType.BOOLEAN;
+            builder.column(key.getKey(), key.getColumnType(), type);
+        }
+        return builder.build();
+    }
+
+    public List<ColumnDefinition> columns() { return new ArrayList<>(columnsByLowerName.values()); }
+
+    public ColumnDefinition column(String name) {
+        if (name == null) return null;
+        return columnsByLowerName.get(name.toLowerCase(Locale.ROOT));
+    }
+
+    public boolean contains(String name) { return column(name) != null; }
+
+    public static final class Builder {
+        private final Map<String, ColumnDefinition> columns = new LinkedHashMap<>();
+
+        private Builder() {
+            columns.put(UUID_COLUMN, new ColumnDefinition(UUID_COLUMN, "VARCHAR(37)", DataType.STRING));
+        }
+
+        public Builder column(String name, String sqlType, DataType dataType) {
+            Objects.requireNonNull(name, "name");
+            if (UUID_COLUMN.equalsIgnoreCase(name)) {
+                throw new IllegalArgumentException("Column name 'uuid' is reserved for user identity");
+            }
+            String canonical = name.toLowerCase(Locale.ROOT);
+            ColumnDefinition existing = columns.get(canonical);
+            if (existing != null) {
+                throw new IllegalArgumentException("Duplicate SQL column name: " + name + " conflicts with " + existing.name());
+            }
+            columns.put(canonical, new ColumnDefinition(name, sqlType, dataType));
+            return this;
+        }
+
+        public SqlUserSchema build() { return new SqlUserSchema(columns); }
+    }
+}