open-index/open-npm huggingface dataset:
npm package: @pma-network/pma-sql
Description: MySQL wrapper with promise-based async operations, connection pooling, and named parameters support
Latest version: 1.0.4

# 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

```bash
pnpm add @pma-network/pma-sql
```

Or with npm:

```bash
npm install @pma-network/pma-sql
```

## Quick Start

Set the connection string environment variable:

```bash
# 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:

```typescript
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:

```typescript
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:

```typescript
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:
```typescript
await db.query('SELECT * FROM users WHERE name = :name AND age > :age', {
  name: 'John',
  age: 18,
});
```

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

TypeScript with type definitions:
```typescript
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');
```