0
# Type System
1

2
MySQL Connector/J type system for mapping between MySQL database types, JDBC types, and Java types.
3

4
## Capabilities
5

6
### MysqlType Enum
7

8
Comprehensive enumeration of MySQL data types with JDBC type mapping and conversion support.
9

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

13
import java.sql.SQLType;
14

15
public enum MysqlType implements SQLType {
16
    // Numeric types - Integer
17
    BIT("BIT", java.sql.Types.BIT, Boolean.class),
18
    TINYINT("TINYINT", java.sql.Types.TINYINT, Integer.class),
19
    TINYINT_UNSIGNED("TINYINT UNSIGNED", java.sql.Types.SMALLINT, Integer.class),
20
    SMALLINT("SMALLINT", java.sql.Types.SMALLINT, Integer.class),
21
    SMALLINT_UNSIGNED("SMALLINT UNSIGNED", java.sql.Types.INTEGER, Integer.class),
22
    MEDIUMINT("MEDIUMINT", java.sql.Types.INTEGER, Integer.class),
23
    MEDIUMINT_UNSIGNED("MEDIUMINT UNSIGNED", java.sql.Types.INTEGER, Integer.class),
24
    INT("INT", java.sql.Types.INTEGER, Integer.class),
25
    INT_UNSIGNED("INT UNSIGNED", java.sql.Types.BIGINT, Long.class),
26
    BIGINT("BIGINT", java.sql.Types.BIGINT, Long.class),
27
    BIGINT_UNSIGNED("BIGINT UNSIGNED", java.sql.Types.BIGINT, java.math.BigInteger.class),
28

29
    // Numeric types - Floating point
30
    FLOAT("FLOAT", java.sql.Types.REAL, Float.class),
31
    FLOAT_UNSIGNED("FLOAT UNSIGNED", java.sql.Types.REAL, Float.class),
32
    DOUBLE("DOUBLE", java.sql.Types.DOUBLE, Double.class),
33
    DOUBLE_UNSIGNED("DOUBLE UNSIGNED", java.sql.Types.DOUBLE, Double.class),
34
    DECIMAL("DECIMAL", java.sql.Types.DECIMAL, java.math.BigDecimal.class),
35
    DECIMAL_UNSIGNED("DECIMAL UNSIGNED", java.sql.Types.DECIMAL, java.math.BigDecimal.class),
36

37
    // Boolean type
38
    BOOLEAN("BOOLEAN", java.sql.Types.BOOLEAN, Boolean.class),
39

40
    // Date and time types
41
    DATE("DATE", java.sql.Types.DATE, java.sql.Date.class),
42
    TIME("TIME", java.sql.Types.TIME, java.sql.Time.class),
43
    DATETIME("DATETIME", java.sql.Types.TIMESTAMP, java.sql.Timestamp.class),
44
    TIMESTAMP("TIMESTAMP", java.sql.Types.TIMESTAMP, java.sql.Timestamp.class),
45
    YEAR("YEAR", java.sql.Types.DATE, java.sql.Date.class),
46

47
    // String types
48
    CHAR("CHAR", java.sql.Types.CHAR, String.class),
49
    VARCHAR("VARCHAR", java.sql.Types.VARCHAR, String.class),
50
    TINYTEXT("TINYTEXT", java.sql.Types.VARCHAR, String.class),
51
    TEXT("TEXT", java.sql.Types.LONGVARCHAR, String.class),
52
    MEDIUMTEXT("MEDIUMTEXT", java.sql.Types.LONGVARCHAR, String.class),
53
    LONGTEXT("LONGTEXT", java.sql.Types.LONGVARCHAR, String.class),
54

55
    // Binary types
56
    BINARY("BINARY", java.sql.Types.BINARY, byte[].class),
57
    VARBINARY("VARBINARY", java.sql.Types.VARBINARY, byte[].class),
58
    TINYBLOB("TINYBLOB", java.sql.Types.VARBINARY, byte[].class),
59
    BLOB("BLOB", java.sql.Types.LONGVARBINARY, byte[].class),
60
    MEDIUMBLOB("MEDIUMBLOB", java.sql.Types.LONGVARBINARY, byte[].class),
61
    LONGBLOB("LONGBLOB", java.sql.Types.LONGVARBINARY, byte[].class),
62

63
    // Special types
64
    JSON("JSON", java.sql.Types.LONGVARCHAR, String.class),
65
    ENUM("ENUM", java.sql.Types.CHAR, String.class),
66
    SET("SET", java.sql.Types.CHAR, String.class),
67
    GEOMETRY("GEOMETRY", java.sql.Types.BINARY, byte[].class),
68
    VECTOR("VECTOR", java.sql.Types.LONGVARBINARY, byte[].class),
69

70
    // Null and unknown
71
    NULL("NULL", java.sql.Types.NULL, Void.class),
72
    UNKNOWN("UNKNOWN", java.sql.Types.OTHER, Object.class);
73

74
    // Primary public API methods (commonly used)
75
    public String getName();
76
    public int getJdbcType();
77
    public String getClassName();
78

79
    public static MysqlType getByName(String mysqlTypeName);
80
    public static MysqlType getByJdbcType(int jdbcType);
81

82
    // Advanced/internal methods (protocol-level, rarely needed by applications)
83
    public Integer getVendorTypeNumber();
84
    public boolean isDecimal();
85
    public Integer getAllowedFlags();
86
    public long getPrecision();
87
    public String getCreateParams();
88
    public static boolean isBinary(MysqlType mysqlType);
89
    public static boolean supportsConvert(int fromType, int toType);
90
}
91
```
92

93
Usage:
94

95
```java
96
import com.mysql.cj.MysqlType;
97
import java.sql.PreparedStatement;
98

99
// Get MysqlType by name
100
MysqlType type = MysqlType.getByName("VARCHAR");
101
System.out.println("JDBC Type: " + type.getJdbcType());
102
System.out.println("Java Class: " + type.getClassName());
103

104
// Use with PreparedStatement.setNull()
105
PreparedStatement pstmt = conn.prepareStatement("INSERT INTO users (name, age) VALUES (?, ?)");
106
pstmt.setNull(1, MysqlType.VARCHAR);
107

108
// Check type properties
109
if (MysqlType.INT.isDecimal()) {
110
    // Handle numeric type
111
}
112

113
// Check conversion support
114
boolean canConvert = MysqlType.supportsConvert(
115
    java.sql.Types.VARCHAR,
116
    java.sql.Types.INTEGER
117
);
118
```
119

120
### Field Flags
121

122
**Note:** These are internal protocol-level constants within the MysqlType enum, not part of the standard public API. They are package-private and used internally by the driver for MySQL protocol communication. Most applications will not need to use these directly.
123

124
```java { .api }
125
package com.mysql.cj;
126

127
// Internal protocol constants (package-private)
128
public enum MysqlType {
129
    // ... enum constants ...
130

131
    // Field flags (internal use)
132
    static final int FIELD_FLAG_NOT_NULL = 1;
133
    static final int FIELD_FLAG_PRIMARY_KEY = 2;
134
    static final int FIELD_FLAG_UNIQUE_KEY = 4;
135
    static final int FIELD_FLAG_MULTIPLE_KEY = 8;
136
    static final int FIELD_FLAG_BLOB = 16;
137
    static final int FIELD_FLAG_UNSIGNED = 32;
138
    static final int FIELD_FLAG_ZEROFILL = 64;
139
    static final int FIELD_FLAG_BINARY = 128;
140
    static final int FIELD_FLAG_ENUM = 256;
141
    static final int FIELD_FLAG_AUTO_INCREMENT = 512;
142
    static final int FIELD_FLAG_TIMESTAMP = 1024;
143
    static final int FIELD_FLAG_SET = 2048;
144
    static final int FIELD_FLAG_NO_DEFAULT_VALUE = 4096;
145
    static final int FIELD_FLAG_ON_UPDATE_NOW = 8192;
146
    static final int FIELD_FLAG_NUM = 32768;
147
}
148
```
149

150
### Protocol Type Numbers
151

152
**Note:** These are internal protocol-level constants used by the driver for MySQL wire protocol communication. They are package-private and rarely needed by application code. Most applications should use the MysqlType enum constants instead.
153

154
```java { .api }
155
package com.mysql.cj;
156

157
// Internal protocol constants (package-private)
158
public enum MysqlType {
159
    // ... enum constants ...
160

161
    // Protocol type numbers (internal use)
162
    static final int FIELD_TYPE_DECIMAL = 0;
163
    static final int FIELD_TYPE_TINY = 1;
164
    static final int FIELD_TYPE_SHORT = 2;
165
    static final int FIELD_TYPE_LONG = 3;
166
    static final int FIELD_TYPE_FLOAT = 4;
167
    static final int FIELD_TYPE_DOUBLE = 5;
168
    static final int FIELD_TYPE_NULL = 6;
169
    static final int FIELD_TYPE_TIMESTAMP = 7;
170
    static final int FIELD_TYPE_LONGLONG = 8;
171
    static final int FIELD_TYPE_INT24 = 9;
172
    static final int FIELD_TYPE_DATE = 10;
173
    static final int FIELD_TYPE_TIME = 11;
174
    static final int FIELD_TYPE_DATETIME = 12;
175
    static final int FIELD_TYPE_YEAR = 13;
176
    static final int FIELD_TYPE_VARCHAR = 15;
177
    static final int FIELD_TYPE_BIT = 16;
178
    static final int FIELD_TYPE_JSON = 245;
179
    static final int FIELD_TYPE_NEWDECIMAL = 246;
180
    static final int FIELD_TYPE_ENUM = 247;
181
    static final int FIELD_TYPE_SET = 248;
182
    static final int FIELD_TYPE_TINY_BLOB = 249;
183
    static final int FIELD_TYPE_MEDIUM_BLOB = 250;
184
    static final int FIELD_TYPE_LONG_BLOB = 251;
185
    static final int FIELD_TYPE_BLOB = 252;
186
    static final int FIELD_TYPE_VAR_STRING = 253;
187
    static final int FIELD_TYPE_STRING = 254;
188
    static final int FIELD_TYPE_GEOMETRY = 255;
189
}
190
```
191

192
### Charset Mapping
193

194
**Note:** CharsetMapping is an internal implementation class with package-private methods. Most applications should handle charset conversions automatically through connection properties (`characterEncoding`, `connectionCollation`) rather than calling CharsetMapping directly.
195

196
Charset constants and limited static accessor methods for collation and encoding mappings.
197

198
```java { .api }
199
package com.mysql.cj;
200

201
public class CharsetMapping {
202
    // Charset name constants (public static final Strings)
203
    public static final String MYSQL_CHARSET_NAME_utf8mb4 = "utf8mb4";
204
    public static final String MYSQL_CHARSET_NAME_utf8mb3 = "utf8mb3";
205
    public static final String MYSQL_CHARSET_NAME_latin1 = "latin1";
206
    // ... and many more charset name constants
207

208
    // Internal static methods (package-private - not part of public API)
209
    // Most charset conversion is handled automatically by the driver
210
    // Use connection properties: characterEncoding, connectionCollation
211
}
212
```
213

214
Usage:
215

216
```java
217
// For most applications, character encoding is handled automatically via connection properties
218
String url = "jdbc:mysql://localhost:3306/mydb?characterEncoding=UTF-8";
219
Connection conn = DriverManager.getConnection(url, "user", "pass");
220

221
// Or use charset name constants if needed
222
String charset = CharsetMapping.MYSQL_CHARSET_NAME_utf8mb4;
223
```
224

225
### Server Version
226

227
Representation and comparison of MySQL server versions.
228

229
```java { .api }
230
package com.mysql.cj;
231

232
public class ServerVersion implements Comparable<ServerVersion> {
233
    // Constructors
234
    public ServerVersion(int major, int minor, int subminor);
235
    public ServerVersion(String completeVersion, int major, int minor, int subminor);
236

237
    // Version components
238
    public int getMajor();
239
    public int getMinor();
240
    public int getSubminor();
241

242
    // String representation
243
    public String toString();
244

245
    // Comparison
246
    public boolean meetsMinimum(ServerVersion version);
247
    public int compareTo(ServerVersion other);
248

249
    // Static factory (parses version string and creates ServerVersion)
250
    public static ServerVersion parseVersion(String versionString);
251
}
252
```
253

254
Usage:
255

256
```java
257
import com.mysql.cj.ServerVersion;
258

259
// Create version using numeric components
260
ServerVersion v1 = new ServerVersion(8, 0, 33);
261
System.out.println("Major: " + v1.getMajor()); // 8
262
System.out.println("Minor: " + v1.getMinor()); // 0
263
System.out.println("Subminor: " + v1.getSubminor()); // 33
264

265
// Or parse version string using static factory
266
ServerVersion v2 = ServerVersion.parseVersion("8.0.33-MySQL");
267

268
// Check minimum version
269
ServerVersion required = new ServerVersion(8, 0, 0);
270
if (v2.meetsMinimum(required)) {
271
    System.out.println("Server version is compatible");
272
}
273

274
// Compare versions
275
int comparison = v1.compareTo(v2);
276
System.out.println("Comparison: " + comparison); // 0 (equal)
277
```
278

279
### Constants
280

281
Global constants used throughout the driver.
282

283
```java { .api }
284
package com.mysql.cj;
285

286
public class Constants {
287
    // Version information
288
    public static final String CJ_NAME = "MySQL Connector/J";
289
    public static final String CJ_FULL_NAME = "mysql-connector-j";
290
    public static final String CJ_VERSION = "9.2.0";
291
    public static final String CJ_MAJOR_VERSION = "9";
292
    public static final String CJ_MINOR_VERSION = "2";
293
    public static final String CJ_LICENSE = "GPL-2.0 with FOSS exception";
294

295
    // Character encoding
296
    public static final String UTF8MB4 = "utf8mb4";
297
    public static final String UTF8MB3 = "utf8mb3";
298

299
    // Buffer sizes
300
    public static final int IO_BUFFER_SIZE = 16384;
301

302
    // Time constants
303
    public static final long MILLIS_I18N = 1000L;
304
    public static final long SECONDS_I18N = 1L;
305

306
    // SQL states
307
    public static final String SQL_STATE_GENERAL_ERROR = "HY000";
308
    public static final String SQL_STATE_COMMUNICATION_LINK_FAILURE = "08S01";
309
    public static final String SQL_STATE_ILLEGAL_ARGUMENT = "S1009";
310
    public static final String SQL_STATE_MEMORY_ALLOCATION_ERROR = "S1001";
311
    public static final String SQL_STATE_CONNECTION_NOT_OPEN = "08003";
312
    public static final String SQL_STATE_CONNECTION_IN_USE = "08002";
313
    public static final String SQL_STATE_CONNECTION_REJECTED = "08004";
314
    public static final String SQL_STATE_CONNECTION_FAILURE = "08006";
315
    public static final String SQL_STATE_TRANSACTION_RESOLUTION_UNKNOWN = "08007";
316
    public static final String SQL_STATE_INVALID_AUTH_SPEC = "28000";
317
    public static final String SQL_STATE_INVALID_TRANSACTION_STATE = "25000";
318
    public static final String SQL_STATE_FEATURE_NOT_SUPPORTED = "0A000";
319
    public static final String SQL_STATE_INVALID_COLUMN_NUMBER = "S1002";
320
    public static final String SQL_STATE_DRIVER_NOT_CAPABLE = "S1C00";
321
    public static final String SQL_STATE_TIMEOUT_EXPIRED = "S1T00";
322
    public static final String SQL_STATE_CLI_SPECIFIC_CONDITION = "HY000";
323
}
324
```
325

326
### Messages
327

328
Internationalized message strings and resource bundles.
329

330
```java { .api }
331
package com.mysql.cj;
332

333
public class Messages {
334
    // Get localized message
335
    public static String getString(String key);
336
    public static String getString(String key, Object[] args);
337

338
    // Check if key exists
339
    public static boolean containsKey(String key);
340
}
341
```
342

343
Usage:
344

345
```java
346
import com.mysql.cj.Messages;
347

348
// Get error message
349
String msg = Messages.getString("ConnectionImpl.UnableToConnect");
350
System.out.println(msg);
351

352
// Get parameterized message
353
String paramMsg = Messages.getString(
354
    "ConnectionImpl.BadURL",
355
    new Object[] { "invalid-url" }
356
);
357
System.out.println(paramMsg);
358
```
359