{"id":15285402,"url":"https://github.com/npkgz/mysql-magic","last_synced_at":"2026-04-10T15:52:40.786Z","repository":{"id":48000352,"uuid":"93987554","full_name":"npkgz/mysql-magic","owner":"npkgz","description":"Promised based, high-level mysql library extension for Node.js \u003e=7.6","archived":false,"fork":false,"pushed_at":"2021-08-11T04:07:38.000Z","size":58,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-14T04:42:20.038Z","etag":null,"topics":["extension","high-level","javascript","library","mysql","mysql-library","nodejs","nodejs-modules","promises"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/mysql-magic","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/npkgz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-06-11T07:02:53.000Z","updated_at":"2021-05-24T13:59:24.000Z","dependencies_parsed_at":"2022-08-12T16:11:51.282Z","dependency_job_id":null,"html_url":"https://github.com/npkgz/mysql-magic","commit_stats":null,"previous_names":["andidittrich/node.mysql-magic"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npkgz%2Fmysql-magic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npkgz%2Fmysql-magic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npkgz%2Fmysql-magic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npkgz%2Fmysql-magic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/npkgz","download_url":"https://codeload.github.com/npkgz/mysql-magic/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245152767,"owners_count":20569399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["extension","high-level","javascript","library","mysql","mysql-library","nodejs","nodejs-modules","promises"],"created_at":"2024-09-30T15:04:36.203Z","updated_at":"2025-12-30T23:29:11.283Z","avatar_url":"https://github.com/npkgz.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/AndiDittrich/Node.mysql-magic.svg?branch=master)](https://travis-ci.org/AndiDittrich/Node.mysql-magic)\n\nmysql-magic\n=========================\n\nPromised based, high-level [mysql library](https://github.com/mysqljs/mysql) extension for Node.js **\u003e=7.6**.\n\n```\nyarn add mysql-magic --save\n```\n\nFeatures\n------------------------------\n\n* Supports multiple named connection pools (different database settings with global scope)\n* Safe async connection scopes - execute querys with build-in error handling\n* High-level API \n* Designed to run with the pure power of native `Promise`, `await` and `async function`\n\n\nUsage\n------------------------------\n\n**Application Bootstrap**\n\n```js\nconst _mysqlMagic = require('mysql-magic');\n\n// somewhere during your applications bootstrap...initialize a custom pool. It consumes any pool-options of [mysqljs](https://github.com/mysqljs/mysql)\n_mysqlMagic.initPool('userdb', {\n    host     : 'localhost',\n    user     : 'me',\n    password : 'secret',\n    database : 'my_db'\n});\n```\n\n**Run Querys**\n\n```js\n// get the pool\nconst _db = require('mysql-magic').getPool('userdb');\n\n// wait for connection becomes available\nconst con = await _db.getConnection();\n\n// execute query\nconst [result, fields] = await con.query('SELECT * FROM `users` LIMIT 10;');\n\n// release connection\nawait con.release();\n```\n\n**Run Querys within scope**\n\nWithin a connection scope, the connection will be automatically closed on finish or in case of an error. All kind of errors are proxied as exception.\n\n```js\nconst _db = require('mysql-magic');\n\n// retrieve connection scope\nconst numUsers = await _db.getConnection('userdb', async function(){\n    // run query\n    const [rows, fields] = await this.query('SELECT COUNT(*) as `count` FROM `users`;');\n\n    return rows.count;\n});\n\nconsole.log(numUsers);\n```\n\nAPI\n------------------------------\n\n* initPool\n* getPool\n* getConnection()\n* Pool::getConnection\n* Connection::release\n* Connection::query\n* Connection::insert\n* Connection::fetchRow\n* Connection::fetchAll\n\n\nmysql-magic::initPool\n------------------------------\n\n**Description:** Initializes a new named connection pool. Pass [mysql connection options](https://github.com/mysqljs/mysql#pool-options) as second argument (passthrough)\n\n**Syntax:** `pool:Object = initPool(name:String, options:Object)`\n\n```js\nconst _db = require('mysql-magic');\n\n// initialize a new \"named\" pool\ninitPool('userdb', {\n    // db credentials\n    host: 'localhost',\n    user: 'bob',\n    password: 'secret',\n    database: 'my_user_db'\n\n    // special pool options\n    connectionLimit: 50,\n    acquireTimeout: 1000,\n    waitForConnections: true,\n    queueLimit: 200\n});\n\n// initialize default pool\ninitPool(null, {\n    ...\n})\n```\n\nmysql-magic::getPool\n------------------------------\n\n**Description:** Retrieves a named connection pool\n\n**Syntax:** `const pool:Object = getPool([name:String])`\n\n```js\n// get the userdb pool\nconst _db = require('mysql-magic').getPool('userdb');\n\n// request a connection\nconst con = await _db.getConnection();\n...\n```\n\nmysql-magic::getConnection\n------------------------------\n\n**Description:** Retrieves a connection using async connection scope\n\n**Syntax:** `const result:Object = getConnection([name:String], scope:async-function)`\n\n**Notice:** A connection scope will automatically call `con.release()` in the end or on an error - exceptions are forwarded\n\n**Example 1 - Named Pool**\n\n```js\n// just include the module\nconst _db = require('mysql-magic');\n\n// retrieve connection scope using userdb\nconst numUsers = await _db.getConnection('userdb', async function(){\n    // run query\n    const [rows, fields] = await this.query('SELECT COUNT(*) as num FROM users;');\n\n    return rows[0].num;\n});\n\nconsole.log(numUsers);\n...\n```\n\n**Example 2 - Default Pool**\n\n```js\n// just include the module\nconst _db = require('mysql-magic');\n\n// retrieve connection scope using default pool\nconst numUsers = await _db.getConnection(async function(){\n    // run query\n    const [rows, fields] = await this.query('SELECT COUNT(*) as num FROM users;');\n\n    return rows[0].num;\n});\n\nconsole.log(numUsers);\n...\n```\n\nmysql-magic::Pool::getConnection\n------------------------------\n\n**Description:** Requests a connection from given pool\n\n**Syntax:** `const connection:Object = Pool::getConnection([scope:async-function])`\n\n**Notice:** A connection scope will automatically call `con.release()` in the end or on an error - exceptions are forwarded\n\n**Example 1**\n\n```js\n// get the userdb pool\nconst _db = require('mysql-magic').getPool('userdb');\n\n// request a connection\nconst con = await _db.getConnection();\n\n// do something\n...\n```\n\n**Example 2 - Scopes**\n```js\nconst _db = require('mysql-magic');\n\n// retrieve connection scope\nconst result = await _db.getConnection('userdb', async function(){\n    // run query\n    const [rows, fields] = await this.query('SELECT * FROM log LIMIT 20;');\n    return rows.length;\n});\n\nconsole.log(result);\n```\n\n\nmysql-magic::Connection::release\n------------------------------\n\n**Description:** Releases the connection\n\n**Syntax:** `Connection::release()`\n\n```js\n// get the userdb pool\nconst _db = require('mysql-magic').getPool('userdb');\n\n// request a connection\nconst con = await _db.getConnection();\n\n// do something\n...\n\n// release the connection\ncon.release();\n```\n\nmysql-magic::Connection::query\n------------------------------\n\n**Description:** Executes a [mysql query](https://github.com/mysqljs/mysql#performing-queries)\n\n**Syntax:** `const [result:Object, fields:Object] = Connection::query(sql:string, [values:Object])`\n\n```js\n// get the userdb pool\nconst _db = require('mysql-magic').getPool('userdb');\n\n// request a connection\nconst con = await _db.getConnection();\n\n// do something\nconst [result] = await con.query('SELECT * FROM `users LIMIT 100`;');\n\nconsole.log(result);\n\n// release the connection\ncon.release();\n```\n\nmysql-magic::Connection::insert\n------------------------------\n\n**Description:** Executes a insert with given values wrapped into object\n\n**Syntax:** `const [insertID:int, result:Object] = Connection::insert(table:string, values:Object)`\n\n```js\n// get the userdb pool\nconst _db = require('mysql-magic').getPool('userdb');\n\n// request a connection\nconst con = await _db.getConnection();\n\n// insert a new user\nconst [userid] = await con.insert('users', {\n    name: 'John',\n    email: 'john@example.org',\n    login: 'johndow1234'\n});\n\nconsole.log(result);\n\n// release the connection\ncon.release();\n```\n\nmysql-magic::Connection::fetchRow\n------------------------------\n\n**Description:** Executes a query an returns a single result as object\n\n**Syntax:** `const [result:Object] = Connection::fetchRow(sql:string, [values:Object])`\n\n```js\n// get the userdb pool\nconst _db = require('mysql-magic').getPool('userdb');\n\n// request a connection\nconst con = await _db.getConnection();\n\n// fetch user by its name\nconst user = await _db.fetchRow('SELECT * FROM `users` WHERE `name` LIKE ? LIMIT 1;', ['John']);\n\nconsole.log(result);\n\n// release the connection\ncon.release();\n```\n\nmysql-magic::Connection::fetchAll\n------------------------------\n\n**Description:** Executes a query an returns an array of objects (similar to query but returns an **empty array** in case of empty resultset)\n\n**Syntax:** `const [results:Array] = Connection::fetchAll(sql:string, [values:Object])`\n\n```js\n// get the userdb pool\nconst _db = require('mysql-magic').getPool('userdb');\n\n// request a connection\nconst con = await _db.getConnection();\n\n// fetch all users\nconst users = await _db.fetchAll('SELECT * FROM `users`;');\n\n// show users\nfor (const user in users){\n    console.log('User[', user.id, '] - ', user.name);\n}\n\n// release the connection\ncon.release\n```\n\nAny Questions ? Report a Bug ? Enhancements ?\n---------------------------------------------\nPlease open a new issue on [GitHub](https://github.com/AndiDittrich/Node.mysql-magic/issues)\n\nLicense\n-------\nmysql-magic is OpenSource and licensed under the Terms of [The MIT License](LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpkgz%2Fmysql-magic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnpkgz%2Fmysql-magic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpkgz%2Fmysql-magic/lists"}