Connection pool

The pool module contains a number of Database classes thatprovide connection pooling for PostgreSQL, MySQL and SQLite databases. The poolworks by overriding the methods on the Database class that open andclose connections to the backend. The pool can specify a timeout after whichconnections are recycled, as well as an upper bound on the number of openconnections.

In a multi-threaded application, up to max_connections will be opened. Eachthread (or, if using gevent, greenlet) will have it’s own connection.

In a single-threaded application, only one connection will be created. It willbe continually recycled until either it exceeds the stale timeout or is closedexplicitly (using .manual_close()).

By default, all your application needs to do is ensure that connections areclosed when you are finished with them, and they will be returned to thepool. For web applications, this typically means that at the beginning of arequest, you will open a connection, and when you return a response, you willclose the connection.

Simple Postgres pool example code:

# Use the special postgresql extensions.
from playhouse.pool import PooledPostgresqlExtDatabase
 
db = PooledPostgresqlExtDatabase(
    'my_app',
    max_connections=32,
    stale_timeout=300,  # 5 minutes.
    user='postgres')
 
class BaseModel(Model):
    class Meta:
        database = db

That’s it! If you would like finer-grained control over the pool ofconnections, check out the advanced_connection_management section.

Pool APIs

• class PooledDatabase(database[, max_connections=20[, stale_timeout=None[, timeout=None[, **kwargs]]]])

Parameters:

• database (str) – The name of the database or database file.
• max_connections (int) – Maximum number of connections. Provide None for unlimited.
• stale_timeout (int) – Number of seconds to allow connections to be used.
• timeout (int) – Number of seconds to block when pool is full. By default peewee does not block when the pool is full but simply throws an exception. To block indefinitely set this value to 0.
• kwargs – Arbitrary keyword arguments passed to database class.

Mixin class intended to be used with a subclass of Database.

Note

Connections will not be closed exactly when they exceed their stale_timeout. Instead, stale connections are only closed when a new connection is requested.

Note

If the number of open connections exceeds max_connections, a ValueError will be raised.

• manual_close()

• Close the currently-open connection without returning it to the pool.

• close_idle()

• Close all idle connections. This does not include any connections thatare currently in-use – only those that were previously created buthave since been returned back to the pool.

• closestale([_age=600])

Parameters:age (int) – Age at which a connection should be considered stale.Returns:Number of connections closed.

Close connections which are in-use but exceed the given age. Usecaution when calling this method!

• close_all()
• Close all connections. This includes any connections that may be in useat the time. Use caution when calling this method!

• class PooledPostgresqlDatabase
• Subclass of PostgresqlDatabase that mixes in the PooledDatabase helper.

• class PooledPostgresqlExtDatabase
• Subclass of PostgresqlExtDatabase that mixes in the PooledDatabase helper. The PostgresqlExtDatabase is a part of thePostgresql Extensions module and provides support for many Postgres-specificfeatures.

• class PooledMySQLDatabase
• Subclass of MySQLDatabase that mixes in the PooledDatabase helper.

• class PooledSqliteDatabase
• Persistent connections for SQLite apps.

• class PooledSqliteExtDatabase
• Persistent connections for SQLite apps, using the SQLite Extensions advanced database driver SqliteExtDatabase.