0
# String Escaping and Utilities
1
2
Critical string escaping functions for SQL injection prevention, utility functions for client information, and debugging support. These functions provide secure ways to handle user input and interact with MySQL.
3
4
## Capabilities
5
6
### String Escaping Functions
7
8
Functions for safely escaping strings and data structures to prevent SQL injection attacks.
9
10
```python { .api }
11
def escape(obj, mapping):
12
"""
13
Escape object using provided mapping dictionary.
14
15
Parameters:
16
- obj: Object to escape (string, number, sequence, etc.)
17
- mapping: Dictionary mapping Python types to escape functions
18
19
Returns:
20
str: Escaped string representation suitable for SQL
21
"""
22
23
def escape_string(s):
24
"""
25
Escape SQL-interpreted characters in string s.
26
27
DEPRECATED: Use connection.escape_string() instead.
28
This function cannot handle character sets properly.
29
30
Parameters:
31
- s (str): String to escape
32
33
Returns:
34
str: Escaped string with SQL special characters escaped
35
"""
36
37
def escape_dict(d, mapping):
38
"""
39
Escape all values in a dictionary using the provided mapping.
40
41
Parameters:
42
- d (dict): Dictionary with values to escape
43
- mapping: Dictionary mapping Python types to escape functions
44
45
Returns:
46
dict: New dictionary with all values escaped
47
"""
48
49
def escape_sequence(seq, mapping):
50
"""
51
Escape all items in a sequence using the provided mapping.
52
53
Parameters:
54
- seq: Sequence (list, tuple) to escape
55
- mapping: Dictionary mapping Python types to escape functions
56
57
Returns:
58
list: List of escaped string representations
59
"""
60
61
def string_literal(obj):
62
"""
63
Convert object to SQL string literal with single quotes.
64
65
DEPRECATED: Use connection.string_literal() instead.
66
This function cannot handle character sets properly.
67
68
Equivalent to: "'%s'" % escape_string(str(obj))
69
70
Parameters:
71
- obj: Object to convert to SQL literal
72
73
Returns:
74
str: Object as quoted SQL string literal
75
"""
76
```
77
78
#### Usage Examples
79
80
```python
81
import MySQLdb
82
83
# Basic escaping (deprecated - use connection methods instead)
84
unsafe_string = "Robert'; DROP TABLE students; --"
85
safe_string = MySQLdb.escape_string(unsafe_string)
86
print(safe_string) # "Robert\\'; DROP TABLE students; --"
87
88
# Preferred: Use connection-aware escaping
89
db = MySQLdb.connect(host="localhost", user="user", passwd="pass", db="test")
90
safe_string = db.escape_string(unsafe_string)
91
92
# Escape dictionary values
93
from MySQLdb.converters import conversions
94
data = {"name": "O'Reilly", "age": 25}
95
escaped_data = MySQLdb.escape_dict(data, conversions)
96
97
# Escape sequence values
98
values = ["O'Reilly", 25, None]
99
escaped_values = MySQLdb.escape_sequence(values, conversions)
100
```
101
102
### Client Information
103
104
Functions for retrieving MySQL client library information.
105
106
```python { .api }
107
def get_client_info():
108
"""
109
Get MySQL client library version string.
110
111
Returns:
112
str: Version string of the MySQL client library
113
"""
114
```
115
116
#### Usage Examples
117
118
```python
119
import MySQLdb
120
121
# Get client library version
122
client_version = MySQLdb.get_client_info()
123
print(f"MySQL client version: {client_version}")
124
# Output: "MySQL client version: 5.1.73"
125
126
# Useful for compatibility checking
127
major_version = int(client_version.split('.')[0])
128
if major_version >= 5:
129
print("Modern MySQL client library")
130
```
131
132
### Debug Support
133
134
Functions for debugging MySQL operations using the Fred Fish debug library.
135
136
```python { .api }
137
def debug(debug_string):
138
"""
139
Perform DBUG_PUSH with the given debug string.
140
141
Uses the Fred Fish debug library. Client library must be
142
compiled with debugging support to use this function.
143
144
Parameters:
145
- debug_string (str): Debug control string
146
"""
147
```
148
149
#### Usage Examples
150
151
```python
152
import MySQLdb
153
154
# Enable debug tracing (requires debug-enabled client library)
155
MySQLdb.debug("d:t:o,/tmp/client.trace")
156
157
# Disable debugging
158
MySQLdb.debug("")
159
```
160
161
### Module Attributes
162
163
Important module-level constants and version information.
164
165
```python { .api }
166
NULL: object
167
"""Special NULL constant for representing SQL NULL values"""
168
169
version_info: tuple
170
"""Version information as tuple (major, minor, patch, release_type, serial)"""
171
172
__version__: str
173
"""Version string in format "major.minor.patch" """
174
175
__author__: str
176
"""Package author information"""
177
```
178
179
#### Usage Examples
180
181
```python
182
import MySQLdb
183
184
# Check version compatibility
185
if MySQLdb.version_info >= (1, 2, 5):
186
print("Compatible version")
187
188
# Use NULL constant
189
cursor.execute("INSERT INTO table (col1, col2) VALUES (%s, %s)",
190
("value", MySQLdb.NULL))
191
192
# Display version information
193
print(f"MySQLdb version: {MySQLdb.__version__}")
194
print(f"Version info: {MySQLdb.version_info}")
195
print(f"Author: {MySQLdb.__author__}")
196
```
197
198
## Security Considerations
199
200
**Important:** The module-level escaping functions (`escape_string`, `string_literal`) are deprecated because they cannot handle character sets properly. Always use the connection-aware methods instead:
201
202
```python
203
# DEPRECATED - Don't use
204
MySQLdb.escape_string(user_input)
205
206
# PREFERRED - Use connection methods
207
db = MySQLdb.connect(...)
208
db.escape_string(user_input) # Character set aware
209
db.escape(user_input, conversions) # Full type conversion
210
```
211
212
The connection methods understand the current character set encoding and provide proper escaping for the specific MySQL connection configuration.