Skip to content

Commit

Permalink
docs: add and improve examples of connections, queries and more (#2337)
Browse files Browse the repository at this point in the history
* chore: prevent large package-lock.json modifications

* ci: add unit tests

* docs: `SELECT` examples using  Prepared Statement

* chore: update Docusaurus

* ci: include unit tests

* ci: check for doc files extensions

* docs: adapting examples for both JS and TS

* docs: `INSERT` examples using Prepared Statement

* docs: `UPDATE` examples using Prepared Statement

* docs: `DELETE` examples using Prepared Statement

* docs: fix broken links

* ci: throw for broken links

* docs: include tags

* ci: rename website CI and include unit tests

* docs: `SELECT` query examples

* docs: `INSERT` query examples

* docs: `UPDATE` query examples

* docs: `DELETE` query examples

* docs: introduce connection examples

* docs: `createConnection` examples

* docs: `createPool` examples

* docs: `createPoolCluster` examples

* docs: group queries examples

* docs: unify, group and reorganize examples

* docs: fix broken links

* docs: suggest examples in their respective sections in home

* docs: add Row as Array query example

* docs: polish examples

* docs: add `ExternalCodeEmbed` component to website contributing
wellwelwel authored Jan 6, 2024
1 parent 75b05f0 commit 323ab12
Showing 65 changed files with 4,865 additions and 804 deletions.
Original file line number Diff line number Diff line change
@@ -33,5 +33,8 @@ jobs:
- name: Checking Types
run: cd website && npm run typecheck

- name: Run Unit Tests
run: cd website && npm run test:unit

- name: Checking Build
run: cd website && npm run build
3 changes: 3 additions & 0 deletions .github/workflows/gh-pages.yml
Original file line number Diff line number Diff line change
@@ -32,6 +32,9 @@ jobs:
- name: Checking Types
run: cd website && npm run typecheck

- name: Run Unit Tests
run: cd website && npm run test:unit

- name: Building Site
run: cd website && npm run build

1 change: 0 additions & 1 deletion website/.eslintignore
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
/build
/.docusaurus
/.cache-loader
/**/*.mdx
3 changes: 2 additions & 1 deletion website/.eslintrc.json
Original file line number Diff line number Diff line change
@@ -8,7 +8,8 @@
"plugin:import/errors",
"plugin:import/warnings",
"plugin:react-hooks/recommended",
"plugin:react/jsx-runtime"
"plugin:react/jsx-runtime",
"plugin:@docusaurus/recommended"
],
"parserOptions": {
"ecmaVersion": "latest",
1 change: 0 additions & 1 deletion website/.prettierignore
Original file line number Diff line number Diff line change
@@ -2,4 +2,3 @@
/.docusaurus
/.cache-loader
# /**/*.mdx
package-lock.json
40 changes: 39 additions & 1 deletion website/docs/contributing/website.mdx
Original file line number Diff line number Diff line change
@@ -5,6 +5,7 @@ title: Documentation Site
import { FAQ } from '@site/src/components/FAQ';
import { History } from '@site/src/components/History';
import { Stability } from '@site/src/components/Stability';
import { ExternalCodeEmbed } from '@site/src/components/ExternalCodeEmbed';

# Website Contributing Guidelines

@@ -145,7 +146,8 @@ import { FAQ } from '@site/src/components/FAQ';

- The **FAQ** component can be utilized in any section or page.
- Code blocks are compatible and can be used within the **FAQ** component.
:::

:::

<FAQ title='Example'>
<FAQ title='Title'>
@@ -157,6 +159,42 @@ import { FAQ } from '@site/src/components/FAQ';

---

### ExternalCodeEmbed

{/* prettier-ignore-start */}
```tsx
import { ExternalCodeEmbed } from '@site/src/components/ExternalCodeEmbed';

<ExternalCodeEmbed
url='https://github.com/sidorares/node-mysql2/blob/75b05f0765c9edd0c0be8f18d85be05618770cca/.prettierrc'
language='json'
/>

<ExternalCodeEmbed
url='https://raw.githubusercontent.com/sidorares/node-mysql2/master/tools/parse-row.js'
language='js'
extractMethod='parseC'
methodType='function'
/>
```
{/* prettier-ignore-end */}

<FAQ title='Example'>
<ExternalCodeEmbed
url='https://raw.githubusercontent.com/sidorares/node-mysql2/master/.prettierrc'
language='json'
/>

<ExternalCodeEmbed
url='https://raw.githubusercontent.com/sidorares/node-mysql2/master/tools/parse-row.js'
language='js'
extractMethod='parseC'
methodType='function'
/>
</FAQ>

---

## Running Tests

```bash
41 changes: 39 additions & 2 deletions website/docs/documentation/prepared-statements.mdx
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
tags: [Prepared Statements, execute]
---

# Prepared Statements

## Automatic creation, cached and re-used by connection
@@ -39,11 +43,11 @@ connection.prepare('select ? + ? as tests', (err, statement) => {

Note that you should not use statement after connection reset (`changeUser()` or disconnect). Statement scope is connection, you need to prepare statement for each new connection in order to use it.

# Configuration
## Configuration

`maxPreparedStatements` : We keep the cached statements in a [lru-cache](https://github.com/isaacs/node-lru-cache). Default size is `16000` but you can use this option to override it. Any statements that are dropped from cache will be `closed`.

# Serialization of bind parameters
## Serialization of bind parameters

The bind parameter values passed to `execute` are serialized JS -> MySQL as:

@@ -57,3 +61,36 @@ The bind parameter values passed to `execute` are serialized JS -> MySQL as:
- Other -> `VAR_STRING`

Passing in `undefined` or a `function` will result in an error.

## Prepared Statements Helper

MySQL2 provides `execute` helper which will prepare and query the statement. You can also manually prepare / unprepare statement with `prepare` / `unprepare` methods.

```js
connection.execute(
'select ?+1 as qqq, ? as rrr, ? as yyy',
[1, null, 3],
(err, rows, fields) => {
console.log(err, rows, fields);
connection.execute(
'select ?+1 as qqq, ? as rrr, ? as yyy',
[3, null, 3],
(err, rows, fields) => {
console.log(err, rows, fields);
connection.unprepare('select ?+1 as qqq, ? as rrr, ? as yyy');
connection.execute(
'select ?+1 as qqq, ? as rrr, ? as yyy',
[3, null, 3],
(err, rows, fields) => {
console.log(err, rows, fields);
}
);
}
);
}
);
```

## Examples

For Prepared Statements examples, please see [here](http://localhost:3000/node-mysql2/docs/examples/queries/prepared-statements).
2 changes: 1 addition & 1 deletion website/docs/documentation/promise-wrapper.mdx
Original file line number Diff line number Diff line change
@@ -72,4 +72,4 @@ co(function* () {
});
```

Examples in [/examples/promise-co-await](/docs/examples/promise-co-await)
Examples in [/examples/promise-co-await](/docs/examples/promise-wrapper/co-await)
4 changes: 2 additions & 2 deletions website/docs/documentation/typescript-examples.mdx
Original file line number Diff line number Diff line change
@@ -401,10 +401,10 @@ For `ProcedureCallPacket<RowDataPacket[]>`, please see the following examples.

You can also check some code examples using **MySQL2** and **TypeScript** to understand advanced concepts:

- [Extending and using **Interfaces** with `RowDataPacket`](/docs/examples/typescript/row-data/row-data-packet)
- [Extending and using **Interfaces** with `RowDataPacket`](/docs/examples/typescript/row-data/index)
- [Extending and using **Interfaces** with `RowDataPacket` and `rowAsArray`](/docs/examples/typescript/row-data/row-as-array)
- [Extending and using **Interfaces** with `RowDataPacket` and `multipleStatements`](/docs/examples/typescript/row-data/multi-statements)
- [Extending and using **Interfaces** with `RowDataPacket`, `rowAsArray` and `multipleStatements`](/docs/examples/typescript/row-data/row-as-array-multi-statements)
- [Checking for `ResultSetHeader`, extending and using **Interfaces** with `RowDataPacket` from `ProcedureCallPacket`](/docs/examples/typescript/procedure-call/procedure-call-packet)
- [Checking for `ResultSetHeader`, extending and using **Interfaces** with `RowDataPacket` from `ProcedureCallPacket`](/docs/examples/typescript/procedure-call/index)
- [Checking for `ResultSetHeader`, extending and using **Interfaces** with `RowDataPacket` and `rowAsArray` from `ProcedureCallPacket`](/docs/examples/typescript/procedure-call/row-as-array)
- [Creating a basic custom **MySQL2** **Class**](/docs/examples/typescript/basic-custom-class)
Loading

0 comments on commit 323ab12

Please sign in to comment.