Getting started¶
Installation¶
$ pip install jardin
or
$ echo 'jardin' >> requirements.txt
$ pip install -r requirements.txt
Setup¶
In your working directory (the root of your app), create a file named jardin_conf.py
:
# jardin_conf.py
DATABASES = {
'my_master_database': 'https://username:password@master_database.url:port',
'my_replica_database': 'https://username:password@replica_database.url:port'
}
LOG_LEVEL = logging.DEBUG
WATERMARK = 'My Great App'
You can also place this file anywhere you want and point to it with the environment variable JARDIN_CONF
.
If you’d like to balance the load among a few databases - especially among replica databases - you may give multiple database URLs, separated by whitespace:
# jardin_conf.py
DATABASES = {
'my_replicas': 'https://user:pass@replica1.url:port https://user:pass@replica2.url:port'
}
# On first access, jardin randomly picks an URL from the list and maintains connection
# "stickiness" during the lifetime of the process. In a long-running process,
# application may ask jardin to switch to other connections on the list by
# calling 'jardin.reset_session()'.
Then, in your app, say you have a table called users
:
# app.py
import jardin
class User(jardin.Model):
db_names = {'master': 'my_master_database', 'replica': 'my_replica_database'}
In the console:
>>> from app import User
>>> users = User.last(4)
# /* My Great App */ SELECT * FROM users ORDER BY u.created_at DESC LIMIT 4;
>>> users
id name email ...
0 John john@beatl.es ...
1 Paul paul@beatl.es ...
2 George george@beatl.es ...
3 Ringo ringo@beatl.es ...
The resulting object is a pandas dataframe:
>>> import pandas
>>> isinstance(users, pandas.DataFrame)
True
>>> isinstance(users, jardin.Collection)
True