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)