0
# Exception Handling
1

2
Comprehensive exception hierarchy for handling errors and exceptional conditions throughout the driver. All connector exceptions are unchecked (runtime exceptions) at the core level, with JDBC-specific SQLException wrappers where required.
3

4
## Capabilities
5

6
### Base Exception
7

8
Core exception class that all connector exceptions extend.
9

10
```java { .api }
11
package com.mysql.cj.exceptions;
12

13
public class CJException extends RuntimeException {
14
    public CJException();
15
    public CJException(String message);
16
    public CJException(Throwable cause);
17
    public CJException(String message, Throwable cause);
18
}
19
```
20

21
### Communication Exceptions
22

23
Exceptions related to network communication failures.
24

25
```java { .api }
26
package com.mysql.cj.exceptions;
27

28
public class CJCommunicationsException extends CJException {
29
    public CJCommunicationsException(String message);
30
    public CJCommunicationsException(String message, Throwable cause);
31
}
32

33
public class UnableToConnectException extends CJException {
34
    public UnableToConnectException(String message);
35
    public UnableToConnectException(String message, Throwable cause);
36
}
37

38
package com.mysql.cj.jdbc.exceptions;
39

40
public class CommunicationsException extends java.sql.SQLException {
41
    public CommunicationsException(String message, Throwable underlyingException);
42
}
43
```
44

45
### Timeout and Cancellation Exceptions
46

47
Exceptions for timeouts and cancelled operations.
48

49
```java { .api }
50
package com.mysql.cj.exceptions;
51

52
public class CJTimeoutException extends CJException {
53
    public CJTimeoutException(String message);
54
}
55

56
public class OperationCancelledException extends CJException {
57
    public OperationCancelledException(String message);
58
}
59

60
package com.mysql.cj.jdbc.exceptions;
61

62
public class MySQLTimeoutException extends java.sql.SQLException {
63
    public MySQLTimeoutException();
64
    public MySQLTimeoutException(String message);
65
}
66

67
public class MySQLStatementCancelledException extends java.sql.SQLException {
68
    public MySQLStatementCancelledException();
69
    public MySQLStatementCancelledException(String message);
70
}
71

72
public class MySQLQueryInterruptedException extends java.sql.SQLException {
73
    public MySQLQueryInterruptedException();
74
}
75
```
76

77
### Transaction Exceptions
78

79
Exceptions related to transaction failures.
80

81
```java { .api }
82
package com.mysql.cj.jdbc.exceptions;
83

84
public class MySQLTransactionRollbackException extends java.sql.SQLException
85
    implements DeadlockTimeoutRollbackMarker {
86
    public MySQLTransactionRollbackException();
87
    public MySQLTransactionRollbackException(String message);
88
}
89

90
public interface DeadlockTimeoutRollbackMarker {
91
    // Marker interface for deadlock/timeout exceptions
92
}
93
```
94

95
### Data Conversion Exceptions
96

97
Exceptions for data type conversion errors.
98

99
```java { .api }
100
package com.mysql.cj.exceptions;
101

102
public class DataConversionException extends CJException {
103
    public DataConversionException(String message);
104
}
105

106
public class DataReadException extends CJException {
107
    public DataReadException(String message);
108
    public DataReadException(Throwable cause);
109
}
110

111
public class DataTruncationException extends CJException {
112
    public DataTruncationException(String message);
113
}
114

115
public class NumberOutOfRange extends CJException {
116
    public NumberOutOfRange(String message);
117
}
118

119
package com.mysql.cj.jdbc.exceptions;
120

121
public class MysqlDataTruncation extends java.sql.DataTruncation {
122
    public MysqlDataTruncation(String message, int index, boolean parameter,
123
                              boolean read, int dataSize, int transferSize, int vendorErrorCode);
124
}
125
```
126

127
### Connection State Exceptions
128

129
Exceptions for invalid connection states.
130

131
```java { .api }
132
package com.mysql.cj.exceptions;
133

134
public class ConnectionIsClosedException extends CJException {
135
    public ConnectionIsClosedException();
136
    public ConnectionIsClosedException(String message);
137
}
138

139
public class StatementIsClosedException extends CJException {
140
    public StatementIsClosedException();
141
    public StatementIsClosedException(String message);
142
}
143

144
public class CJConnectionFeatureNotAvailableException extends CJException {
145
    public CJConnectionFeatureNotAvailableException();
146
}
147

148
public class InvalidConnectionAttributeException extends CJException {
149
    public InvalidConnectionAttributeException(String message);
150
}
151

152
package com.mysql.cj.jdbc.exceptions;
153

154
public class ConnectionFeatureNotAvailableException extends java.sql.SQLException {
155
    public ConnectionFeatureNotAvailableException(String message, Throwable underlyingException);
156
}
157

158
public class NotUpdatable extends java.sql.SQLException {
159
    public NotUpdatable(String message);
160
}
161
```
162

163
### Operation Not Supported Exceptions
164

165
Exceptions for unsupported operations.
166

167
```java { .api }
168
package com.mysql.cj.exceptions;
169

170
public class CJOperationNotSupportedException extends CJException {
171
    public CJOperationNotSupportedException();
172
    public CJOperationNotSupportedException(String message);
173
}
174

175
public class FeatureNotAvailableException extends CJException {
176
    public FeatureNotAvailableException(String message);
177
}
178

179
public class UnsupportedConnectionStringException extends CJException {
180
    public UnsupportedConnectionStringException();
181
}
182

183
package com.mysql.cj.jdbc.exceptions;
184

185
public class OperationNotSupportedException extends java.sql.SQLException {
186
    public OperationNotSupportedException();
187
    public OperationNotSupportedException(String message);
188
}
189
```
190

191
### Authentication and Security Exceptions
192

193
Exceptions for authentication and security failures.
194

195
```java { .api }
196
package com.mysql.cj.exceptions;
197

198
public class PasswordExpiredException extends CJException {
199
    public PasswordExpiredException();
200
    public PasswordExpiredException(String message);
201
}
202

203
public class RSAException extends CJException {
204
    public RSAException(String message);
205
    public RSAException(String message, Throwable cause);
206
}
207

208
public class SSLParamsException extends CJException {
209
    public SSLParamsException(String message);
210
    public SSLParamsException(String message, Throwable cause);
211
}
212

213
package com.mysql.cj.jdbc.exceptions;
214

215
public class ClosedOnExpiredPasswordException extends java.sql.SQLException {
216
    public ClosedOnExpiredPasswordException();
217
}
218
```
219

220
### Protocol Exceptions
221

222
Exceptions related to protocol violations.
223

224
```java { .api }
225
package com.mysql.cj.exceptions;
226

227
public class CJPacketTooBigException extends CJException {
228
    public CJPacketTooBigException();
229
    public CJPacketTooBigException(String message);
230
}
231

232
public class WrongArgumentException extends CJException {
233
    public WrongArgumentException(String message);
234
}
235

236
package com.mysql.cj.jdbc.exceptions;
237

238
public class PacketTooBigException extends java.sql.SQLException {
239
    public PacketTooBigException(long packetSize);
240
}
241
```
242

243
### Property Exceptions
244

245
Exceptions for property handling.
246

247
```java { .api }
248
package com.mysql.cj.exceptions;
249

250
public class PropertyNotModifiableException extends CJException {
251
    public PropertyNotModifiableException(String message);
252
}
253
```
254

255
### Assertion Failures
256

257
Exception for assertion failures (should never occur in production).
258

259
```java { .api }
260
package com.mysql.cj.exceptions;
261

262
public class AssertionFailedException extends CJException {
263
    public AssertionFailedException(String message);
264
}
265
```
266

267
### Exception Interceptor
268

269
Interface for intercepting and modifying exceptions.
270

271
```java { .api }
272
package com.mysql.cj.exceptions;
273

274
public interface ExceptionInterceptor {
275
    // Initialize interceptor
276
    ExceptionInterceptor init(Properties props, Log log);
277

278
    // Destroy interceptor
279
    void destroy();
280

281
    // Intercept exception
282
    Exception interceptException(Exception sqlEx);
283
}
284

285
public class ExceptionInterceptorChain implements ExceptionInterceptor {
286
    public ExceptionInterceptorChain(String interceptorClasses, Properties props, Log log);
287

288
    public ExceptionInterceptor init(Properties props, Log log);
289
    public void destroy();
290
    public Exception interceptException(Exception sqlEx);
291
}
292
```
293

294
### Exception Factory
295

296
Factory for creating exceptions with proper initialization.
297

298
```java { .api }
299
package com.mysql.cj.exceptions;
300

301
public class ExceptionFactory {
302
    // Create exception of specific type
303
    public static <T extends CJException> T createException(Class<T> clazz, String message);
304
    public static <T extends CJException> T createException(Class<T> clazz, String message,
305
                                                           ExceptionInterceptor exceptionInterceptor);
306
    public static <T extends CJException> T createException(Class<T> clazz, Throwable cause);
307
    public static <T extends CJException> T createException(Class<T> clazz, String message,
308
                                                           Throwable cause);
309
}
310
```
311

312
### MySQL Error Numbers
313

314
Constants for MySQL server error numbers.
315

316
```java { .api }
317
package com.mysql.cj.exceptions;
318

319
public class MysqlErrorNumbers {
320
    // Connection errors
321
    public static final int ER_SOCKET_UNEXPECTED_CLOSE = 2013;
322

323
    // Access denied errors
324
    public static final int ER_ACCESS_DENIED_ERROR = 1045;
325

326
    // Password errors
327
    public static final int ER_MUST_CHANGE_PASSWORD = 1820;
328
    public static final int ER_MUST_CHANGE_PASSWORD_LOGIN = 1862;
329

330
    // Deadlock and lock wait timeout
331
    public static final int ER_LOCK_WAIT_TIMEOUT = 1205;
332
    public static final int ER_LOCK_DEADLOCK = 1213;
333

334
    // Constraint violations
335
    public static final int ER_DUP_ENTRY = 1062;
336
    public static final int ER_NO_REFERENCED_ROW = 1216;
337
    public static final int ER_ROW_IS_REFERENCED = 1217;
338

339
    // Table/database errors
340
    public static final int ER_NO_SUCH_TABLE = 1146;
341
    public static final int ER_BAD_DB_ERROR = 1049;
342
    public static final int ER_BAD_TABLE_ERROR = 1051;
343

344
    // Column errors
345
    public static final int ER_BAD_FIELD_ERROR = 1054;
346

347
    // Data errors
348
    public static final int ER_DATA_TOO_LONG = 1406;
349
    public static final int ER_TRUNCATED_WRONG_VALUE = 1292;
350

351
    // Too many connections
352
    public static final int ER_CON_COUNT_ERROR = 1040;
353

354
    // Query errors
355
    public static final int ER_SYNTAX_ERROR = 1064;
356
    public static final int ER_PARSE_ERROR = 1064;
357

358
    // ... many more error codes
359
}
360
```
361

362
### SQL Error Mapping
363

364
Utility for mapping MySQL errors to SQL states.
365

366
```java { .api }
367
package com.mysql.cj.jdbc.exceptions;
368

369
public class SQLError {
370
    // Create SQLException with proper SQL state
371
    public static SQLException createSQLException(String message, String sqlState,
372
                                                 ExceptionInterceptor interceptor);
373
    public static SQLException createSQLException(String message, String sqlState, int vendorErrorCode,
374
                                                 ExceptionInterceptor interceptor);
375

376
    // Get localized message
377
    public static String get(String key);
378

379
    // SQL state constants
380
    public static final String SQL_STATE_GENERAL_ERROR = "S1000";
381
    public static final String SQL_STATE_COMMUNICATION_LINK_FAILURE = "08S01";
382
    public static final String SQL_STATE_CONNECTION_NOT_OPEN = "08003";
383
    public static final String SQL_STATE_CONNECTION_IN_USE = "08002";
384
    public static final String SQL_STATE_ILLEGAL_ARGUMENT = "S1009";
385
    public static final String SQL_STATE_SYNTAX_ERROR = "42000";
386
    public static final String SQL_STATE_TIMEOUT_EXPIRED = "S1T00";
387
}
388

389
public class SQLExceptionsMapping {
390
    // Map CJ exceptions to SQL exceptions
391
    public static SQLException translateException(Throwable ex, ExceptionInterceptor interceptor);
392
}
393
```
394

395
### X DevAPI Error
396

397
Exception for X DevAPI specific errors.
398

399
```java { .api }
400
package com.mysql.cj.xdevapi;
401

402
public class XDevAPIError extends com.mysql.cj.exceptions.CJException {
403
    public XDevAPIError(String message);
404
    public XDevAPIError(String message, Throwable cause);
405
}
406
```
407

408
### Streaming Notifiable
409

410
Interface for streaming-related exceptions.
411

412
```java { .api }
413
package com.mysql.cj.exceptions;
414

415
public interface StreamingNotifiable {
416
    // Notify that streaming is in progress
417
    void setWasStreamingResults();
418
}
419
```
420

421
Usage examples:
422

423
```java
424
// Catch specific exception
425
try {
426
    conn.createStatement().executeQuery("SELECT * FROM users");
427
} catch (CommunicationsException e) {
428
    System.out.println("Connection lost: " + e.getMessage());
429
    // Attempt reconnection
430
}
431

432
// Handle timeout
433
try {
434
    stmt.setQueryTimeout(5);
435
    stmt.executeQuery("SELECT * FROM large_table");
436
} catch (MySQLTimeoutException e) {
437
    System.out.println("Query timed out after 5 seconds");
438
}
439

440
// Handle deadlock
441
try {
442
    // Perform transaction
443
} catch (MySQLTransactionRollbackException e) {
444
    if (e instanceof DeadlockTimeoutRollbackMarker) {
445
        System.out.println("Deadlock detected, retrying...");
446
        // Retry transaction
447
    }
448
}
449

450
// Check MySQL error code
451
try {
452
    stmt.executeUpdate("INSERT INTO users (id, name) VALUES (1, 'Alice')");
453
} catch (SQLException e) {
454
    if (e.getErrorCode() == MysqlErrorNumbers.ER_DUP_ENTRY) {
455
        System.out.println("Duplicate key error");
456
    }
457
}
458

459
// Use exception interceptor
460
String url = "jdbc:mysql://localhost:3306/mydb" +
461
             "?exceptionInterceptors=com.mycompany.MyExceptionInterceptor";
462
Connection conn = DriverManager.getConnection(url);
463
```
464