🐉 NagaSQL

Lightweight SQL Loader & Query Manager for Node.js
โหลดไฟล์ .sql มาใช้งานแบบ dynamic พร้อม parameter, condition และ callback logic

🚀 Basic Usage

const mysql = require('mysql2');
const NagaSQL = require('nagasql');

const db = new NagaSQL({
    mysql,
    config: {
        host: 'localhost',
        user: 'root',
        password: '',
        database: 'test'
    },
    path: __dirname + '/sql',
    debug: true,
    log: true
});

📂 Folder Structure

project/
│
├── sql/
│   ├── getUser.sql
│   ├── listUsers.sql
│   └── createUser.sql
│
└── app.js

🧾 Writing SQL Files

1. Basic Query

SELECT * FROM users WHERE id = :id;

Usage

await db.use('getUser', { id: 1 });

2. Array Parameter

SELECT * FROM users WHERE id IN (:[ids]);

await db.use('listUsers', { ids: [1,2,3] });

3. Conditional SQL

SELECT * FROM users
WHERE 1=1
$role{ AND role = :role }{ }

await db.use('listUsers', { role: 'admin' });

• ถ้ามี role → จะเพิ่มเงื่อนไข
• ถ้าไม่มี → จะไม่เพิ่ม

🧠 Special Comments (Magic Directives)

ใช้ comment แบบพิเศษเพื่อควบคุมผลลัพธ์ของ query

🔹 Return Only One Row

/* [R938.one] {} */
SELECT * FROM users WHERE id = :id;

const user = await db.use('getUser', { id: 1 });

🔹 Check Length

/* [R938.length] {>0} */
SELECT * FROM users;

• >0 → ต้องมีข้อมูลอย่างน้อย 1 row
• =1 → ต้องมี 1 row เท่านั้น

🔹 Check affectedRows

/* [R938.affectedRows] {>0} */
INSERT INTO users(name) VALUES(:name);

const success = await db.use('createUser', { name: 'John' });

🔹 Custom Callback

/* [R938.callback] {
    if(data && data.length){
        return data.map(d => d.name);
    }
    return [];
} */
SELECT * FROM users;

🔹 Custom Parameter Logic

/* [R938.parameter] {
    return data.filter(d => d.active);
} */

🔐 Parameter Types

| Syntax | Description | |-----------|--------------------| | :id | string / number | | :[ids] | array |

⚙️ Debug Mode

const db = new NagaSQL({
    mysql,
    config,
    path: './sql',
    debug: true
});

Output

[R938.SQL.debug.use] Query(getUser): SELECT ...

🧪 Full Example

SQL (sql/getUser.sql)

/* [R938.one] {} */
SELECT * FROM users WHERE id = :id;

SQL (sql/listUsers.sql)

SELECT * FROM users
WHERE 1=1
$status{ AND status = :status }{ }

JS

(async () => {
    const user = await db.use('getUser', { id: 1 });
    console.log(user);

    const users = await db.use('listUsers', { status: 'active' });
    console.log(users);
})();

❗ Notes

• .sql filename = function name
• Duplicate filename จะถูก ignore
• Query ถูก compile เป็น function เพื่อเพิ่ม performance

💡 Tips

• แยก SQL ตาม feature → maintain ง่าย
• ใช้ conditional → ลด query ซ้ำ
• ใช้ callback ใน SQL → ลด logic ฝั่ง JS