0
# MySQL Connector Python
1

2
A comprehensive MySQL database driver written in pure Python, providing complete connectivity for both traditional SQL operations and modern document-based operations. The package offers two complementary interfaces: the traditional `mysql.connector` module with full DB-API 2.0 compliance, and the modern `mysqlx` module supporting MySQL's X DevAPI for document and relational data.
3

4
## Package Information
5

6
- **Package Name**: mysql-connector
7
- **Language**: Python
8
- **Installation**: `pip install mysql-connector`
9
- **Python Compatibility**: Python 2.6+ and 3.3+
10

11
## Core Imports
12

13
Standard MySQL connectivity:
14

15
```python
16
import mysql.connector
17
```
18

19
MySQL X DevAPI for document operations:
20

21
```python
22
import mysqlx
23
```
24

25
## Basic Usage
26

27
### Traditional SQL Connection
28

29
```python
30
import mysql.connector
31

32
# Connect to MySQL database
33
config = {
34
    'user': 'username',
35
    'password': 'password',
36
    'host': 'localhost',
37
    'database': 'mydb',
38
    'port': 3306
39
}
40

41
connection = mysql.connector.connect(**config)
42
cursor = connection.cursor()
43

44
# Execute SQL query
45
cursor.execute("SELECT * FROM users WHERE age > %s", (18,))
46
results = cursor.fetchall()
47

48
for row in results:
49
    print(row)
50

51
cursor.close()
52
connection.close()
53
```
54

55
### Modern Document Operations (X DevAPI)
56

57
```python
58
import mysqlx
59

60
# Connect using X Protocol
61
session = mysqlx.get_session({
62
    'host': 'localhost',
63
    'port': 33060,
64
    'user': 'username',
65
    'password': 'password'
66
})
67

68
# Work with collections (document store)
69
schema = session.get_schema('mydb')
70
collection = schema.get_collection('users')
71

72
# Add documents
73
collection.add({'name': 'John', 'age': 25, 'email': 'john@example.com'}).execute()
74

75
# Find documents
76
docs = collection.find('age > :age').bind('age', 18).execute()
77
for doc in docs:
78
    print(doc)
79

80
session.close()
81
```
82

83
## Architecture
84

85
The package provides two distinct yet complementary APIs:
86

87
- **mysql.connector**: Traditional relational database operations following DB-API 2.0 specifications
88
- **mysqlx**: Modern X DevAPI supporting both document collections and relational tables through X Protocol
89

90
Both modules share common error handling patterns and support advanced features like connection pooling, SSL/TLS encryption, authentication plugins, and comprehensive charset support.
91

92
## Capabilities
93

94
### Database Connections and Pooling
95

96
Core connection functionality with support for connection pooling, failover configurations, SSL/TLS encryption, and various authentication methods including plugin-based authentication.
97

98
```python { .api }
99
def connect(**config):
100
    """Create MySQL connection with configuration options"""
101

102
class MySQLConnection:
103
    """Pure Python MySQL connection implementation"""
104
    
105
class MySQLConnectionPool:
106
    """Connection pool for managing multiple connections"""
107
```
108

109
[Database Connections](./connections.md)
110

111
### SQL Operations and Cursors
112

113
Traditional SQL operations with multiple cursor types for different data access patterns, including dictionary cursors, buffered cursors, prepared statements, and raw data access.
114

115
```python { .api }
116
class MySQLCursor:
117
    """Standard cursor for SQL operations"""
118
    def execute(self, statement, params=None): ...
119
    def fetchone(self): ...
120
    def fetchmany(self, size=1): ...
121
    def fetchall(self): ...
122
    
123
class MySQLCursorDict:
124
    """Dictionary-based cursor returning rows as dicts"""
125
```
126

127
[SQL Operations](./sql-operations.md)
128

129
### Document Operations (X DevAPI)
130

131
Modern document database operations using MySQL's X DevAPI, supporting JSON document storage, retrieval, and manipulation with a fluent API design.
132

133
```python { .api }
134
def get_session(connection_data):
135
    """Create X Protocol session for document operations"""
136
    
137
class Collection:
138
    """Document collection operations"""
139
    def add(self, *docs): ...
140
    def find(self, condition=None): ...
141
    def modify(self, condition): ...
142
    def remove(self, condition): ...
143
```
144

145
[Document Operations](./document-operations.md)
146

147
### Error Handling and Exceptions
148

149
Comprehensive exception hierarchy following DB-API 2.0 standards, with specific error types for different failure scenarios and custom error handling capabilities.
150

151
```python { .api }
152
class Error(Exception):
153
    """Base exception class for all MySQL errors"""
154
    
155
class DatabaseError(Error):
156
    """Database-related error exceptions"""
157
    
158
class OperationalError(DatabaseError):
159
    """Database operation error exceptions"""
160
```
161

162
[Error Handling](./error-handling.md)
163

164
### Django Integration
165

166
Complete Django ORM backend providing seamless integration with Django applications, including database introspection, feature detection, and operation optimization.
167

168
```python { .api }
169
class DatabaseWrapper:
170
    """Django database backend wrapper"""
171
    
172
class DatabaseOperations:
173
    """Django-specific database operations"""
174
```
175

176
[Django Integration](./django-integration.md)
177

178
### MySQL Fabric Support
179

180
Integration with MySQL Fabric for high availability and scaling, supporting automatic failover, load balancing, and sharding configurations.
181

182
```python { .api }
183
def connect(**config):
184
    """Create Fabric-aware MySQL connection"""
185
    
186
class MySQLFabricConnection:
187
    """MySQL Fabric connection management"""
188
```
189

190
[Fabric Support](./fabric-support.md)
191

192
## Types
193

194
### DB-API 2.0 Components
195

196
```python { .api }
197
# DB-API 2.0 Module Attributes
198
apilevel: str = '2.0'
199
threadsafety: int = 1
200
paramstyle: str = 'pyformat'
201

202
# Type Constructors
203
def Date(year: int, month: int, day: int) -> datetime.date:
204
    """Construct date object from year, month, day"""
205

206
def Time(hour: int, minute: int, second: int) -> datetime.time:
207
    """Construct time object from hour, minute, second"""
208

209
def Timestamp(year: int, month: int, day: int, hour: int, minute: int, second: int) -> datetime.datetime:
210
    """Construct timestamp object from date and time components"""
211

212
def DateFromTicks(ticks: float) -> datetime.date:
213
    """Construct date object from timestamp in seconds since epoch"""
214

215
def TimeFromTicks(ticks: float) -> datetime.time:
216
    """Construct time object from timestamp in seconds since epoch"""
217

218
def TimestampFromTicks(ticks: float) -> datetime.datetime:
219
    """Construct timestamp object from timestamp in seconds since epoch"""
220

221
def Binary(data: bytes) -> bytes:
222
    """Construct binary object for binary data"""
223

224
# Type Objects for comparisons
225
STRING: _DBAPITypeObject
226
BINARY: _DBAPITypeObject  
227
NUMBER: _DBAPITypeObject
228
DATETIME: _DBAPITypeObject
229
ROWID: _DBAPITypeObject
230
```
231

232
### Connection Configuration
233

234
```python { .api }
235
ConnectionConfig = {
236
    'user': str,
237
    'password': str,
238
    'host': str,
239
    'port': int,
240
    'database': str,
241
    'charset': str,
242
    'use_pure': bool,
243
    'ssl_disabled': bool,
244
    'ssl_cert': str,
245
    'ssl_key': str,
246
    'ssl_ca': str,
247
    'pool_name': str,
248
    'pool_size': int,
249
    'pool_reset_session': bool,
250
    'autocommit': bool,
251
    'time_zone': str,
252
    'sql_mode': str,
253
    'init_command': str,
254
    'read_timeout': int,
255
    'write_timeout': int,
256
    'connect_timeout': int,
257
    'compress': bool,
258
    'auth_plugin': str,
259
    'unix_socket': str,
260
    'use_unicode': bool,
261
    'collation': str
262
}
263
```
264

265
### Constants
266

267
```python { .api }
268
class FieldType:
269
    """MySQL field type constants"""
270
    DECIMAL: int
271
    TINY: int
272
    SHORT: int
273
    LONG: int
274
    FLOAT: int
275
    DOUBLE: int
276
    NULL: int
277
    TIMESTAMP: int
278
    LONGLONG: int
279
    INT24: int
280
    DATE: int
281
    TIME: int
282
    DATETIME: int
283
    YEAR: int
284
    NEWDATE: int
285
    VARCHAR: int
286
    BIT: int
287
    JSON: int
288
    NEWDECIMAL: int
289
    ENUM: int
290
    SET: int
291
    TINY_BLOB: int
292
    MEDIUM_BLOB: int
293
    LONG_BLOB: int
294
    BLOB: int
295
    VAR_STRING: int
296
    STRING: int
297
    GEOMETRY: int
298

299
class FieldFlag:
300
    """MySQL field attribute flags"""
301
    NOT_NULL: int
302
    PRI_KEY: int
303
    UNIQUE_KEY: int
304
    MULTIPLE_KEY: int
305
    BLOB: int
306
    UNSIGNED: int
307
    ZEROFILL: int
308
    BINARY: int
309
    ENUM: int
310
    AUTO_INCREMENT: int
311
    TIMESTAMP: int
312
    SET: int
313

314
class ClientFlag:
315
    """MySQL client capability flags"""
316
    LONG_PASSWD: int
317
    FOUND_ROWS: int
318
    LONG_FLAG: int
319
    CONNECT_WITH_DB: int
320
    NO_SCHEMA: int
321
    COMPRESS: int
322
    ODBC: int
323
    LOCAL_FILES: int
324
    IGNORE_SPACE: int
325
    PROTOCOL_41: int
326
    INTERACTIVE: int
327
    SSL: int
328
    IGNORE_SIGPIPE: int
329
    TRANSACTIONS: int
330
    RESERVED: int
331
    SECURE_CONNECTION: int
332
    MULTI_STATEMENTS: int
333
    MULTI_RESULTS: int
334
    PS_MULTI_RESULTS: int
335
    PLUGIN_AUTH: int
336
    CONNECT_ARGS: int
337
    PLUGIN_AUTH_LENENC_CLIENT_DATA: int
338
    CAN_HANDLE_EXPIRED_PASSWORDS: int
339
    SESSION_TRACK: int
340
    DEPRECATE_EOF: int
341

342
class ServerFlag:
343
    """MySQL server status flags"""
344
    STATUS_IN_TRANS: int
345
    STATUS_AUTOCOMMIT: int
346
    STATUS_MORE_RESULTS_EXISTS: int
347
    STATUS_NO_GOOD_INDEX_USED: int
348
    STATUS_NO_INDEX_USED: int
349
    STATUS_CURSOR_EXISTS: int
350
    STATUS_LAST_ROW_SENT: int
351
    STATUS_DB_DROPPED: int
352
    STATUS_NO_BACKSLASH_ESCAPES: int
353
    STATUS_METADATA_CHANGED: int
354
    STATUS_QUERY_WAS_SLOW: int
355
    STATUS_PS_OUT_PARAMS: int
356

357
class RefreshOption:
358
    """MySQL FLUSH/REFRESH options"""
359
    GRANT: int
360
    LOG: int
361
    TABLES: int
362
    HOSTS: int
363
    STATUS: int
364
    THREADS: int
365
    SLAVE: int
366
    MASTER: int
367

368
class CharacterSet:
369
    """MySQL character set constants"""
370
    LATIN1: int
371
    UTF8: int
372
    UTF8MB4: int
373
    BINARY: int
374
```