You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A wrapper for the MySQL Python connector that provides additional resilience and functionality.
4
4
5
-
## What is this repository for? ##
5
+
**Latest version: 1.3.1**
6
+
7
+
## About this repository
6
8
7
9
* A wrapper for the MySQL Python connector that provides additional resilience and functionality.
8
10
* Implements connection pooling that's more reliable.
9
-
* Version 1.2.1
10
-
* Works with Python 2.7+ or 3.5+
11
+
* Developed and tested with Python 3.9, should work with 3.5+
11
12
12
-
## How do I get set up? ##
13
+
## How do I get set up?
13
14
14
15
* Make sure you have Git installed - [Download Git](https://git-scm.com/downloads)
15
16
* Run `pip install git+https://github.com/SheffieldSolar/MySQL-DBConnector/`
16
17
17
-
## Getting started ##
18
-
I recommend using a MySQL options file to pass the connection parameters rather than hard-coding the DB credentials:
18
+
## Usage
19
+
Start by creating an instance of the `DBConnector` class, ideally using a context manager as this will ensure all connections are closed if an error is encountered or the code is interrupted:
20
+
21
+
```Python
22
+
from dbconnector import DBConnector
23
+
```
24
+
25
+
The `DBConnector` class requires at least one argument: `connector_args`. This should be a dictionary of connection arguments, the full list of which can be found [here](https://dev.mysql.com/doc/connector-python/en/connector-python-connectargs.html). Most of these are optional, but you'll need to specify at least:
26
+
27
+
```Python
28
+
connector_args = {
29
+
"user": "<your-username>",
30
+
"password": "<your-password>",
31
+
"database": "<your-database>",
32
+
}
33
+
```
34
+
35
+
Some of the connector args have default values which override the defaults in the mysql-connector-python library, they are:
36
+
37
+
-`time_zone`: "UTC"
38
+
-`connection_timeout`: 60
39
+
-`buffered`: True
40
+
-`get_warnings`: True
41
+
-`raise_on_warnings`: False
42
+
-`use_pure`: True
43
+
44
+
You can override these yourself if you prefer.
45
+
46
+
Loading your password into your Python code is usually insecure, so I recommend using a MySQL options file to pass the connection parameters rather than hard-coding the DB credentials:
19
47
```Python
20
48
from dbconnector import DBConnector
21
49
22
50
mysql_options_file ="mysql_options.txt"
23
51
24
-
# Use the context manager to ensure DB connections are always safely closed
25
-
# Always specify the session_tz to avoid issues with MySQL's timezone-naive datetimes or unwanted TZ conversions of timestamp fields!
26
-
with DBConnector(mysql_options_file, session_tz="UTC") as dbc:
52
+
#HINT: Use the context manager to ensure DB connections are always safely closed
53
+
54
+
with DBConnector(connector_args={"option_files": mysql_options_file}) as dbc:
27
55
# Selecting from the database (returns a list of tuples):
28
56
# See https://dev.mysql.com/doc/connector-python/en/connector-python-api-mysqlcursor-fetchall.html
57
+
# Note that using `select * from` is not recommended since the returned columns or their order
58
+
# might change.
29
59
data = dbc.query("SELECT * FROM test;")
30
60
61
+
# Select from the database and convert to a Pandas DataFrame:
62
+
data = dbc.query("SELECT col2, col2 FROM test;", df=True)
63
+
31
64
# Inserting one row into the database:
32
65
dbc.iud_query("insert into test (col1, col2, col3) values ('val1', 'val2', 'val3');")
33
66
@@ -39,7 +72,9 @@ with DBConnector(mysql_options_file, session_tz="UTC") as dbc:
39
72
args = (1, 2, 3)
40
73
result = dbc.proc("myProcedure", args)
41
74
```
75
+
42
76
The file _'mysql_options.txt'_ should look something like this:
77
+
43
78
```
44
79
[client]
45
80
host = <your-server-hostname>
@@ -49,32 +84,50 @@ database = <your-database>
49
84
```
50
85
51
86
It is also possible to pass connection parameters directly to the DBConnector class. This is not recommended but can be useful for testing/debugging:
with DBConnector(db_config=db_config, session_tz="UTC") as dbc:
91
+
# HINT: Always specify the time_zone arg to avoid issues with MySQL's timezone-naive datetimes or
92
+
# unwanted TZ conversions of timestamp fields!
93
+
connector_args = {
94
+
"host": "<your-server-hostname>",
95
+
"user": "<your-username>",
96
+
"password": "<your-password>",
97
+
"database": "<your-database>",
98
+
"time_zone": "UTC"
99
+
}
100
+
101
+
with DBConnector(connector_args=connector_args) as dbc:
59
102
# Do some DB stuff
60
103
```
61
104
62
-
## Documentation ##
105
+
The `dbconnector` module uses the Python `logging` module to log useful debugging messages, warnings and errors. You can set your preferred logging level using something like:
0 commit comments