MySQL Async/Await Wrapper v2.2.3

Simple wrapper for MySQL async/await functionality. Intended for functionality to mimic the popular mysql Node.js callback-based package, but with additional methods for awaiting execution. Goal is for normal methods to be unaffected and only additional await methods added, though accomplished through intermediary class objects.

• Installation
• Provided Async/Await Methods
• Configuration
• Example Using Single Connection
• Example Using Connection Pool
• Fringe Features Not Currently Supported
• Contributing
• License

Installation

1npm i mysql-await

Provided Async/Await Methods

The methods below have been added as async/await wrappers to existing MySQL methods of similar name. In order to use them, simply "await" their execution rather than passing a callback for the last argument of the function call. For original methods for which "await" methods may have been added, as needed, see the mysql library.

Connections from mysql.createConnection()

• Connection.awaitBeginTransaction()
• Connection.awaitChangeUser(params)
• Connection.awaitCommit()
• Connection.awaitConnect()
• Connection.awaitDestroy()
• Connection.awaitEnd()
• Connection.awaitQuery(query[, params])
• Connection.awaitRollback()

Connection Pool's from mysql.createPool()

• Pool.awaitEnd()
• Pool.awaitGetConnection()
• Pool.awaitQuery(query[, params])

Connections from pool.getConnection()

• Connection.awaitBeginTransaction()
• Connection.awaitChangeUser(params)
• Connection.awaitCommit()
• Connection.awaitQuery(query[, params])
• Connection.awaitRollback()

Configuration:

Example JSON configuration

1{
2  "connectionLimit" : 10,
3  "host"            : "example.org",
4  "user"            : "bob",
5  "password"        : "secret",
6  "database"        : "my_db",
7  "throwErrors"     : false
8}

Note: throwErrors is used to determine whether MySQL errors should be thrown AND emitted, or only emitted

Example Using Single Connection

1const fs = require(`fs`);
2const mysql = require(`mysql-await`);
3
4/** Self-executing asynchronous function so we can await results in this example */
5(async () => {
6  /** Create connection pool using loaded config */
7  const connection = mysql.createConnection(JSON.parse(fs.readFileSync(`mysql-config.json`)));
8
9  connection.on(`error`, (err) => {
10    console.error(`Connection error ${err.code}`);
11  });
12
13  /** Perform query on connection */
14  let result = await connection.awaitQuery(`SELECT * FROM people WHERE lastName = ?`, [`Doe`]);
15  
16  /** Log output */
17  console.log(result);
18    
19  /** Begin a new transaction */
20  await connection.awaitBeginTransaction();
21  
22  /** Perform query for max id number in users table */
23  result = await connection.awaitQuery(`SELECT MAX(id) maxId FROM people`);
24  
25  /** Add one to max id to get new id number */
26  const newId = result[0].maxId + 1;
27  
28  /** Insert new test user with new id number */
29  await connection.awaitQuery(`INSERT INTO people (id, firstName, lastName, age) VALUES (?, ?, ?, ?)`, [newId, `Ebenezer`, `Scrooge`, 142]);
30  
31  /** Commit transaction */
32  await connection.awaitCommit();
33  
34  /** End the connection */
35  connection.awaitEnd();
36})();
37

Example Output

1[
2  RowDataPacket { id: 3, firstName: 'Jane', lastName: 'Doe', age: 45 }
3]

Example Using Connection Pool

1const fs = require(`fs`);
2const mysql = require(`mysql-await`);
3
4/** Self-executing asynchronous function so we can await results in this example */
5(async () => {
6  /** Create connection pool using loaded config */
7  const pool = mysql.createPool(JSON.parse(fs.readFileSync(`mysql-config.json`)));
8
9  pool.on(`acquire`, (connection) => {
10    console.log(`Connection %d acquired`, connection.threadId);
11  });
12  
13  pool.on(`connection`, (connection) => {
14    console.log(`Connection %d connected`, connection.threadId);
15  });
16
17  pool.on(`enqueue`, () => {
18    console.log(`Waiting for available connection slot`);
19  });
20
21  pool.on(`release`, function (connection) {
22    console.log(`Connection %d released`, connection.threadId);
23  });
24
25  const connection = await pool.awaitGetConnection();
26  
27  connection.on(`error`, (err) => {
28    console.error(`Connection error ${err.code}`);
29  });
30
31  /** Perform query on connection */
32  let result = await connection.awaitQuery(`SELECT * FROM people WHERE lastName = ?`, [`Smith`]);
33  
34  /** Log output */
35  console.log(result);
36  
37  /** Release connection */
38  connection.release();
39    
40  /** Perform query on pool (opens a connection, runs query, releases connection) */
41  result = await pool.awaitQuery(`SELECT * FROM people WHERE age = ?`, [45]);
42  
43  /** Log output */
44  console.log(result);
45  
46  /** Get a new connection from the pool */
47  const connection2 = await pool.awaitGetConnection();
48  
49  /** Begin a new transaction */
50  await connection2.awaitBeginTransaction();
51  
52  /** Perform query for max id number in users table */
53  result = await connection2.awaitQuery(`SELECT MAX(id) maxId FROM people`);
54  
55  /** Add one to max id to get new id number */
56  const newId = result[0].maxId + 1;
57  
58  /** Insert new test user with new id number */
59  await connection2.awaitQuery(`INSERT INTO people (id, firstName, lastName, age) VALUES (?, ?, ?, ?)`, [newId, `Jacob`, `Marley`, 147]);
60  
61  /** Commit transaction */
62  await connection2.awaitCommit();
63  
64  /** Release connection */
65  connection2.release();
66  
67  /** Close connection pool */
68  await pool.awaitEnd();
69})();

Example Output

1Connection 16 connected
2Connection 16 acquired
3[
4  RowDataPacket {
5    id: 2,
6    firstName: 'John',
7    lastName: 'Smith',
8    age: 37
9  }
10]
11Connection 16 released
12Connection 16 acquired
13Connection 16 released
14[
15  RowDataPacket { id: 3, firstName: 'Jane', lastName: 'Doe', age: 45 }
16]
17Connection 16 acquired
18Connection 16 released

Fringe Features Not Currently Supported

• Pool Cluster's -- for now, can be added later if needed
• Result Streams -- for now, can be added later if needed

Contributing

Please open an issue for any bugs found or feature requests

• Thanks, @DavidvanDriessche, for identifying a significant issue with error handling
• Thanks, @DonaldKellet, for identifying missing arguments on the escape() and escapeId() functions
• Thanks, @Andromeda606, for identifying issues with connection.on() events

License

MIT