Connection Management

To open a connection to a database, use the Database.connect() method:

>>> db = SqliteDatabase(':memory:')  # In-memory SQLite database.
>>> db.connect()
True

If we try to call connect() on an already-open database, we get aOperationalError:

>>> db.connect()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/charles/pypath/peewee.py", line 2390, in connect
    raise OperationalError('Connection already opened.')
peewee.OperationalError: Connection already opened.

To prevent this exception from being raised, we can call connect() with anadditional argument, reuse_if_open:

>>> db.close()  # Close connection.
True
>>> db.connect()
True
>>> db.connect(reuse_if_open=True)
False

Note that the call to connect() returns False if the databaseconnection was already open.

To close a connection, use the Database.close() method:

>>> db.close()
True

Calling close() on an already-closed connection will not result in anexception, but will return False:

>>> db.connect()  # Open connection.
True
>>> db.close()  # Close connection.
True
>>> db.close()  # Connection already closed, returns False.
False

You can test whether the database is closed using theDatabase.is_closed() method:

>>> db.is_closed()
True

Using autoconnect

It is not necessary to explicitly connect to the database before usingit if the database is initialized with autoconnect=True (the default).Managing connections explicitly is considered a best practice, thereforeyou may consider disabling the autoconnect behavior.

It is very helpful to be explicit about your connection lifetimes. If theconnection fails, for instance, the exception will be caught when theconnection is being opened, rather than some arbitrary time later when a queryis executed. Furthermore, if using a connection pool, it isnecessary to call connect() and close()to ensure connections are recycled properly.

For the best guarantee of correctness, disable autoconnect:

db = PostgresqlDatabase('my_app', user='postgres', autoconnect=False)

Thread Safety

Peewee keeps track of the connection state using thread-local storage, makingthe Peewee Database object safe to use with multiple threads. Eachthread will have it’s own connection, and as a result any given thread willonly have a single connection open at a given time.

Context managers

The database object itself can be used as a context-manager, which opens aconnection for the duration of the wrapped block of code. Additionally, atransaction is opened at the start of the wrapped block and committed beforethe connection is closed (unless an error occurs, in which case the transactionis rolled back).

>>> db.is_closed()
True
>>> with db:
...     print(db.is_closed())  # db is open inside context manager.
...
False
>>> db.is_closed()  # db is closed.
True

If you want to manage transactions separately, you can use theDatabase.connection_context() context manager.

>>> with db.connection_context():
...     # db connection is open.
...     pass
...
>>> db.is_closed()  # db connection is closed.
True

The connection_context() method can also be used as a decorator:

@db.connection_context()def prepare_database():
# DB connection will be managed by the decorator, which opens
# a connection, calls function, and closes upon returning.
db.create_tables(MODELS)  # Create schema.
load_fixture_data(db)

DB-API Connection Object

To obtain a reference to the underlying DB-API 2.0 connection, use theDatabase.connection() method. This method will return thecurrently-open connection object, if one exists, otherwise it will open a newconnection.

>>> db.connection()
<sqlite3.Connection object at 0x7f94e9362f10>