pma-sql

MySQL wrapper built on mysql2 with promise-based async operations, connection pooling, and named parameter support.

Features

• Auto-configuration from environment variables
• Promise-based async operations
• Connection pooling
• Named parameters (:paramName) and positional (?) placeholders
• Full TypeScript support
• Transaction handling with automatic rollback
• Resource-specific connection strings for FiveM

Installation

pnpm add @pma-network/pma-sql

Or with npm:

npm install @pma-network/pma-sql

Quick Start

Set the connection string environment variable:

# server.cfg (resource-specific):
set pma_characters_connection_string "mysql://user:password@localhost:3306/fivem"

# server.cfg (global fallback):
set mysql_connection_string "mysql://user:password@localhost:3306/fivem"

# Node.js:
export mysql_connection_string="mysql://user:password@localhost:3306/mydb"

Import and use:

import db from 'pma-sql';

const users = await db.query('SELECT * FROM users WHERE age > :age', { age: 18 });
const result = await db.insert('INSERT INTO users (name, sex, identifier) VALUES (:name, :sex, :identifier)', {
  name: 'John Doe',
  sex: 'm',
  identifier: 'discord:123456789',
});

Usage

Manual Configuration

Configure the default instance programmatically:

import db from 'pma-sql';

db.configure({
  host: 'localhost',
  user: 'root',
  password: 'password',
  database: 'mydb',
  connectionLimit: 10,
});

const users = await db.query('SELECT * FROM users');

Custom Instances

Create multiple database connections:

import { MySQL } from 'pma-sql';

const db1 = new MySQL({
  host: 'localhost',
  user: 'root',
  password: 'password',
  database: 'mydb',
});

const db2 = new MySQL({
  connectionString: 'mysql://user:password@remote:3306/otherdb',
});

API Reference

Configuration

Configuration is read using GetConvar (FiveM) with process.env fallback.

Priority order:

1. Resource-specific: {resource_name}_connection_string

   • Resource name detected via GetCurrentResourceName()
   • Dashes converted to underscores: pma-characters → pma_characters_connection_string

2. Global fallback: mysql_connection_string

Connection string format: mysql://username:password@hostname:port/database

Required: mysql:// protocol, username, hostname, database name

Optional: password, port (default: 3306)

Examples

Named parameters:

await db.query('SELECT * FROM users WHERE name = :name AND age > :age', {
  name: 'John',
  age: 18,
});

Positional parameters:

await db.query('SELECT * FROM users WHERE name = ? AND age > ?', ['John', 18]);

TypeScript with type definitions:

import { MySQL, type RowDataPacket } from 'pma-sql';

interface User extends RowDataPacket {
  id: number;
  name: string;
  email: string;
}

const users = await db.query<User[]>('SELECT * FROM users');