Connections and transactions

In order to start using a database in weppy, you have to initialize an instance of the Database class:

from weppy.orm import Database

db = Database(app)

As you will learn in the next chapters, this Database instance will be fundamental to perform operations on your database, as it will be the access point to the data you store.


As we seen in the first example, the Database instance gives you a pipe to be registered into your application pipeline:

app.pipeline = [db.pipe]

This pipe will ensure the connection to the database during the request flow and the disconnection when the response is ready. As a consequence, you don't need to bother about connecting/disconnecting in your application flow, unless you're explicit working without a request context.
Even in that case, you won't have troubles in connecting to the database, since the Database instance will automatically open up a connection after initialization. This means that, even if you import your Database instance from the console, you will have the connection opened with your database.

If somehow you need to manually open and close the connection with your database, you can use the adapter methods:

# manually open a connection
# manually close the active connection


As you've seen from the example above, Database class needs your application object as the first parameter, and reads the configuration from its config object.

The minimal configuration needed is the database address to connect to, and you can pass it directly as uri, for example:

# with a local sqlite database:
app.config.db.uri = 'sqlite://filename.sqlite'
# with a remote postgre database with auth access:
app.config.db.uri = 'postgres://username:yourpassword@localhost/database'

Or you can set all the connection details in the config object:

app.config.db.adapter = 'postgres' = 'localhost'
app.config.db.user = 'username'
app.config.db.password = 'yourpassword'
app.config.db.database = 'database'

This becomes useful when you're using yaml config files and/or environment dependencies, as you can write down your db.yml file in a config folder:

adapter: postgres
host: localhost
user: username
password: yourpassword
database: databasename

and then do:

app.config_from_yaml('db.yml', 'db')

where the first parameter is the filename and the second is the attribute to be set in the application config.

Passing explicit config to Database

Database class also accepts a specific config object that become particularly handy in situations where you have multiple databases in your application:

app.config.db.uri = "postgres://localhost/mydb"
app.config.db2.uri = "mongodb://localhost/mydb"

db = Database(app)
db2 = Database(app, app.config.db2)

Additional configuration parameters

Database class accepts several configuration parameters, here we list them in detail:

parameter default description
pool_size 0 the pool size to use when connecting to the database
auto_connect None automatically connects to the DBMS on init
auto_migrate False turns on or off the automatic migration
folder databases the folder relative to your application path where to store the database (when using sqlite) and/or support data
adapter_args {} specific options for the pyDAL adapter
driver_args {} specific options for the driver

Note that when you don't specify any pool_size value, weppy won't use any pool when connecting to the database, but just one connection.

Also, when the auto_migrate option is set to False, weppy won't migrate your data when you will made changes to your models, and requires you to generate migrations with the appropriate command or write down your own migrations. Please checkout the appropriate section of the documentation for additional details.


As we seen above, the pipe of your Database instance will ensure the connection to the database during the request flow; but it's also responsible of the transactions during this flow.
In fact, the pipe treats the request as a single database transaction, ensuring the commit of the changes if the request had success. Otherwise, in the case of un-catched exceptions (resulting in a 500 HTTP error response), the pipe will perform a rollback on the database data.

Since the pipe is used only in a request context, every time you work without it you should commit or rollback your changes (also when you're working in the console), using the available methods of the Database instance:

# commit all the changes
# discard all the changes

You can obviously use them also in the application code during the request in order to have a better control of what happens with your data. Just remember that when you call commit() or rollback() you're in fact ending the last transaction and starting a new one.