0
# MariaDB Node.js Connector
1

2
MariaDB Node.js Connector is a high-performance MariaDB and MySQL connector for Node.js applications. It offers both Promise-based and callback-based APIs with TypeScript definitions, featuring advanced capabilities like insert streaming, pipelining, bulk inserts, and zero-configuration SSL.
3

4
## Package Information
5

6
- **Package Name**: mariadb
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install mariadb`
10

11
## Core Imports
12

13
```javascript
14
// Promise-based API (main entry point)
15
const mariadb = require("mariadb");
16
const { createConnection, createPool, createPoolCluster, importFile, SqlError, version } = require("mariadb");
17
```
18

19
ES Modules:
20

21
```typescript
22
import * as mariadb from "mariadb";
23
import { createConnection, createPool, createPoolCluster, importFile, SqlError, version } from "mariadb";
24
```
25

26
Callback-based API:
27

28
```javascript
29
const mariadb = require("mariadb/callback");
30
const { createConnection, createPool, createPoolCluster, importFile, SqlError, version } = require("mariadb/callback");
31
```
32

33
## Basic Usage
34

35
```javascript
36
const mariadb = require("mariadb");
37

38
// Create connection
39
const connection = await mariadb.createConnection({
40
  host: "localhost",
41
  user: "root", 
42
  password: "password",
43
  database: "test"
44
});
45

46
// Execute query
47
const rows = await connection.query("SELECT * FROM users WHERE age > ?", [18]);
48
console.log(rows);
49

50
// Close connection
51
await connection.end();
52
```
53

54
## Architecture
55

56
The MariaDB connector is built around several key components:
57

58
- **Connection API**: Individual database connections with Promise or callback interfaces
59
- **Pool API**: Connection pooling for efficient resource management and scalability
60
- **Cluster API**: Pool clustering for load balancing and high availability
61
- **Configuration System**: Comprehensive options for connection behavior, timeouts, and data formatting
62
- **Type System**: Full TypeScript support with detailed type definitions for all APIs
63
- **Error Handling**: Structured error objects with SQL state codes and detailed error information
64

65
## Capabilities
66

67
### Connection Management
68

69
Core database connection functionality for establishing, managing, and executing queries on individual database connections. Supports both Promise-based and callback-based APIs.
70

71
```typescript { .api }
72
function createConnection(config: string | ConnectionConfig): Promise<Connection>;
73

74
interface Connection {
75
  query<T>(sql: string | QueryOptions, values?: any): Promise<T>;
76
  execute<T>(sql: string | QueryOptions, values?: any): Promise<T>;
77
  beginTransaction(): Promise<void>;
78
  commit(): Promise<void>;
79
  rollback(): Promise<void>;
80
  end(): Promise<void>;
81
}
82
```
83

84
[Connection Management](./connections.md)
85

86
### Connection Pooling
87

88
Connection pooling system for managing multiple database connections efficiently. Provides automatic connection lifecycle management, configurable pool sizing, and resource optimization.
89

90
```typescript { .api }
91
function createPool(config: string | PoolConfig): Pool;
92

93
interface Pool {
94
  getConnection(): Promise<PoolConnection>;
95
  query<T>(sql: string | QueryOptions, values?: any): Promise<T>;
96
  execute<T>(sql: string | QueryOptions, values?: any): Promise<T>;
97
  end(): Promise<void>;
98
  totalConnections(): number;
99
  activeConnections(): number;
100
  idleConnections(): number;
101
}
102
```
103

104
[Connection Pooling](./pooling.md)
105

106
### Pool Clustering
107

108
Pool clustering functionality for load balancing across multiple database pools and high availability scenarios. Supports node management, failover, and flexible connection routing.
109

110
```typescript { .api }
111
function createPoolCluster(config?: PoolClusterConfig): PoolCluster;
112

113
interface PoolCluster {
114
  add(id: string, config: PoolConfig): void;
115
  remove(pattern: string): void;
116
  getConnection(pattern?: string, selector?: string): Promise<PoolConnection>;
117
  of(pattern?: string, selector?: string): FilteredPoolCluster;
118
  end(): Promise<void>;
119
}
120
```
121

122
[Pool Clustering](./clustering.md)
123

124
### Configuration Options
125

126
Comprehensive configuration system covering connection parameters, timeouts, data formatting, SSL settings, and performance tuning options.
127

128
```typescript { .api }
129
interface ConnectionConfig {
130
  host?: string;
131
  port?: number;
132
  user?: string;
133
  password?: string;
134
  database?: string;
135
  ssl?: boolean | SSLConfig;
136
  connectTimeout?: number;
137
  queryTimeout?: number;
138
  // ... extensive configuration options
139
}
140

141
function defaultOptions(config?: ConnectionConfig): any;
142
```
143

144
[Configuration](./configuration.md)
145

146
### Query Operations
147

148
Advanced querying capabilities including prepared statements, batch operations, streaming queries, and transaction management with comprehensive type safety.
149

150
```typescript { .api }
151
interface QueryOptions {
152
  sql: string;
153
  nestTables?: boolean;
154
  typeCast?: TypeCastFunction;
155
  rowsAsArray?: boolean;
156
  timeout?: number;
157
}
158

159
interface Prepare {
160
  execute<T>(values?: any): Promise<T>;
161
  executeStream(values?: any): Readable;
162
  close(): void;
163
}
164
```
165

166
[Query Operations](./queries.md)
167

168
### Error Handling
169

170
Structured error handling with detailed SQL error information, error codes, and connection state management for robust application development.
171

172
```typescript { .api }
173
interface SqlError extends Error {
174
  code: string | null;
175
  errno: number;
176
  sqlState?: string | null;
177
  sqlMessage: string | null;
178
  sql: string | null;
179
  fatal: boolean;
180
}
181

182
const SqlError: SqlErrorConstructor;
183
```
184

185
[Error Handling](./errors.md)
186

187
### SQL File Import
188

189
Import and execute SQL files directly into the database. Supports both Promise-based and callback-based APIs for database initialization and migration tasks.
190

191
```typescript { .api }
192
/** Import SQL file (Promise-based) */
193
function importFile(config: ImportFileConfig): Promise<void>;
194

195
interface ImportFileConfig extends ConnectionConfig {
196
  /** SQL file path to import */
197
  file: string;
198
}
199
```
200

201
[SQL File Import](./connections.md#sql-file-import)
202

203
### Callback API
204

205
Complete callback-based API matching the Promise API but using Node.js-style callbacks. All async methods use `(err, result, meta?) => void` callback signature.
206

207
```typescript { .api }
208
// Callback-based entry points
209
function createConnection(config: string | ConnectionConfig): Connection; // Returns callback-based Connection
210
function createPool(config: string | PoolConfig): Pool; // Returns callback-based Pool
211
function createPoolCluster(config?: PoolClusterConfig): PoolCluster; // Returns callback-based PoolCluster
212
function importFile(config: ImportFileConfig, callback: (err: SqlError | null) => void): void;
213
```
214

215
[Callback API](./callbacks.md)
216

217
### Package Constants
218

219
Core package constants and utilities exported by the mariadb module.
220

221
```typescript { .api }
222
/** Package version string */
223
const version: string;
224

225
/** SQL Error constructor class */
226
const SqlError: SqlErrorConstructor;
227

228
/** Get default connection options */
229
function defaultOptions(config?: ConnectionConfig): any;
230
```
231

232
[Type Definitions](./types.md)
233

234
## Type Definitions
235

236
```typescript { .api }
237
interface UpsertResult {
238
  affectedRows: number;
239
  insertId: number | bigint;
240
  warningStatus: number;
241
}
242

243
interface ConnectionInfo {
244
  threadId: number | null;
245
  status: number;
246
  serverVersion: ServerVersion;
247
  serverCapabilities: number;
248
  isMariaDB(): boolean;
249
  hasMinVersion(major: number, minor: number, patch: number): boolean;
250
}
251

252
interface ServerVersion {
253
  raw: string;
254
  mariaDb: boolean;
255
  major: number;
256
  minor: number;
257
  patch: number;
258
}
259

260
interface FieldInfo {
261
  collation: Collation;
262
  columnLength: number;
263
  columnType: TypeNumbers;
264
  scale: number;
265
  type: Types;
266
  flags: Flags;
267
  db(): string;
268
  table(): string;
269
  name(): string;
270
  string(): string | null;
271
  buffer(): Buffer | null;
272
  float(): number | null;
273
  int(): number | null;
274
  date(): Date | null;
275
}
276
```