Connecting¶
You connect to a server/database by creating an instance of the class
quma.Database
. You have to at least provide a valid
database URL and the path to your sql scripts. See below for the
details.
Connection Examples¶
sqldirs = '/path/to/sql/scripts'
# can also be a list of paths:
sqldirs = [
'/path/to/sql/scripts',
'/another/path/to/sql/scripts',
]
# SQLite
db = Database('sqlite:////path/to/db.sqlite', sqldirs)
# SQLite in memory db
db = Database('sqlite:///:memory:', sqldirs)
# PostgreSQL localhost
db = Database('postgresql://username:password@/db_name', sqldirs)
# PostgreSQL network server
db = Database('postgresql://username:password@10.0.0.1:5432/db_name', sqldirs)
# MySQL/MariaDB localhost
db = Database('mysql://username:password@/db_name', sqldirs)
# MySQL/MariaDB network server
db = Database('mysql://username:password@192.168.1.1:5432/db_name', sqldirs)
# You can pass driver specific parameters e. g. MySQL's charset
db = Database('mysql://username:password@192.168.1.1:5432/db_name',
sqldirs,
charset='utf8')
The Database class¶
-
class
quma.database.
Database
(dburi, *args, **kwargs)¶ The database object acts as the central object of the library.
Parameters: - dburi – The connection string. See section “Connection Examples”
- sqldirs – One or more filesystem paths pointing to the sql scripts.
str
orpathlib.Path
. - persist – If
True
quma immediately opens a connection and keeps it open throughout the complete application runtime. Setting it toTrue
will raise an error if you try to initialize a connection pool. Defaults toFalse
. - pessimistic – If
True
quma emits a test statement on a persistent SQL connection every time it is accessed or at the start of each connection pool checkout (see section “Connection Pool”), to test that the database connection is still viable. Defaults toFalse
. - contextcommit – If
True
and a context manager is used quma will automatically commit all changes when the context manager exits. Defaults toFalse
. - prepare_params – A callback function which will be called before every query to prepare the params which will be passed to the query. Defaults to None.
- file_ext – The file extension of sql files. Defaults to ‘
sql'
. - tmpl_ext – The file extension of template files (see
Templates). Defaults to
'msql'
. - echo – Print the executed query to stdout if
True
. Defaults toFalse
. PostgreSQL and MySQL/MariaDB connections will print the query after argument binding. This means placeholders will be substituted with the parameter values. SQLite will always print the query without substitutions. - cache – cache the scripts in memory if
True
, otherwise re-read each script when the query is executed. Defaults toFalse
.
Additional connection pool parameters (see Connection pool):
Parameters: - size – The size of the pool to be maintained. This is the largest number of connections that will be kept persistently in the pool. The pool begins with no connections. Defaults to 5.
- overflow – The maximum overflow size of the pool. When the number of checked-out connections reaches the size set in size, additional connections will be returned up to this limit. Set to -1 to indicate no overflow limit. Defaults to 10.
- timeout – The number of seconds to wait before giving up on returning a connection. Defaults to None.
-
exception
DoesNotExistError
¶
-
exception
MultipleRowsError
¶
-
close
()¶ Close (all) open connections. If you want to reconnect you need to create a new
quma.Database
instance.
-
cursor
¶ Open a connection and return a cursor.
-
execute
(query, **kwargs)¶ Execute the statements in
query
and commit immediately.Parameters: query – The sql query to execute.
-
release
(carrier)¶ If the
carrier
holds a connection close it or return it to the pool.Parameters: carrier – An object holding a quma connection. See Reusing connections