Documentation missing simple examples. How to insert using variables etc ...

[kevin-wad]

Documentation is missing simple examples.
How to insert using variables etc ...
The mysql has much more documentation. If it was up to me I would stickwith npm mysql but for this specific project I have to use mysql2 and it is a real pain to implement!

[wellwelwel]

When you say "insert using variables", are you asking for an example like this, but with INSERT?

node-mysql2/examples/simple-select.js

Lines 23 to 29 in fa47d0b

	connection.query(
	'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
	['Page', 45],
	(err, results) => {
	console.log(results);
	}
	);

---

From mysql2 documentation: "MySQL2 is mostly API compatible with mysqljs and supports majority of features.".

Following this approach, mysqljs has this example:

var post  = {id: 1, title: 'Hello MySQL'};
var query = connection.query('INSERT INTO posts SET ?', post, function (error, results, fields) {
  if (error) throw error;
  // Neat!
});
console.log(query.sql); // INSERT INTO posts SET `id` = 1, `title` = 'Hello MySQL'

This example will work for both mysqljs and mysql2 🧙🏻

---

Documentation is missing simple examples.

I think we can improve it, especially for execute and promise-based examples.

---

You can also compare some of the differences between them:

• History and Why MySQL2
• API and Configuration

[sidorares]

"MySQL2 is mostly API compatible with mysqljs and supports majority of features.".

When this line was added years ago mysqljs/mysql was way more popular than mysql2, and it made sense to "delegate" documentation in that way. Maybe it's time now to have full api docs in the readme. Good example: https://github.com/mscdex/ssh2

Also would be great to add nextra or docusaurus based documentation site (main api, same as in readme + examples / gotchas / common mistakes / best practices / FAQ etc )

[wellwelwel]

Hey @sidorares, how would it be to set up a website (MDX) in practice (same repository using a "website" directory, for example)?

Personally, I love the way how docusaurus does it and it naturally comes with a beautiful layout.

I really believe that MySQL2 deserves it 🦖✨

[sidorares]

Yes, in the subfolder of the same repo, so that the docs are in sync with the code

[wellwelwel]

If you're okay with that, we can dedicate a separate branch to work on it.

[sidorares]

If you're okay with that, we can dedicate a separate branch to work on it.

Sure, I'm OK with that

[wellwelwel]

One approach I've considered interesting is using tabs to show the variations of a same section, for example:

Installation (JavaScript) | Installation (TypeScript)
Some Method (Promise) | Some Method (Callback)

---

The same idea for sidebar, for example in "Examples" section, we can use a parent "Queries", then:

• Queries
  • INSERT
  • SELECT
  • UPDATE
  • etc.

---

Also, on the main page, keep it focused on documentation.

---

Here's a test using docusaurus:

480.mov

---

Notes:

• Every page would be a .md or .mdx file in website/docs path.
  • This would allow pages to be created dynamically when a new file is added to the directory.
• We can use the current documentation and examples to start it.
  • Naturally, increasing more complete documentation in the long term.

---

What do you think? 🌞✨

[sidorares]

What do you think? 🌞✨

😍

[sidorares]

#2279 fixes this

[wellwelwel]

#2279 fixes this

---

Just complementing:

node-mysql2/website/docs/examples/queries/prepared-statements/insert.mdx

Lines 21 to 32 in 323ab12

	try {
	const sql = 'INSERT INTO `users`(`name`, `age`) VALUES (?, ?), (?,?)';
	const values = ['Josh', 19, 'Page', 45];
	// highlight-next-line
	const [result, fields] = await connection.execute(sql, values);
	console.log(result);
	console.log(fields);
	} catch (err) {
	console.log(err);
	}

• sidorares.github.io/node-mysql2/docs/examples/queries/prepared-statements/insert

---

For now (#2337), there are examples of INSERT, SELECT, UPDATE and DELETE for both simple queries and using Placeholders / Prepared Statements, also for createConnection, createPool and createPoolCluster and its variations (such as connecting using URI string and options, SHA1, SSL, etc. for each connection variation) 🧙🏻