Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/pardnio/node-mysql-pool

A MySQL connection pool solution designed specifically for PHP, featuring intuitive chaining syntax that integrates query builder capabilities with read-write separation.
https://github.com/pardnio/node-mysql-pool

chain-syntax mysql nodejs pardnchiu typescript

Last synced: about 1 month ago
JSON representation

A MySQL connection pool solution designed specifically for PHP, featuring intuitive chaining syntax that integrates query builder capabilities with read-write separation.

Awesome Lists containing this project

README 

          
# MySQLPool



> A MySQL connection pool solution designed specifically for Nodejs, featuring intuitive chaining syntax that integrates query builder capabilities with read-write separation.



[![npm](https://img.shields.io/npm/v/@pardnchiu/mysql-pool)](https://www.npmjs.com/package/@pardnchiu/mysql-pool)



## Features



- **Dual Connection Pools**: Separate read and write database connections

- **Query Builder**: Fluent interface for building SQL queries

- **Environment Configuration**: Easy setup using environment variables

- **Connection Management**: Automatic connection pooling and cleanup

- **Slow Query Detection**: Automatic logging of queries taking over 20ms

- **JOIN Operations**: Support for INNER, LEFT, and RIGHT joins

- **CRUD Operations**: Complete Create, Read, Update, Delete functionality

- **UPSERT Support**: Insert or update on duplicate key



## Installation



```bash

npm install @pardnchiu/mysql-pool

```



## Environment Configuration



Set up your database connections using environment variables:



### Read Database (Optional)

```env

DB_READ_HOST=localhost

DB_READ_PORT=3306

DB_READ_USER=read_user

DB_READ_PASSWORD=read_password

DB_READ_DATABASE=your_database

DB_READ_CHARSET=utf8mb4

DB_READ_CONNECTION=8

```



### Write Database (Required for write operations)

```env

DB_WRITE_HOST=localhost

DB_WRITE_PORT=3306

DB_WRITE_USER=write_user

DB_WRITE_PASSWORD=write_password

DB_WRITE_DATABASE=your_database

DB_WRITE_CHARSET=utf8mb4

DB_WRITE_CONNECTION=4

```



## Quick Start



```javascript

import MySQLPool from "@pardnchiu/mysql-pool";



// init pool

await MySQLPool.init();



// simple query

const users = await MySQLPool

  .table("users")

  .where("status", "active")

  .get();



// Close connections when done

await MySQLPool.close();

```



## API Reference



### Initialization



#### `init(): Promise`

Initialize the database connection pools.



```javascript

await MySQLPool.init();

```



#### `close(): Promise`

Close all database connections.



```javascript

await MySQLPool.close();

```



### Query Builder Methods



#### `table(tableName: string, target?: "read" | "write"): MySQLPool`

Set the target table and target pool



```javascript

MySQLPool.table("users");           // use read pool

MySQLPool.table("users", "write");  // use write pool

```



#### `select(...fields: string[]): MySQLPool`

Specify columns to select.



```javascript

MySQLPool.table("users").select("id", "name", "email");

MySQLPool.table("users").select("COUNT(*) as total");

```



#### `where(column: string, operator: any, value?: any): MySQLPool`

Add WHERE conditions.



```javascript

// Basic where

MySQLPool.table("users").where("id", 1);

MySQLPool.table("users").where("age", ">", 18);



// LIKE operator (automatically adds % wildcards)

MySQLPool.table("users").where('name', "LIKE", "John");



// IN operator

MySQLPool.table("users").where("id", "IN", [1, 2, 3]);

```



#### JOIN Operations



```javascript

// INNER JOIN

MySQLPool.table("users")

  .innerJoin("profiles", "users.id", "profiles.user_id");



// LEFT JOIN

MySQLPool.table("users")

  .leftJoin("orders", "users.id", "orders.user_id");



// RIGHT JOIN with custom operator

MySQLPool.table("users")

  .rightJoin("posts", "users.id", "!=", "posts.author_id");

```



#### `orderBy(column: string, direction?: "ASC" | "DESC"): MySQLPool`

Add ORDER BY clause.



```javascript

MySQLPool.table("users").orderBy("created_at", "DESC");

MySQLPool.table("users").orderBy("name"); // Defaults to ASC

```



#### `limit(num: number): MySQLPool`

Limit the number of results.



```javascript

MySQLPool.table("users").limit(10);

```



#### `offset(num: number): MySQLPool`

Skip a number of records.



```javascript

MySQLPool.table("users").offset(20).limit(10); // Pagination

```



#### `total(): MySQLPool`

Include total count in results (adds COUNT(*) OVER()).



```javascript

const results = await MySQLPool

  .table("users")

  .total()

  .limit(10)

  .get();

// Results will include 'total' field with complete count

```



### Data Operations



#### `get(): Promise`

Execute SELECT query and return results.



```javascript

const users = await MySQLPool

  .table("users")

  .where("status", "active")

  .orderBy("created_at", "DESC")

  .get();

```



#### `insert(data: Record): Promise`

Insert a new record.



```javascript

const userId = await MySQLPool

  .table("users")

  .insert({

    name: "John Doe",

    email: "john@example.com",

    created_at: "NOW()"

  });

```



#### `update(data?: Record): Promise`

Update existing records.



```javascript

// Update with data

const result = await MySQLPool

  .table("users")

  .where("id", 1)

  .update({

    name: "Jane Doe",

    updated_at: "NOW()"

  });



// Update using increase() method

await MySQLPool

  .table("users")

  .where("id", 1)

  .increase("login_count", 1)

  .update();

```



#### `upsert(data: Record, updateData?: Record | string): Promise`

Insert or update on duplicate key.



```javascript

// Simple upsert (updates all fields)

const id = await MySQLPool

  .table("users")

  .upsert({

    email: "john@example.com",

    name: "John Doe",

    login_count: 1

  });



// Upsert with specific update data

const id2 = await MySQLPool

  .table("users")

  .upsert(

    { email: "john@example.com", name: "John Doe", login_count: 1 },

    { updated_at: "NOW()" }

  );

```



### Raw Queries



#### `read(query: string, params?: any[]): Promise`

Execute read query using read pool.



```javascript

const users = await MySQLPool.read(`

SELECT COUNT(*) as total 

FROM users 

WHERE status = ?

`, ['active']);

```



#### `write(query: string, params?: any[]): Promise`

Execute write query using write pool.



```javascript

const result = await MySQLPool.write(`

UPDATE users 

SET last_login = NOW() 

WHERE id = ?

`, [userId]);

```



## Advanced Examples



### Complex Query with Joins and Conditions



```javascript

const reports = await MySQLPool

  .table("orders")

  .select("orders.id", "users.name", "products.title", "orders.total")

  .innerJoin("users", "orders.user_id", "users.id")

  .leftJoin("order_items", "orders.id", "order_items.order_id")

  .leftJoin("products", "order_items.product_id", "products.id")

  .where("orders.status", "completed")

  .where("orders.created_at", ">", "2023-01-01")

  .orderBy("orders.created_at", "DESC")

  .limit(50)

  .get();

```



### Pagination with Total Count



```javascript

const page = 1;

const perPage = 10;



const results = await MySQLPool

  .table("users")

  .select("id", "name", "email", "created_at")

  .where("status", "active")

  .total()

  .orderBy("created_at", "DESC")

  .limit(perPage)

  .offset((page - 1) * perPage)

  .get();



console.log(`total: ${results[0]?.total || 0}`);

console.log(`page: ${page}`);

```



### Transaction-like Operations



```javascript

try {

  // Create user

  const userId = await MySQLPool

    .table("users", "write")

    .insert({

      name: "John Doe",

      email: "john@example.com"

    });



  // Create user profile

  await MySQLPool

    .table("profiles", "write")

    .insert({

      user_id: userId,

      bio: "Software Developer",

      avatar: "avatar.jpg"

    });



  console.log("created successfully");

} catch (error) {

  console.error("failed to create:", error);

}

```



## Supported MySQL Functions



The following MySQL functions are supported in update operations:



- `NOW()`

- `CURRENT_TIMESTAMP`

- `UUID()`

- `RAND()`

- `CURDATE()`

- `CURTIME()`

- `UNIX_TIMESTAMP()`

- `UTC_TIMESTAMP()`

- `SYSDATE()`

- `LOCALTIME()`

- `LOCALTIMESTAMP()`

- `PI()`

- `DATABASE()`

- `USER()`

- `VERSION()`



## Error Handling



```javascript

try {

  await MySQLPool.init();

  

  const users = await MySQLPool

    .table("users")

    .where("invalid_column", "value")

    .get();

    

} catch (error) {

  console.error("error:", error.message);

} finally {

  await MySQLPool.close();

}

```



## Performance Features



- **Connection Pooling**: Automatic connection reuse

- **Slow Query Detection**: Queries over 20ms are automatically logged

- **Prepared Statements**: All queries use parameterized statements to prevent SQL injection

- **Connection Management**: Automatic connection release after each query



## License



This source code project is licensed under the [MIT](https://github.com/pardnltd-tools/blob/main/LICENSE) license.



## Creator






邱敬幃 Pardn Chiu





    

 

    




***



©️ 2025 [邱敬幃 Pardn Chiu](https://pardn.io)