@open-core/database 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 OpenCore Framework Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @open-core/database
+
+Database adapter package for **OpenCore**. It provides `DatabaseContract` implementations and registration helpers so you can access databases through the framework’s standard API (`query`, `single`, `scalar`, `execute`, `insert`, `transaction`).
+
+## Purpose
+
+This package aims to:
+
+- Allow selecting the database backend **only via configuration** (convars), without changing data-access code.
+- Keep compatibility with OpenCore’s database abstraction (`DatabaseService`).
+- Provide production-ready adapters for:
+  - PostgreSQL (`postgres`)
+  - MySQL (`mysql2`)
+
+## How it works (high level)
+
+OpenCore resolves the database adapter using `opencore_db_adapter` and a factory registered through `registerDatabaseAdapterFactory(name, factory)`.
+
+This package exposes:
+
+- `registerPostgresAdapter()` (registers `opencore_db_adapter=postgres`)
+- `registerMysql2Adapter()` (registers `opencore_db_adapter=mysql2`)
+
+Once the adapter is registered, you can initialize OpenCore’s database service and use the standard database functions.
+
+## Installation
+
+```bash
+pnpm add @open-core/database
+```
+
+> This package includes driver dependencies (`pg`, `mysql2`).
+
+## Quickstart
+
+1. Register the adapters at the start of your server/resource.
+2. Configure `opencore_db_adapter` and the driver-specific convars.
+3. Initialize the framework database module.
+
+Example:
+
+```ts
+import { registerPostgresAdapter, registerMysql2Adapter } from '@open-core/database'
+import { Server } from '@open-core/framework'
+
+registerPostgresAdapter() // or registerMysql2Adapter()
+Server.initDatabase()
+// we highly recommend using the databaseService by injection
+const rows = await Server.query('SELECT 1 as ok')
+```
+
+## Configuration
+
+- `opencore_db_adapter`
+  - `postgres`
+  - `mysql2`
+
+Guides:
+
+- [PostgreSQL](./docs/postgresql.md)
+- [MySQL](./docs/mysql.md)
+- [ORM integration](./docs/orm-integration.md)
+
+## Compatibility notes
+
+- Transactions using the oxmysql-style named shared parameters format `@name` (`TransactionSharedParams`) are not supported by these adapters. Use the **tuple** or **object** format with positional parameters.
+- For PostgreSQL, to obtain `insertId` reliably, use `RETURNING id`.

package/dist/adapters/index.d.ts

@@ -0,0 +1,2 @@
+export { Mysql2Adapter } from './mysql.adapter';
+export { PostgresAdapter } from './postgresql.adapter';

package/dist/adapters/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresAdapter = exports.Mysql2Adapter = void 0;
+var mysql_adapter_1 = require("./mysql.adapter");
+Object.defineProperty(exports, "Mysql2Adapter", { enumerable: true, get: function () { return mysql_adapter_1.Mysql2Adapter; } });
+var postgresql_adapter_1 = require("./postgresql.adapter");
+Object.defineProperty(exports, "PostgresAdapter", { enumerable: true, get: function () { return postgresql_adapter_1.PostgresAdapter; } });

package/dist/adapters/mysql.adapter.d.ts

@@ -0,0 +1,12 @@
+import { Server } from '@open-core/framework';
+import { type Pool } from 'mysql2/promise';
+export declare class Mysql2Adapter extends Server.DatabaseContract {
+    private pool;
+    constructor(pool?: Pool);
+    query<T = any>(sql: string, params?: any[]): Promise<T[]>;
+    single<T = any>(sql: string, params?: any[]): Promise<T | null>;
+    scalar<T = any>(sql: string, params?: any[]): Promise<T | null>;
+    execute(sql: string, params?: any[]): Promise<Server.ExecuteResult>;
+    insert(sql: string, params?: any[]): Promise<Server.InsertResult>;
+    transaction(queries: Server.TransactionInput, sharedParams?: Server.TransactionSharedParams): Promise<boolean>;
+}

package/dist/adapters/mysql.adapter.js

@@ -0,0 +1,114 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Mysql2Adapter = void 0;
+const framework_1 = require("@open-core/framework");
+const promise_1 = __importDefault(require("mysql2/promise"));
+function getRequiredConvar(name) {
+    const value = globalThis.GetConvar?.(name, '')?.trim() ?? '';
+    if (!value)
+        throw new Error(`[OpenCoreDB] Missing required convar '${name}'`);
+    return value;
+}
+function getOptionalConvar(name, fallback = '') {
+    return globalThis.GetConvar?.(name, fallback)?.trim() ?? fallback;
+}
+function getOptionalIntConvar(name, fallback) {
+    const raw = getOptionalConvar(name, String(fallback));
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : fallback;
+}
+function buildPoolOptionsFromConvars() {
+    const url = getOptionalConvar('opencore_mysql_url', '');
+    const connectionLimit = getOptionalIntConvar('opencore_mysql_pool_max', 10);
+    if (url) {
+        return {
+            uri: url,
+            connectionLimit,
+        };
+    }
+    return {
+        host: getRequiredConvar('opencore_mysql_host'),
+        port: getOptionalIntConvar('opencore_mysql_port', 3306),
+        user: getRequiredConvar('opencore_mysql_user'),
+        password: getRequiredConvar('opencore_mysql_password'),
+        database: getRequiredConvar('opencore_mysql_database'),
+        connectionLimit,
+    };
+}
+function normalizeTransactionQueries(queries, sharedParams) {
+    if (queries.length === 0)
+        return [];
+    const first = queries[0];
+    if (typeof first === 'string') {
+        if (sharedParams && Object.keys(sharedParams).length > 0) {
+            throw new Error("[OpenCoreDB] MySQL adapter doesn't support named sharedParams transactions (the '@name' format). Use tuple/object format with positional params.");
+        }
+        return queries.map((sql) => ({ sql }));
+    }
+    if (Array.isArray(first)) {
+        return queries.map(([sql, params]) => ({ sql, params }));
+    }
+    return queries.map((q) => ({
+        sql: q.query,
+        params: q.values,
+    }));
+}
+class Mysql2Adapter extends framework_1.Server.DatabaseContract {
+    pool;
+    constructor(pool) {
+        super();
+        this.pool = pool ?? promise_1.default.createPool(buildPoolOptionsFromConvars());
+    }
+    async query(sql, params) {
+        const [rows] = await this.pool.query(sql, params);
+        return rows ?? [];
+    }
+    async single(sql, params) {
+        const rows = await this.query(sql, params);
+        return rows[0] ?? null;
+    }
+    async scalar(sql, params) {
+        const row = await this.single(sql, params);
+        if (!row)
+            return null;
+        const firstKey = Object.keys(row)[0];
+        return (firstKey ? row[firstKey] : null) ?? null;
+    }
+    async execute(sql, params) {
+        const [result] = await this.pool.execute(sql, params);
+        return { affectedRows: result.affectedRows ?? 0 };
+    }
+    async insert(sql, params) {
+        const [result] = await this.pool.execute(sql, params);
+        const insertId = typeof result.insertId === 'number' ? result.insertId : Number(result.insertId ?? 0);
+        return { insertId: Number.isFinite(insertId) ? insertId : 0 };
+    }
+    async transaction(queries, sharedParams) {
+        const normalized = normalizeTransactionQueries(queries, sharedParams);
+        if (normalized.length === 0)
+            return true;
+        const conn = await this.pool.getConnection();
+        try {
+            await conn.beginTransaction();
+            for (const q of normalized) {
+                await conn.query(q.sql, q.params);
+            }
+            await conn.commit();
+            return true;
+        }
+        catch (e) {
+            try {
+                await conn.rollback();
+            }
+            catch { }
+            return false;
+        }
+        finally {
+            conn.release();
+        }
+    }
+}
+exports.Mysql2Adapter = Mysql2Adapter;

package/dist/adapters/postgresql.adapter.d.ts

@@ -0,0 +1,12 @@
+import { Server } from '@open-core/framework';
+import { Pool } from 'pg';
+export declare class PostgresAdapter extends Server.DatabaseContract {
+    private pool;
+    constructor(pool?: Pool);
+    query<T = any>(sql: string, params?: any[]): Promise<T[]>;
+    single<T = any>(sql: string, params?: any[]): Promise<T | null>;
+    scalar<T = any>(sql: string, params?: any[]): Promise<T | null>;
+    execute(sql: string, params?: any[]): Promise<Server.ExecuteResult>;
+    insert(sql: string, params?: any[]): Promise<Server.InsertResult>;
+    transaction(queries: Server.TransactionInput, sharedParams?: Server.TransactionSharedParams): Promise<boolean>;
+}

package/dist/adapters/postgresql.adapter.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresAdapter = void 0;
+const framework_1 = require("@open-core/framework");
+const pg_1 = require("pg");
+const pg_placeholders_1 = require("../sql/pg-placeholders");
+function getRequiredConvar(name) {
+    const value = globalThis.GetConvar?.(name, '')?.trim() ?? '';
+    if (!value)
+        throw new Error(`[OpenCoreDB] Missing required convar '${name}'`);
+    return value;
+}
+function getOptionalConvar(name, fallback = '') {
+    return globalThis.GetConvar?.(name, fallback)?.trim() ?? fallback;
+}
+function getOptionalIntConvar(name, fallback) {
+    const raw = getOptionalConvar(name, String(fallback));
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : fallback;
+}
+function buildPoolConfigFromConvars() {
+    const url = getOptionalConvar('opencore_pg_url', '');
+    if (url) {
+        return {
+            connectionString: url,
+            max: getOptionalIntConvar('opencore_pg_pool_max', 10),
+        };
+    }
+    return {
+        host: getRequiredConvar('opencore_pg_host'),
+        port: getOptionalIntConvar('opencore_pg_port', 5432),
+        user: getRequiredConvar('opencore_pg_user'),
+        password: getRequiredConvar('opencore_pg_password'),
+        database: getRequiredConvar('opencore_pg_database'),
+        max: getOptionalIntConvar('opencore_pg_pool_max', 10),
+    };
+}
+function normalizeTransactionQueries(queries, sharedParams) {
+    if (queries.length === 0)
+        return [];
+    const first = queries[0];
+    if (typeof first === 'string') {
+        if (sharedParams && Object.keys(sharedParams).length > 0) {
+            throw new Error("[OpenCoreDB] Postgres adapter doesn't support named sharedParams transactions (the '@name' format). Use tuple/object format with positional params.");
+        }
+        return queries.map((q) => ({ sql: q }));
+    }
+    if (Array.isArray(first)) {
+        return queries.map(([sql, params]) => ({ sql, params }));
+    }
+    return queries.map((q) => ({
+        sql: q.query,
+        params: q.values,
+    }));
+}
+class PostgresAdapter extends framework_1.Server.DatabaseContract {
+    pool;
+    constructor(pool) {
+        super();
+        this.pool = pool ?? new pg_1.Pool(buildPoolConfigFromConvars());
+    }
+    async query(sql, params) {
+        const pgSql = (0, pg_placeholders_1.toPgPlaceHolders)(sql);
+        const res = await this.pool.query(pgSql, params);
+        return (res.rows ?? []);
+    }
+    async single(sql, params) {
+        const rows = await this.query(sql, params);
+        return rows[0] ?? null;
+    }
+    async scalar(sql, params) {
+        const row = await this.single(sql, params);
+        if (!row)
+            return null;
+        const firstKey = Object.keys(row)[0];
+        return (firstKey ? row[firstKey] : null) ?? null;
+    }
+    async execute(sql, params) {
+        const pgSql = (0, pg_placeholders_1.toPgPlaceHolders)(sql);
+        const res = await this.pool.query(pgSql, params);
+        return { affectedRows: res.rowCount ?? 0 };
+    }
+    async insert(sql, params) {
+        const pgSql = (0, pg_placeholders_1.toPgPlaceHolders)(sql);
+        const res = await this.pool.query(pgSql, params);
+        const firstRow = res.rows?.[0];
+        const insertIdRaw = firstRow?.id ?? firstRow?.insertId ?? firstRow?.insert_id ?? firstRow?.ID ?? null;
+        const insertId = typeof insertIdRaw === 'number' ? insertIdRaw : Number(insertIdRaw ?? 0);
+        return { insertId: Number.isFinite(insertId) ? insertId : 0 };
+    }
+    async transaction(queries, sharedParams) {
+        const normalized = normalizeTransactionQueries(queries, sharedParams);
+        if (normalized.length === 0)
+            return true;
+        const client = await this.pool.connect();
+        try {
+            await client.query('BEGIN');
+            for (const q of normalized) {
+                const pgSql = (0, pg_placeholders_1.toPgPlaceHolders)(q.sql);
+                await client.query(pgSql, q.params);
+            }
+            await client.query('COMMIT');
+            return true;
+        }
+        catch (e) {
+            try {
+                await client.query('ROLLBACK');
+            }
+            catch { }
+            return false;
+        }
+        finally {
+            client.release();
+        }
+    }
+}
+exports.PostgresAdapter = PostgresAdapter;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { registerPostgresAdapter, registerMysql2Adapter } from './register';
+export * from './adapters/index';

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerMysql2Adapter = exports.registerPostgresAdapter = void 0;
+var register_1 = require("./register");
+Object.defineProperty(exports, "registerPostgresAdapter", { enumerable: true, get: function () { return register_1.registerPostgresAdapter; } });
+Object.defineProperty(exports, "registerMysql2Adapter", { enumerable: true, get: function () { return register_1.registerMysql2Adapter; } });
+__exportStar(require("./adapters/index"), exports);

package/dist/register.d.ts

@@ -0,0 +1,2 @@
+export declare function registerPostgresAdapter(): void;
+export declare function registerMysql2Adapter(): void;

package/dist/register.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerPostgresAdapter = registerPostgresAdapter;
+exports.registerMysql2Adapter = registerMysql2Adapter;
+const server_1 = require("@open-core/framework/dist/runtime/server");
+const postgresql_adapter_1 = require("./adapters/postgresql.adapter");
+const mysql_adapter_1 = require("./adapters/mysql.adapter");
+let registered = false;
+function registerPostgresAdapter() {
+    if (registered)
+        return;
+    (0, server_1.registerDatabaseAdapterFactory)('postgres', () => new postgresql_adapter_1.PostgresAdapter());
+    registered = true;
+}
+function registerMysql2Adapter() {
+    if (registered)
+        return;
+    (0, server_1.registerDatabaseAdapterFactory)('mysql2', () => new mysql_adapter_1.Mysql2Adapter());
+    registered = true;
+}

package/dist/sql/pg-placeholders.d.ts

@@ -0,0 +1 @@
+export declare function toPgPlaceHolders(sql: string): string;

package/dist/sql/pg-placeholders.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPgPlaceHolders = toPgPlaceHolders;
+function toPgPlaceHolders(sql) {
+    let idx = 0;
+    return sql.replace(/\?/g, () => {
+        idx += 1;
+        return `$${idx}`;
+    });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@open-core/database",
+  "version": "0.1.0",
+  "type": "commonjs",
+  "description": "Database library for the Open Core framework with PostgreSQL and MySQL drivers.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "open-core",
+    "database",
+    "sql",
+    "postgres",
+    "postgresql",
+    "mysql",
+    "node",
+    "typescript"
+  ],
+  "author": "OpenCore Team",
+  "license": "ISC",
+  "packageManager": "pnpm@10.27.0",
+  "repository": {
+    "url": "https://github.com/newcore-network/opencore-database"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@open-core/framework": "^0.2.4",
+    "mysql2": "^3.16.0",
+    "pg": "^8.16.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "@types/pg": "^8.16.0",
+    "typescript": "^5.9.3"
+  }
+}