0
# MySQL-python
1
2
A Python interface to MySQL databases implementing the Python Database API version 2.0 specification. MySQL-python provides thread-safe database connectivity with comprehensive functionality for connecting to, querying, and managing MySQL databases from Python applications.
3
4
## Package Information
5
6
- **Package Name**: MySQL-python
7
- **Language**: Python
8
- **Installation**: `pip install MySQL-python`
9
- **Python Support**: Python 2.4-2.7 (with PyPy support)
10
- **MySQL Support**: MySQL versions 3.23 through 5.5
11
12
## Core Imports
13
14
```python
15
import MySQLdb
16
```
17
18
For type constants and field types:
19
20
```python
21
from MySQLdb import FIELD_TYPE
22
from MySQLdb.constants import CLIENT, CR, ER, FLAG, REFRESH
23
```
24
25
For specific functionality:
26
27
```python
28
from MySQLdb import cursors, converters, times
29
```
30
31
## Basic Usage
32
33
```python
34
import MySQLdb
35
36
# Connect to database
37
db = MySQLdb.connect(
38
host="localhost",
39
user="username",
40
passwd="password",
41
db="database_name"
42
)
43
44
# Create cursor and execute query
45
cursor = db.cursor()
46
cursor.execute("SELECT * FROM users WHERE id = %s", (1,))
47
48
# Fetch results
49
result = cursor.fetchone()
50
print(result)
51
52
# Commit changes and close
53
db.commit()
54
cursor.close()
55
db.close()
56
```
57
58
Using context managers:
59
60
```python
61
import MySQLdb
62
63
# Connection automatically closed on exit
64
with MySQLdb.connect(host="localhost", user="user", passwd="pass", db="test") as db:
65
with db.cursor() as cursor:
66
cursor.execute("SELECT COUNT(*) FROM users")
67
count = cursor.fetchone()[0]
68
print(f"Total users: {count}")
69
```
70
71
## Architecture
72
73
MySQL-python is built on a layered architecture:
74
75
- **High-level MySQLdb module**: Python DB API 2.0 compliant interface with connection and cursor objects
76
- **Low-level _mysql module**: C extension providing direct access to MySQL C API for performance
77
- **Type conversion system**: Automatic conversion between Python and MySQL data types
78
- **Constants modules**: MySQL protocol constants, error codes, and field type definitions
79
- **Exception hierarchy**: Comprehensive error handling following DB API 2.0 specification
80
81
The design provides both ease of use through the high-level interface and performance through the underlying C extension, making it suitable for both simple scripts and high-performance applications.
82
83
## Capabilities
84
85
### Database Connections
86
87
Core functionality for establishing and managing database connections, including connection configuration, transaction control, and connection lifecycle management.
88
89
```python { .api }
90
def connect(host=None, user=None, passwd=None, db=None, port=3306, **kwargs):
91
"""Create database connection."""
92
93
class Connection:
94
def autocommit(self, on): ...
95
def begin(self): ...
96
def commit(self): ...
97
def rollback(self): ...
98
def cursor(self, cursorclass=None): ...
99
def close(self): ...
100
```
101
102
[Database Connections](./connections.md)
103
104
### Cursor Operations
105
106
Comprehensive cursor functionality for executing queries and fetching results, including multiple cursor types for different use cases (tuple/dictionary rows, stored/streaming results).
107
108
```python { .api }
109
class Cursor:
110
def execute(self, query, args=None): ...
111
def executemany(self, query, args): ...
112
def fetchone(self): ...
113
def fetchmany(self, size=None): ...
114
def fetchall(self): ...
115
116
class DictCursor: ...
117
class SSCursor: ...
118
class SSDictCursor: ...
119
```
120
121
[Cursor Operations](./cursors.md)
122
123
### Data Type Conversion
124
125
Automatic conversion between Python and MySQL data types, including date/time handling, binary data, and custom type converters.
126
127
```python { .api }
128
def Binary(x): ...
129
def DateFromTicks(ticks): ...
130
def TimeFromTicks(ticks): ...
131
def TimestampFromTicks(ticks): ...
132
133
# Type sets for DB API 2.0 compliance
134
STRING: DBAPISet
135
BINARY: DBAPISet
136
NUMBER: DBAPISet
137
DATE: DBAPISet
138
TIME: DBAPISet
139
TIMESTAMP: DBAPISet
140
```
141
142
[Data Type Conversion](./types.md)
143
144
### String Escaping and Utilities
145
146
Essential string escaping functions for SQL injection prevention and utility functions for client information and debugging.
147
148
```python { .api }
149
def escape(obj, mapping): ...
150
def escape_string(s): ...
151
def escape_dict(d, mapping): ...
152
def escape_sequence(seq, mapping): ...
153
def string_literal(obj): ...
154
def get_client_info(): ...
155
def debug(debug_string): ...
156
157
# Module attributes
158
NULL: object
159
version_info: tuple
160
__version__: str
161
__author__: str
162
```
163
164
[String Escaping and Utilities](./escaping.md)
165
166
### Constants and Error Handling
167
168
MySQL protocol constants, error codes, field types, and comprehensive exception hierarchy for robust error handling.
169
170
```python { .api }
171
# Constants modules
172
CLIENT: module # Connection flags
173
CR: module # Client error codes
174
ER: module # MySQL error codes
175
FIELD_TYPE: module # Column type constants
176
FLAG: module # Column property flags
177
REFRESH: module # Refresh operation flags
178
179
# Exception hierarchy
180
class MySQLError(Exception): ...
181
class Error(MySQLError): ...
182
class DatabaseError(Error): ...
183
class OperationalError(DatabaseError): ...
184
```
185
186
[Constants and Error Handling](./constants-errors.md)
187
188
### Low-Level Operations
189
190
Direct access to MySQL C API functionality for advanced use cases requiring fine-grained control over database operations and performance optimization.
191
192
```python { .api }
193
import _mysql
194
195
def connect(**kwargs): ...
196
def escape_string(s): ...
197
def get_client_info(): ...
198
def thread_safe(): ...
199
200
# Connection object methods from C extension
201
connection.affected_rows()
202
connection.insert_id()
203
connection.ping()
204
```
205
206
[Low-Level Operations](./low-level.md)