1 | // This file was modified by Oracle on November 04, 2021.
|
2 | // Type definitions and corresponding descriptions were introduced for the
|
3 | // connection options relevant for multifactor authentication.
|
4 | // Modifications copyright (c) 2021, Oracle and/or its affiliates.
|
5 |
|
6 | import { EventEmitter } from 'events';
|
7 | import { Readable } from 'stream';
|
8 | import { Query, QueryError } from './protocol/sequences/Query.js';
|
9 | import { Prepare, PrepareStatementInfo } from './protocol/sequences/Prepare.js';
|
10 | import {
|
11 | OkPacket,
|
12 | FieldPacket,
|
13 | RowDataPacket,
|
14 | ResultSetHeader,
|
15 | OkPacketParams,
|
16 | ErrorPacketParams,
|
17 | } from './protocol/packets/index.js';
|
18 | import { Connection as PromiseConnection } from '../../../promise.js';
|
19 | import { AuthPlugin } from './Auth.js';
|
20 | import { QueryableBase } from './protocol/sequences/QueryableBase.js';
|
21 | import { ExecutableBase } from './protocol/sequences/ExecutableBase.js';
|
22 | import { TypeCast } from './parsers/typeCast.js';
|
23 |
|
24 | export interface SslOptions {
|
25 | /**
|
26 | * A string or buffer holding the PFX or PKCS12 encoded private key, certificate and CA certificates
|
27 | */
|
28 | pfx?: string;
|
29 |
|
30 | /**
|
31 | * Either a string/buffer or list of strings/Buffers holding the PEM encoded private key(s) to use
|
32 | */
|
33 | key?: string | string[] | Buffer | Buffer[];
|
34 |
|
35 | /**
|
36 | * A string of passphrase for the private key or pfx
|
37 | */
|
38 | passphrase?: string;
|
39 |
|
40 | /**
|
41 | * A string/buffer or list of strings/Buffers holding the PEM encoded certificate(s)
|
42 | */
|
43 | cert?: string | string[] | Buffer | Buffer[];
|
44 |
|
45 | /**
|
46 | * Either a string/Buffer or list of strings/Buffers of PEM encoded CA certificates to trust.
|
47 | */
|
48 | ca?: string | string[] | Buffer | Buffer[];
|
49 |
|
50 | /**
|
51 | * Either a string or list of strings of PEM encoded CRLs (Certificate Revocation List)
|
52 | */
|
53 | crl?: string | string[];
|
54 |
|
55 | /**
|
56 | * A string describing the ciphers to use or exclude
|
57 | */
|
58 | ciphers?: string;
|
59 |
|
60 | /**
|
61 | * You can also connect to a MySQL server without properly providing the appropriate CA to trust. You should not do this.
|
62 | */
|
63 | rejectUnauthorized?: boolean;
|
64 |
|
65 | /**
|
66 | * Configure the minimum supported version of SSL, the default is TLSv1.2.
|
67 | */
|
68 | minVersion?: string;
|
69 |
|
70 | /**
|
71 | * Configure the maximum supported version of SSL, the default is TLSv1.3.
|
72 | */
|
73 | maxVersion?: string;
|
74 |
|
75 | /**
|
76 | * You can verify the server name identity presented on the server certificate when connecting to a MySQL server.
|
77 | * You should enable this but it is disabled by default right now for backwards compatibility.
|
78 | */
|
79 | verifyIdentity?: boolean;
|
80 | }
|
81 |
|
82 | export interface ConnectionOptions {
|
83 | /**
|
84 | * DECIMAL and NEWDECIMAL types will be returned as numbers if this option is set to `true` ( default: `false`).
|
85 | */
|
86 | decimalNumbers?: boolean;
|
87 |
|
88 | /**
|
89 | * The MySQL user to authenticate as
|
90 | */
|
91 | user?: string;
|
92 |
|
93 | /**
|
94 | * The password of that MySQL user
|
95 | */
|
96 | password?: string;
|
97 |
|
98 | /**
|
99 | * Alias for the MySQL user password. Makes a bit more sense in a multifactor authentication setup (see
|
100 | * "password2" and "password3")
|
101 | */
|
102 | password1?: string;
|
103 |
|
104 | /**
|
105 | * 2nd factor authentication password. Mandatory when the authentication policy for the MySQL user account
|
106 | * requires an additional authentication method that needs a password.
|
107 | * https://dev.mysql.com/doc/refman/8.0/en/multifactor-authentication.html
|
108 | */
|
109 | password2?: string;
|
110 |
|
111 | /**
|
112 | * 3rd factor authentication password. Mandatory when the authentication policy for the MySQL user account
|
113 | * requires two additional authentication methods and the last one needs a password.
|
114 | * https://dev.mysql.com/doc/refman/8.0/en/multifactor-authentication.html
|
115 | */
|
116 | password3?: string;
|
117 |
|
118 | /**
|
119 | * Name of the database to use for this connection
|
120 | */
|
121 | database?: string;
|
122 |
|
123 | /**
|
124 | * The charset for the connection. This is called 'collation' in the SQL-level of MySQL (like utf8_general_ci).
|
125 | * If a SQL-level charset is specified (like utf8mb4) then the default collation for that charset is used.
|
126 | * (Default: 'UTF8_GENERAL_CI')
|
127 | */
|
128 | charset?: string;
|
129 |
|
130 | /**
|
131 | * The hostname of the database you are connecting to. (Default: localhost)
|
132 | */
|
133 | host?: string;
|
134 |
|
135 | /**
|
136 | * The port number to connect to. (Default: 3306)
|
137 | */
|
138 | port?: number;
|
139 |
|
140 | /**
|
141 | * The source IP address to use for TCP connection
|
142 | */
|
143 | localAddress?: string;
|
144 |
|
145 | /**
|
146 | * The path to a unix domain socket to connect to. When used host and port are ignored
|
147 | */
|
148 | socketPath?: string;
|
149 |
|
150 | /**
|
151 | * The timezone used to store local dates. (Default: 'local')
|
152 | */
|
153 | timezone?: string | 'local';
|
154 |
|
155 | /**
|
156 | * The milliseconds before a timeout occurs during the initial connection to the MySQL server. (Default: 10 seconds)
|
157 | */
|
158 | connectTimeout?: number;
|
159 |
|
160 | /**
|
161 | * Stringify objects instead of converting to values. (Default: 'false')
|
162 | */
|
163 | stringifyObjects?: boolean;
|
164 |
|
165 | /**
|
166 | * Allow connecting to MySQL instances that ask for the old (insecure) authentication method. (Default: false)
|
167 | */
|
168 | insecureAuth?: boolean;
|
169 |
|
170 | /**
|
171 | * By specifying a function that returns a readable stream, an arbitrary stream can be sent when sending a local fs file.
|
172 | */
|
173 | infileStreamFactory?: (path: string) => Readable;
|
174 |
|
175 | /**
|
176 | * Determines if column values should be converted to native JavaScript types.
|
177 | *
|
178 | * @default true
|
179 | *
|
180 | * It is not recommended (and may go away / change in the future) to disable type casting, but you can currently do so on either the connection or query level.
|
181 | *
|
182 | * ---
|
183 | *
|
184 | * You can also specify a function to do the type casting yourself:
|
185 | * ```ts
|
186 | * (field: Field, next: () => void) => {
|
187 | * return next();
|
188 | * }
|
189 | * ```
|
190 | *
|
191 | * ---
|
192 | *
|
193 | * **WARNING:**
|
194 | *
|
195 | * YOU MUST INVOKE the parser using one of these three field functions in your custom typeCast callback. They can only be called once:
|
196 | *
|
197 | * ```js
|
198 | * field.string();
|
199 | * field.buffer();
|
200 | * field.geometry();
|
201 | * ```
|
202 |
|
203 | * Which are aliases for:
|
204 | *
|
205 | * ```js
|
206 | * parser.parseLengthCodedString();
|
207 | * parser.parseLengthCodedBuffer();
|
208 | * parser.parseGeometryValue();
|
209 | * ```
|
210 | *
|
211 | * You can find which field function you need to use by looking at `RowDataPacket.prototype._typeCast`.
|
212 | */
|
213 | typeCast?: TypeCast;
|
214 |
|
215 | /**
|
216 | * A custom query format function
|
217 | */
|
218 | queryFormat?: (query: string, values: any) => void;
|
219 |
|
220 | /**
|
221 | * When dealing with big numbers (BIGINT and DECIMAL columns) in the database, you should enable this option
|
222 | * (Default: false)
|
223 | */
|
224 | supportBigNumbers?: boolean;
|
225 |
|
226 | /**
|
227 | * Enabling both supportBigNumbers and bigNumberStrings forces big numbers (BIGINT and DECIMAL columns) to be
|
228 | * always returned as JavaScript String objects (Default: false). Enabling supportBigNumbers but leaving
|
229 | * bigNumberStrings disabled will return big numbers as String objects only when they cannot be accurately
|
230 | * represented with [JavaScript Number objects](https://262.ecma-international.org/5.1/#sec-8.5)
|
231 | * (which happens when they exceed the [-2^53, +2^53] range), otherwise they will be returned as Number objects.
|
232 | * This option is ignored if supportBigNumbers is disabled.
|
233 | */
|
234 | bigNumberStrings?: boolean;
|
235 |
|
236 | /**
|
237 | * Force date types (TIMESTAMP, DATETIME, DATE) to be returned as strings rather then inflated into JavaScript Date
|
238 | * objects. Can be true/false or an array of type names to keep as strings.
|
239 | *
|
240 | * (Default: false)
|
241 | */
|
242 | dateStrings?: boolean | Array<'TIMESTAMP' | 'DATETIME' | 'DATE'>;
|
243 |
|
244 | /**
|
245 | * This will print all incoming and outgoing packets on stdout.
|
246 | * You can also restrict debugging to packet types by passing an array of types (strings) to debug;
|
247 | *
|
248 | * (Default: false)
|
249 | */
|
250 | debug?: any;
|
251 |
|
252 | /**
|
253 | * Generates stack traces on Error to include call site of library entrance ('long stack traces'). Slight
|
254 | * performance penalty for most calls. (Default: true)
|
255 | */
|
256 | trace?: boolean;
|
257 |
|
258 | /**
|
259 | * Allow multiple mysql statements per query. Be careful with this, it exposes you to SQL injection attacks. (Default: false)
|
260 | */
|
261 | multipleStatements?: boolean;
|
262 |
|
263 | /**
|
264 | * List of connection flags to use other than the default ones. It is also possible to blacklist default ones
|
265 | */
|
266 | flags?: Array<string>;
|
267 |
|
268 | /**
|
269 | * object with ssl parameters or a string containing name of ssl profile
|
270 | */
|
271 | ssl?: string | SslOptions;
|
272 |
|
273 | /**
|
274 | * Return each row as an array, not as an object.
|
275 | * This is useful when you have duplicate column names.
|
276 | * This can also be set in the `QueryOption` object to be applied per-query.
|
277 | */
|
278 | rowsAsArray?: boolean;
|
279 |
|
280 | /**
|
281 | * Enable keep-alive on the socket. (Default: true)
|
282 | */
|
283 | enableKeepAlive?: boolean;
|
284 |
|
285 | /**
|
286 | * If keep-alive is enabled users can supply an initial delay. (Default: 0)
|
287 | */
|
288 | keepAliveInitialDelay?: number;
|
289 |
|
290 | charsetNumber?: number;
|
291 |
|
292 | compress?: boolean;
|
293 |
|
294 | authSwitchHandler?: (data: any, callback: () => void) => any;
|
295 |
|
296 | connectAttributes?: { [param: string]: any };
|
297 |
|
298 | isServer?: boolean;
|
299 |
|
300 | maxPreparedStatements?: number;
|
301 |
|
302 | namedPlaceholders?: boolean;
|
303 |
|
304 | nestTables?: boolean | string;
|
305 |
|
306 | passwordSha1?: string;
|
307 |
|
308 | pool?: any;
|
309 |
|
310 | stream?: any;
|
311 |
|
312 | uri?: string;
|
313 |
|
314 | connectionLimit?: number;
|
315 |
|
316 | maxIdle?: number;
|
317 |
|
318 | idleTimeout?: number;
|
319 |
|
320 | Promise?: any;
|
321 |
|
322 | queueLimit?: number;
|
323 |
|
324 | waitForConnections?: boolean;
|
325 |
|
326 | authPlugins?: {
|
327 | [key: string]: AuthPlugin;
|
328 | };
|
329 |
|
330 | /**
|
331 | * Force JSON to be returned as string
|
332 | *
|
333 | * (Default: false)
|
334 | */
|
335 | jsonStrings?: boolean;
|
336 | }
|
337 |
|
338 | declare class Connection extends QueryableBase(ExecutableBase(EventEmitter)) {
|
339 | config: ConnectionOptions;
|
340 |
|
341 | threadId: number;
|
342 |
|
343 | authorized: boolean;
|
344 |
|
345 | static createQuery<
|
346 | T extends
|
347 | | RowDataPacket[][]
|
348 | | RowDataPacket[]
|
349 | | OkPacket
|
350 | | OkPacket[]
|
351 | | ResultSetHeader,
|
352 | >(
|
353 | sql: string,
|
354 | callback?: (
|
355 | err: QueryError | null,
|
356 | result: T,
|
357 | fields: FieldPacket[],
|
358 | ) => any,
|
359 | ): Query;
|
360 | static createQuery<
|
361 | T extends
|
362 | | RowDataPacket[][]
|
363 | | RowDataPacket[]
|
364 | | OkPacket
|
365 | | OkPacket[]
|
366 | | ResultSetHeader,
|
367 | >(
|
368 | sql: string,
|
369 | values: any | any[] | { [param: string]: any },
|
370 | callback?: (
|
371 | err: QueryError | null,
|
372 | result: T,
|
373 | fields: FieldPacket[],
|
374 | ) => any,
|
375 | ): Query;
|
376 |
|
377 | beginTransaction(callback: (err: QueryError | null) => void): void;
|
378 |
|
379 | connect(callback?: (err: QueryError | null) => void): void;
|
380 |
|
381 | commit(callback?: (err: QueryError | null) => void): void;
|
382 |
|
383 | changeUser(
|
384 | options: ConnectionOptions,
|
385 | callback?: (err: QueryError | null) => void,
|
386 | ): void;
|
387 |
|
388 | end(callback?: (err: QueryError | null) => void): void;
|
389 | end(options: any, callback?: (err: QueryError | null) => void): void;
|
390 |
|
391 | destroy(): void;
|
392 |
|
393 | pause(): void;
|
394 |
|
395 | resume(): void;
|
396 |
|
397 | escape(value: any): string;
|
398 |
|
399 | escapeId(value: string): string;
|
400 | escapeId(values: string[]): string;
|
401 |
|
402 | format(sql: string, values?: any | any[] | { [param: string]: any }): string;
|
403 |
|
404 | on(event: string, listener: (...args: any[]) => void): this;
|
405 |
|
406 | rollback(callback: (err: QueryError | null) => void): void;
|
407 |
|
408 | prepare(
|
409 | sql: string,
|
410 | callback?: (err: QueryError | null, statement: PrepareStatementInfo) => any,
|
411 | ): Prepare;
|
412 |
|
413 | unprepare(sql: string): PrepareStatementInfo;
|
414 |
|
415 | serverHandshake(args: any): any;
|
416 |
|
417 | promise(promiseImpl?: PromiseConstructor): PromiseConnection;
|
418 |
|
419 | ping(callback?: (err: QueryError | null) => any): void;
|
420 |
|
421 | writeOk(args?: OkPacketParams): void;
|
422 |
|
423 | writeError(args?: ErrorPacketParams): void;
|
424 |
|
425 | writeEof(warnings?: number, statusFlags?: number): void;
|
426 |
|
427 | writeTextResult(rows?: Array<any>, columns?: Array<any>): void;
|
428 |
|
429 | writePacket(packet: any): void;
|
430 |
|
431 | sequenceId: number;
|
432 | }
|
433 |
|
434 | export { Connection };
|