Skip to content

Commit aa3f036

Browse files
karenc-bqkarenc-bq
authored
docs: update documentation and sample code for updated API (#543)
1 parent bc54309 commit aa3f036

23 files changed

+853
-57
lines changed

‎docs/Documentation.md‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,20 +5,32 @@
55
- [Logging](../docs/using-the-nodejs-wrapper/UsingTheNodejsWrapper.md#logging)
66
- [Telemetry](../docs/using-the-nodejs-wrapper/Telemetry.md)
77
- [Database Dialects](../docs/using-the-nodejs-wrapper/DatabaseDialects.md)
8+
- [Driver Dialects](../docs/using-the-nodejs-wrapper/DriverDialects.md)
9+
- [Configuration Presets](../docs/using-the-nodejs-wrapper/ConfigurationPresets.md)
10+
- [Session State](../docs/using-the-nodejs-wrapper/SessionState.md)
11+
- [Support for RDS Multi-AZ DB Cluster](../docs/using-the-nodejs-wrapper/SupportForRDSMultiAzDBCluster.md)
12+
- [Using the AWS Clients](../docs/using-the-nodejs-wrapper/UsingTheAwsClients.md)
13+
- [Using the Connection Pool](../docs/using-the-nodejs-wrapper/UsingTheConnectionPool.md)
814
- [Plugins](./using-the-nodejs-wrapper/UsingTheNodejsWrapper.md#plugins)
915
- [Failover Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheFailoverPlugin.md)
1016
- [Failover Configuration Guide](./using-the-nodejs-wrapper/FailoverConfigurationGuide.md)
11-
- [Host Monitoring Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheHostMonitoringPlugin.md);
17+
- [Failover2 Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheFailover2Plugin.md)
18+
- [Host Monitoring Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheHostMonitoringPlugin.md)
1219
- [Read-Write Splitting Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheReadWriteSplittingPlugin.md)
20+
- [Fastest Response Strategy Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheFastestResponseStrategyPlugin.md)
1321
- [Okta Authentication Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheOktaAuthPlugin.md)
1422
- [Federated Authentication Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheFederatedAuthPlugin.md)
1523
- [IAM Authentication Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheIamAuthenticationPlugin.md)
1624
- [Aurora Initial Connection Strategy Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md)
1725
- [AWS Secrets Manager Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheAwsSecretsManagerPlugin.md)
1826
- [Aurora Connection Tracker Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheAuroraConnectionTrackerPlugin.md)
1927
- [Blue/Green Deployment Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheBlueGreenPlugin.md)
28+
- [Custom Endpoint Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheCustomEndpointPlugin.md)
29+
- [Developer Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheDeveloperPlugin.md)
30+
- [Limitless Connection Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheLimitlessConnectionPlugin.md)
2031
- [Host Availability Strategy](./using-the-nodejs-wrapper/HostAvailabilityStrategy.md)
2132
- [Reader Selection Strategies](./using-the-nodejs-wrapper/ReaderSelectionStrategies.md)
33+
- [Custom Configuration](./using-the-nodejs-wrapper/custom-configuration/AwsCredentialsConfiguration.md)
2234
- Examples
2335
- [Running the AWS Advanced NodeJS Wrapper Code Samples](./../examples/aws_driver_example/README.md)
2436
- [Using The NodeJS Wrapper with Prisma ORM](./../examples/prisma_example/README.md)
@@ -27,6 +39,7 @@
2739
- [Setting Up the AWS Advanced NodeJS Wrapper](../docs/development-guide/DevelopmentGuide.md#setting-up-the-aws-advanced-nodejs-wrapper)
2840
- [Testing Overview](../docs/development-guide/DevelopmentGuide.md#testing-overview)
2941
- [Performance Tests](../docs/development-guide/DevelopmentGuide.md#performance-tests)
42+
- [Integration Tests](../docs/development-guide/IntegrationTests.md)
3043
- [Running the Tests](../docs/development-guide/DevelopmentGuide.md#running-the-tests)
3144
- [Architecture](../docs/development-guide/Architecture.md)
3245
- [Plugin Manager](../docs/development-guide/PluginManager.md)

‎docs/using-the-nodejs-wrapper/UsingTheAwsClients.md‎

Lines changed: 336 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,336 @@
1+
# Using the AWS Advanced NodeJS Wrapper Clients
2+
3+
The AWS Advanced NodeJS Wrapper is a promise-based library that is compatible with the MySQL2 and Node-Postgres community drivers' **promise-based** APIs.
4+
Callback APIs from community drivers are not supported by the wrapper.
5+
6+
### Callback APIs (Not Supported)
7+
8+
**MySQL2 callback API (not supported):**
9+
10+
```typescript
11+
// ❌ This will NOT work with AwsMySQLClient
12+
import mysql from "mysql2";
13+
14+
const connection = mysql.createConnection({
15+
/* config */
16+
});
17+
connection.query("SELECT NOW()", (error, results, fields) => {
18+
if (error) throw error;
19+
console.log(results[0]);
20+
});
21+
```
22+
23+
**Node-Postgres callback API (not supported):**
24+
25+
```typescript
26+
// ❌ This will NOT work with AwsPGClient
27+
import { Client } from "pg";
28+
29+
const client = new Client({
30+
/* config */
31+
});
32+
client.connect();
33+
client.query("SELECT NOW()", (err, result) => {
34+
if (err) throw err;
35+
console.log(result.rows[0]);
36+
});
37+
```
38+
39+
### Promise-Based APIs (Supported)
40+
41+
**MySQL2 promise-based API:**
42+
43+
```typescript
44+
import { createConnection } from "mysql2/promise";
45+
46+
const connection = await createConnection({
47+
/* config */
48+
});
49+
const [rows] = await connection.query("SELECT NOW()");
50+
console.log(rows[0]);
51+
```
52+
53+
**Node-Postgres promise-based API:**
54+
55+
```typescript
56+
import { Client } from "pg";
57+
58+
const client = new Client({
59+
/* config */
60+
});
61+
await client.connect();
62+
const result = await client.query("SELECT NOW()");
63+
console.log(result.rows[0]);
64+
```
65+
66+
If your application is already using promise-based APIs, migrating from community drivers to the wrapper requires minimal modification to existing execution workflows.
67+
See the sections below for examples of how community driver APIs map to the wrapper APIs.
68+
69+
> [!WARNING]\
70+
> The imports and query parsing shown in these examples are only compatible with AWS Advanced NodeJS Wrapper versions 2.0.0 and above.
71+
> If you are using versions 1.3.0 and earlier, see the [sample code from version 1.3.0](https://github.com/aws/aws-advanced-nodejs-wrapper/tree/1.3.0/examples/aws_driver_example).
72+
73+
## MySQL2 Migration Guide
74+
75+
### Creating a Client
76+
77+
**mysql2:**
78+
79+
```typescript
80+
import { createConnection } from "mysql2/promise";
81+
82+
const connection = await createConnection({
83+
host: "cluster-endpoint",
84+
user: "database-user",
85+
password: "database-pwd",
86+
database: "db",
87+
port: 3306
88+
});
89+
```
90+
91+
**AwsMySQLClient:**
92+
93+
```typescript
94+
import { AwsMySQLClient } from "aws-advanced-nodejs-wrapper/mysql";
95+
96+
const client = new AwsMySQLClient({
97+
host: "cluster-endpoint",
98+
user: "database-user",
99+
password: "database-pwd",
100+
database: "db",
101+
port: 3306
102+
});
103+
104+
await client.connect();
105+
```
106+
107+
### Querying With the Client
108+
109+
#### Basic String Query
110+
111+
**mysql2:**
112+
113+
```typescript
114+
const [rows] = await connection.query("SELECT NOW()");
115+
console.log(rows[0]); // { "NOW()": 2023-12-01T10:30:00.000Z }
116+
```
117+
118+
**AwsMySQLClient:**
119+
120+
```typescript
121+
const [rows] = await client.query("SELECT NOW()");
122+
console.log(rows[0]); // { "NOW()": 2023-12-01T10:30:00.000Z }
123+
```
124+
125+
#### Parameterized Query
126+
127+
**mysql2:**
128+
129+
```typescript
130+
const [rows] = await connection.query("SELECT ? as name, ? as age", ["John", 25]);
131+
console.log(rows[0]); // { name: "John", age: 25 }
132+
console.log(rows[0].name); // "John"
133+
console.log(rows[0].age); // 25
134+
```
135+
136+
**AwsMySQLClient:**
137+
138+
```typescript
139+
const [rows] = await client.query("SELECT ? as name, ? as age", ["John", 25]);
140+
console.log(rows[0]); // { name: "John", age: 25 }
141+
console.log(rows[0].name); // "John"
142+
console.log(rows[0].age); // 25
143+
```
144+
145+
#### Query with Options Object
146+
147+
**mysql2:**
148+
149+
```typescript
150+
const [rows] = await connection.query({
151+
sql: "SELECT ? as name, ? as age",
152+
values: ["Jane", 30]
153+
});
154+
console.log(rows[0]); // { name: "Jane", age: 30 }
155+
console.log(rows[0].name); // "Jane"
156+
console.log(rows[0].age); // 30
157+
```
158+
159+
**AwsMySQLClient:**
160+
161+
```typescript
162+
const [rows] = await client.query({
163+
sql: "SELECT ? as name, ? as age",
164+
values: ["Jane", 30]
165+
});
166+
console.log(rows[0]); // { name: "Jane", age: 30 }
167+
console.log(rows[0].name); // "Jane"
168+
console.log(rows[0].age); // 30
169+
```
170+
171+
#### Prepared Statement
172+
173+
**mysql2:**
174+
175+
```typescript
176+
const [rows] = await connection.execute("SELECT ? as id, ? as status", [1, "active"]);
177+
console.log(rows[0]); // { id: 1, status: "active" }
178+
console.log(rows[0].id); // 1
179+
console.log(rows[0].status); // "active"
180+
```
181+
182+
**AwsMySQLClient:**
183+
184+
```typescript
185+
const [rows] = await client.execute("SELECT ? as id, ? as status", [1, "active"]);
186+
console.log(rows[0]); // { id: 1, status: "active" }
187+
console.log(rows[0].id); // 1
188+
console.log(rows[0].status); // "active"
189+
```
190+
191+
## Node-Postgres Migration Guide
192+
193+
### Creating a Client
194+
195+
**node-postgres:**
196+
197+
```typescript
198+
import { Client } from "pg";
199+
200+
const client = new Client({
201+
host: "cluster-endpoint",
202+
user: "database-user",
203+
password: "database-pwd",
204+
database: "db",
205+
port: 5432
206+
});
207+
208+
await client.connect();
209+
```
210+
211+
**AwsPGClient:**
212+
213+
```typescript
214+
import { AwsPGClient } from "aws-advanced-nodejs-wrapper/pg";
215+
216+
const client = new AwsPGClient({
217+
host: "cluster-endpoint",
218+
user: "database-user",
219+
password: "database-pwd",
220+
database: "db",
221+
port: 5432
222+
});
223+
224+
await client.connect();
225+
```
226+
227+
### Querying With the Client
228+
229+
#### Basic String Query
230+
231+
**node-postgres:**
232+
233+
```typescript
234+
const result = await client.query("SELECT NOW()");
235+
console.log(result.rows[0]); // { now: 2023-12-01T10:30:00.000Z }
236+
```
237+
238+
**AwsPGClient:**
239+
240+
```typescript
241+
const result = await client.query("SELECT NOW()");
242+
console.log(result.rows[0]); // { now: 2023-12-01T10:30:00.000Z }
243+
```
244+
245+
#### Parameterized Query
246+
247+
**node-postgres:**
248+
249+
```typescript
250+
const result = await client.query("SELECT $1::text as name, $2::int as age", ["John", 25]);
251+
console.log(result.rows[0]); // { name: 'John', age: 25 }
252+
```
253+
254+
**AwsPGClient:**
255+
256+
```typescript
257+
const result = await client.query("SELECT $1::text as name, $2::int as age", ["John", 25]);
258+
console.log(result.rows[0]); // { name: 'John', age: 25 }
259+
```
260+
261+
#### Query with Config Object
262+
263+
**node-postgres:**
264+
265+
```typescript
266+
const result = await client.query({
267+
text: "SELECT $1::text as name, $2::int as age",
268+
values: ["Jane", 30]
269+
});
270+
console.log(result.rows[0]); // { name: 'Jane', age: 30 }
271+
```
272+
273+
**AwsPGClient:**
274+
275+
```typescript
276+
const result = await client.query({
277+
text: "SELECT $1::text as name, $2::int as age",
278+
values: ["Jane", 30]
279+
});
280+
console.log(result.rows[0]); // { name: 'Jane', age: 30 }
281+
```
282+
283+
#### Array Row Mode
284+
285+
**node-postgres:**
286+
287+
```typescript
288+
const result = await client.query({
289+
text: "SELECT $1::int as id, $2::text as status",
290+
values: [1, "active"],
291+
rowMode: "array"
292+
});
293+
console.log(result[0]); // [1, 'active']
294+
```
295+
296+
**AwsPGClient:**
297+
298+
```typescript
299+
const result = await client.query({
300+
text: "SELECT $1::int as id, $2::text as status",
301+
values: [1, "active"],
302+
rowMode: "array"
303+
});
304+
console.log(result[0]); // [1, 'active']
305+
```
306+
307+
#### Named Prepared Statement
308+
309+
**node-postgres:**
310+
311+
```typescript
312+
const result = await client.query({
313+
name: "fetch-data",
314+
text: "SELECT $1::int as id, $2::text as name",
315+
values: [1, "test"]
316+
});
317+
console.log(result.rows[0]); // { id: 1, name: 'test' }
318+
```
319+
320+
**AwsPGClient:**
321+
322+
```typescript
323+
const result = await client.query({
324+
name: "fetch-data",
325+
text: "SELECT $1::int as id, $2::text as name",
326+
values: [1, "test"]
327+
});
328+
console.log(result.rows[0]); // { id: 1, name: 'test' }
329+
```
330+
331+
# Sample Code
332+
333+
For sample JavaScript and TypeScript projects using the AWS Advanced NodeJS Wrapper, see the following directories:
334+
335+
- [JavaScript Example](../../examples/javascript_example)
336+
- [TypeScript Example](../../examples/typescript_example)

0 commit comments

Comments
 (0)