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 or pathlib.Path.
  • persist – If True quma immediately opens a connection and keeps it open throughout the complete application runtime. Setting it to True will raise an error if you try to initialize a connection pool. Defaults to False.
  • 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 to False.
  • contextcommit – If True and a context manager is used quma will automatically commit all changes when the context manager exits. Defaults to False.
  • 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 to False. 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 to False.

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