Skip to content

Commit 785d853

Browse files
committed
docs: Show generated SQL in MySQLTable query examples
1 parent 725cdfa commit 785d853

File tree

2 files changed

+140
-106
lines changed

2 files changed

+140
-106
lines changed

README.md

Lines changed: 71 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -587,43 +587,48 @@ userTable.select('*', (err, rows) => {
587587
if (err) throw err;
588588
// rows contains all data for all users
589589
});
590+
591+
// SELECT * FROM `user`;
590592
```
591593

592594
**Example**: Select specific columns
593595
```js
594596
userTable.select(['email', 'name'], 'WHERE `points` > 10000', (err, rows) => {
595597
if (err) throw err;
596-
console.log(rows); // -> [{email: 'email@example.com', name: 'John Doe'}, etc.]
598+
console.log(rows); // -> [{email: 'email@example.com', name: 'John Doe'}, ...]
597599
});
600+
601+
// SELECT `email`, `name` FROM `user` WHERE `points` > 10000;
598602
```
599603

600604
**Example**: Select with placeholders
601605
```js
602-
userTable.select(['email'], 'WHERE `id` = ?', [5], (err, rows) => {
603-
if (err) throw err;
604-
console.log(rows); // -> [{email: 'email@example.com'}]
605-
});
606+
userTable.select(['email'], 'WHERE `id` = ?', [5])
607+
.then(rows => console.log(rows)); // -> [{email: 'email@example.com'}]
606608

607-
userTable.select('??', 'WHERE ?', ['email', {id: 5}], (err, rows) => {
608-
if (err) throw err;
609-
console.log(rows); // -> [{email: 'email@example.com'}]
610-
});
609+
// SELECT `email` FROM `user` WHERE `id` = 5;
610+
611+
612+
userTable.select('??', 'WHERE ?', ['email', {id: 5}])
613+
.then(rows => console.log(rows)); // -> [{email: 'email@example.com'}]
614+
615+
// SELECT `email` FROM `user` WHERE `id` = 5;
611616
```
612617

613618
**Example**: Select columns with aliases
614619
```js
615-
userTable.select('`display_name` AS `name`', 'WHERE `points` > 10000', (err, rows) => {
616-
if (err) throw err;
617-
console.log(rows); // -> [{name: 'JohnD'}, etc.]
618-
});
620+
userTable.select('`name` AS `fullName`', 'WHERE `points` > 10000')
621+
.then(rows => console.log(rows)); // -> [{fullName: 'John Doe'}, ...]
622+
623+
// SELECT `name` AS `fullName` FROM `user` WHERE `points` > 10000;
619624
```
620625

621626
**Example**: Select using a function
622627
```js
623-
userTable.select('COUNT(*) AS `highScorers`', 'WHERE `points` > 10000', (err, rows) => {
624-
if (err) throw err;
625-
console.log(rows); // -> [{highScorers: 27}]
626-
});
628+
userTable.select('COUNT(*) AS `highScorers`', 'WHERE `points` > 10000')
629+
.then(rows => console.log(rows)); // -> [{highScorers: 27}]
630+
631+
// SELECT COUNT(*) AS `highScorers` FROM `user` WHERE `points` > 10000;
627632
```
628633

629634

@@ -650,21 +655,32 @@ optional but at least one of them must be specified.
650655

651656
**Example**: Insert a new user
652657
```js
653-
userTable.insert({email: 'email@example.com', name: 'John Doe'}, (err, result) => {
654-
if (err) throw err;
655-
// data inserted!
656-
});
658+
userTable.insert({email: 'email@example.com', name: 'John Doe'})
659+
.then(result => result.affectedRows); // 1
660+
661+
// INSERT INTO `user`
662+
// SET `email` = 'email@example.com', `name` = 'John Doe';
657663
```
658664

659665
**Example**: Insert or update
660666
```js
661667
const data = {id: 5, points: 100};
662668
// If duplicate key (id), add the points
663669
const onDuplicateKeySQL = 'ON DUPLICATE KEY UPDATE `points` = `points` + ?';
664-
userTable.insert(data, onDuplicateKeySQL, [data.points], (err, result) => {
665-
if (err) throw err;
666-
// data inserted or updated!
667-
});
670+
userTable.insert(data, onDuplicateKeySQL, [data.points])
671+
.then(result => result.affectedRows); // 1 if inserted, 2 if updated
672+
673+
// INSERT INTO `user` SET `id` = 5, `points` = 100
674+
// ON DUPLICATE KEY UPDATE `points` = `points` + 100;
675+
```
676+
677+
**Example**: With only the `sqlString` argument
678+
```js
679+
placeTable.insert('`location` = POINT(0, 0)');
680+
// INSERT INTO `place` SET `location` = POINT(0, 0);
681+
682+
placeTable.insert('`location` = POINT(?, ?)', [8, 2]);
683+
// INSERT INTO `place` SET `location` = POINT(8, 2);
668684
```
669685

670686
**Example**: Bulk insert
@@ -673,10 +689,12 @@ const users = [
673689
[1, 'john@email.com', 'John Doe'],
674690
[2, 'jane@email.com', 'Jane Brown'],
675691
];
676-
userTable.insert([users], (err, result) => {
677-
if (err) throw err;
678-
// users inserted!
679-
});
692+
userTable.insert([users])
693+
.then(result => result.insertId); // 2 (ID of the last inserted row)
694+
695+
// INSERT INTO `user` VALUES
696+
// (1, 'john@email.com', 'John Doe'),
697+
// (2, 'jane@email.com', 'Jane Brown');
680698
```
681699

682700
**Example**: Bulk insert with specified columns
@@ -685,10 +703,12 @@ const users = [
685703
['john@email.com', 'John Doe'],
686704
['jane@email.com', 'Jane Brown'],
687705
];
688-
userTable.insert([['email', 'name'], users], (err, result) => {
689-
if (err) throw err;
690-
// users inserted!
691-
});
706+
userTable.insert([['email', 'name'], users])
707+
.then(result => result.affectedRows); // 2
708+
709+
// INSERT INTO `user` (`email`, `name`) VALUES
710+
// ('john@email.com', 'John Doe'),
711+
// ('jane@email.com', 'Jane Brown');
692712
```
693713

694714

@@ -715,31 +735,27 @@ optional but at least one of them must be specified.
715735

716736
**Example**: With both the `data` and `sqlString` arguments
717737
```js
718-
userTable.update({email: 'updated@email.com'}, 'WHERE `id` = ?', [5], (err, result) => {
719-
if (err) throw err;
720-
// email updated!
721-
});
738+
userTable.update({email: 'updated@email.com'}, 'WHERE `id` = ?', [5])
739+
.then(result => result.changedRows); // 1
740+
741+
// UPDATE `user` SET `email` = 'updated@email.com'
742+
// WHERE `id` = 5;
722743
```
723744

724745
**Example**: With only the `sqlString` argument
725746
```js
726-
userTable.update("`word` = CONCAT('prefix', `word`)", (err, result) => {
727-
if (err) throw err;
728-
// prefix added to all words!
729-
});
747+
userTable.update("`word` = CONCAT('prefix', `word`)");
748+
// UPDATE `user` SET `word` = CONCAT('prefix', `word`);
730749

731-
userTable.update('`points` = `points` + ? WHERE `winner` = ?', [1, 1], (err, result) => {
732-
if (err) throw err;
733-
// 1 point added to all winners!
734-
});
750+
userTable.update('`points` = `points` + ? WHERE `winner` = ?', [10, 1]);
751+
// UPDATE `user` SET `points` = `points` + 10
752+
// WHERE `winner` = 1;
735753
```
736754

737755
**Example**: With only the `data` argument (updates all rows)
738756
```js
739-
userTable.update({points: 1000}, (err, result) => {
740-
if (err) throw err;
741-
// Now everyone has 1000 points!
742-
});
757+
userTable.update({points: 1000});
758+
// UPDATE `user` SET `points` = 1000;
743759
```
744760

745761

@@ -762,10 +778,10 @@ Deletes data from the table.
762778

763779
**Example**: Delete specific rows
764780
```js
765-
userTable.delete('WHERE `spammer` = 1', (err, result) => {
766-
if (err) throw err;
767-
// spammers deleted!
768-
});
781+
userTable.delete('WHERE `spammer` = 1')
782+
.then(result => result.affectedRows); // The number of deleted spammers
783+
784+
// DELETE FROM `user` WHERE `spammer` = 1;
769785
```
770786

771787
**Example**: Delete all rows (you probably don't want to do this)
@@ -774,6 +790,8 @@ userTable.delete((err, result) => {
774790
if (err) throw err;
775791
// all rows deleted :(
776792
});
793+
794+
// DELETE FROM `user`;
777795
```
778796

779797

lib/MySQLTable.js

Lines changed: 69 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -49,34 +49,39 @@ class MySQLTable {
4949
* // rows contains all data for all users
5050
* });
5151
*
52+
* // SELECT * FROM `user`;
53+
*
5254
* @example <caption>Select specific columns</caption>
5355
* userTable.select(['email', 'name'], 'WHERE `points` > 10000', (err, rows) => {
5456
* if (err) throw err;
55-
* console.log(rows); // -> [{email: 'email@example.com', name: 'John Doe'}, etc.]
57+
* console.log(rows); // -> [{email: 'email@example.com', name: 'John Doe'}, ...]
5658
* });
5759
*
60+
* // SELECT `email`, `name` FROM `user` WHERE `points` > 10000;
61+
*
5862
* @example <caption>Select with placeholders</caption>
59-
* userTable.select(['email'], 'WHERE `id` = ?', [5], (err, rows) => {
60-
* if (err) throw err;
61-
* console.log(rows); // -> [{email: 'email@example.com'}]
62-
* });
63+
* userTable.select(['email'], 'WHERE `id` = ?', [5])
64+
* .then(rows => console.log(rows)); // -> [{email: 'email@example.com'}]
6365
*
64-
* userTable.select('??', 'WHERE ?', ['email', {id: 5}], (err, rows) => {
65-
* if (err) throw err;
66-
* console.log(rows); // -> [{email: 'email@example.com'}]
67-
* });
66+
* // SELECT `email` FROM `user` WHERE `id` = 5;
67+
*
68+
*
69+
* userTable.select('??', 'WHERE ?', ['email', {id: 5}])
70+
* .then(rows => console.log(rows)); // -> [{email: 'email@example.com'}]
71+
*
72+
* // SELECT `email` FROM `user` WHERE `id` = 5;
6873
*
6974
* @example <caption>Select columns with aliases</caption>
70-
* userTable.select('`display_name` AS `name`', 'WHERE `points` > 10000', (err, rows) => {
71-
* if (err) throw err;
72-
* console.log(rows); // -> [{name: 'JohnD'}, etc.]
73-
* });
75+
* userTable.select('`name` AS `fullName`', 'WHERE `points` > 10000')
76+
* .then(rows => console.log(rows)); // -> [{fullName: 'John Doe'}, ...]
77+
*
78+
* // SELECT `name` AS `fullName` FROM `user` WHERE `points` > 10000;
7479
*
7580
* @example <caption>Select using a function</caption>
76-
* userTable.select('COUNT(*) AS `highScorers`', 'WHERE `points` > 10000', (err, rows) => {
77-
* if (err) throw err;
78-
* console.log(rows); // -> [{highScorers: 27}]
79-
* });
81+
* userTable.select('COUNT(*) AS `highScorers`', 'WHERE `points` > 10000')
82+
* .then(rows => console.log(rows)); // -> [{highScorers: 27}]
83+
*
84+
* // SELECT COUNT(*) AS `highScorers` FROM `user` WHERE `points` > 10000;
8085
*/
8186
select(columns, sqlString, values, cb) {
8287
if (typeof columns !== 'string') {
@@ -111,39 +116,52 @@ class MySQLTable {
111116
* of the query is returned.
112117
*
113118
* @example <caption>Insert a new user</caption>
114-
* userTable.insert({email: 'email@example.com', name: 'John Doe'}, (err, result) => {
115-
* if (err) throw err;
116-
* // data inserted!
117-
* });
119+
* userTable.insert({email: 'email@example.com', name: 'John Doe'})
120+
* .then(result => result.affectedRows); // 1
121+
*
122+
* // INSERT INTO `user`
123+
* // SET `email` = 'email@example.com', `name` = 'John Doe';
118124
*
119125
* @example <caption>Insert or update</caption>
120126
* const data = {id: 5, points: 100};
121127
* // If duplicate key (id), add the points
122128
* const onDuplicateKeySQL = 'ON DUPLICATE KEY UPDATE `points` = `points` + ?';
123-
* userTable.insert(data, onDuplicateKeySQL, [data.points], (err, result) => {
124-
* if (err) throw err;
125-
* // data inserted or updated!
126-
* });
129+
* userTable.insert(data, onDuplicateKeySQL, [data.points])
130+
* .then(result => result.affectedRows); // 1 if inserted, 2 if updated
131+
*
132+
* // INSERT INTO `user` SET `id` = 5, `points` = 100
133+
* // ON DUPLICATE KEY UPDATE `points` = `points` + 100;
134+
*
135+
* @example <caption>With only the `sqlString` argument</caption>
136+
* placeTable.insert('`location` = POINT(0, 0)');
137+
* // INSERT INTO `place` SET `location` = POINT(0, 0);
138+
*
139+
* placeTable.insert('`location` = POINT(?, ?)', [8, 2]);
140+
* // INSERT INTO `place` SET `location` = POINT(8, 2);
127141
*
128142
* @example <caption>Bulk insert</caption>
129143
* const users = [
130144
* [1, 'john@email.com', 'John Doe'],
131145
* [2, 'jane@email.com', 'Jane Brown'],
132146
* ];
133-
* userTable.insert([users], (err, result) => {
134-
* if (err) throw err;
135-
* // users inserted!
136-
* });
147+
* userTable.insert([users])
148+
* .then(result => result.insertId); // 2 (ID of the last inserted row)
149+
*
150+
* // INSERT INTO `user` VALUES
151+
* // (1, 'john@email.com', 'John Doe'),
152+
* // (2, 'jane@email.com', 'Jane Brown');
137153
*
138154
* @example <caption>Bulk insert with specified columns</caption>
139155
* const users = [
140156
* ['john@email.com', 'John Doe'],
141157
* ['jane@email.com', 'Jane Brown'],
142158
* ];
143-
* userTable.insert([['email', 'name'], users], (err, result) => {
144-
* if (err) throw err;
145-
* // users inserted!
146-
* });
159+
* userTable.insert([['email', 'name'], users])
160+
* .then(result => result.affectedRows); // 2
161+
*
162+
* // INSERT INTO `user` (`email`, `name`) VALUES
163+
* // ('john@email.com', 'John Doe'),
164+
* // ('jane@email.com', 'Jane Brown');
147165
*/
148166
insert(data, sqlString, values, cb) {
149167
if (typeof data === 'string') {
@@ -199,27 +217,23 @@ class MySQLTable {
199217
* of the query is returned.
200218
*
201219
* @example <caption>With both the `data` and `sqlString` arguments</caption>
202-
* userTable.update({email: 'updated@email.com'}, 'WHERE `id` = ?', [5], (err, result) => {
203-
* if (err) throw err;
204-
* // email updated!
205-
* });
220+
* userTable.update({email: 'updated@email.com'}, 'WHERE `id` = ?', [5])
221+
* .then(result => result.changedRows); // 1
222+
*
223+
* // UPDATE `user` SET `email` = 'updated@email.com'
224+
* // WHERE `id` = 5;
206225
*
207226
* @example <caption>With only the `sqlString` argument</caption>
208-
* userTable.update("`word` = CONCAT('prefix', `word`)", (err, result) => {
209-
* if (err) throw err;
210-
* // prefix added to all words!
211-
* });
227+
* userTable.update("`word` = CONCAT('prefix', `word`)");
228+
* // UPDATE `user` SET `word` = CONCAT('prefix', `word`);
212229
*
213-
* userTable.update('`points` = `points` + ? WHERE `winner` = ?', [1, 1], (err, result) => {
214-
* if (err) throw err;
215-
* // 1 point added to all winners!
216-
* });
230+
* userTable.update('`points` = `points` + ? WHERE `winner` = ?', [10, 1]);
231+
* // UPDATE `user` SET `points` = `points` + 10
232+
* // WHERE `winner` = 1;
217233
*
218234
* @example <caption>With only the `data` argument (updates all rows)</caption>
219-
* userTable.update({points: 1000}, (err, result) => {
220-
* if (err) throw err;
221-
* // Now everyone has 1000 points!
222-
* });
235+
* userTable.update({points: 1000});
236+
* // UPDATE `user` SET `points` = 1000;
223237
*/
224238
update(data, sqlString, values, cb) {
225239
if (typeof data === 'string') {
@@ -257,16 +271,18 @@ class MySQLTable {
257271
* of the query is returned.
258272
*
259273
* @example <caption>Delete specific rows</caption>
260-
* userTable.delete('WHERE `spammer` = 1', (err, result) => {
261-
* if (err) throw err;
262-
* // spammers deleted!
263-
* });
274+
* userTable.delete('WHERE `spammer` = 1')
275+
* .then(result => result.affectedRows); // The number of deleted spammers
276+
*
277+
* // DELETE FROM `user` WHERE `spammer` = 1;
264278
*
265279
* @example <caption>Delete all rows (you probably don't want to do this)</caption>
266280
* userTable.delete((err, result) => {
267281
* if (err) throw err;
268282
* // all rows deleted :(
269283
* });
284+
*
285+
* // DELETE FROM `user`;
270286
*/
271287
delete(sqlString, values, cb) {
272288
if (sqlString === undefined || typeof sqlString === 'function') {

0 commit comments

Comments
 (0)