Muffin Peewee AIO

muffin-peewee-aio — Asynchronous Peewee ORM integration for the Muffin framework.

Requirements

Python >= 3.11

Installation

Install via pip:

$ pip install muffin-peewee-aio

You can include an async database driver as needed:

$ pip install muffin-peewee-aio[aiosqlite]
$ pip install muffin-peewee-aio[aiopg]
$ pip install muffin-peewee-aio[asyncpg]
$ pip install muffin-peewee-aio[aiomysql]

Usage

from muffin import Application
from muffin_peewee import Plugin as Peewee

# Create the application
app = Application("example")

# Initialize the plugin
db = Peewee()
db.setup(app, PEEWEE_CONNECTION="postgresql://postgres:postgres@localhost:5432/database")

# Or: db = Peewee(app, **options)

Configuration

You can provide options either at initialization or through the application config.

Name	Default	Description
CONNECTION	`sqlite:///db.sqlite`	Database connection URL
CONNECTION_PARAMS	`{}`	Extra options passed to the database backend
REPLICAS	`None`	List of read-replica connection URLs
AUTO_CONNECTION	`True`	Automatically acquire a DB connection per request
AUTO_TRANSACTION	`True`	Automatically wrap each request in a transaction
MIGRATIONS_ENABLED	`True`	Enable the migration engine
MIGRATIONS_PATH	`"migrations"`	Path to store migration files
PYTEST_SETUP_DB	`True`	Manage DB setup and teardown in pytest

You can also define options in the Application config using the PEEWEE_ prefix:

PEEWEE_CONNECTION = "postgresql://..."

Note: Muffin application config is case-insensitive.

Models and Queries

Define your model:

class Test(db.Model):
    data = peewee.CharField()

Query the database:

@app.route("/")
async def view(request):
    return [t.data async for t in Test.select()]

Connection Management

By default, connections and transactions are managed automatically. To manage them manually, disable the config flags and use context managers:

@app.route("/")
async def view(request):
    async with db.connection():
        async with db.transaction():
            # Perform DB operations here
            ...

Read Replicas

You can configure read replicas via the REPLICAS option:

db.setup(
    app,
    PEEWEE_CONNECTION="postgresql://...",
    PEEWEE_REPLICAS=[
        "postgresql://replica1/...",
        "postgresql://replica2/...",
    ],
)

Use db.replica() to open a read-only connection to a replica backend:

@app.route("/")
async def view(request):
    async with db.replica():
        return [t.data async for t in Test.select()]

Migrations

Create a migration:

$ muffin example:app peewee-create [NAME] [--auto]

Run migrations:

$ muffin example:app peewee-migrate [NAME] [--fake]

Rollback the latest migration:

$ muffin example:app peewee-rollback

List all migrations:

$ muffin example:app peewee-list

Clear migration history from the database:

$ muffin example:app peewee-clear

Merge all migrations into one:

$ muffin example:app peewee-merge

Testing Support

You can use the conftest() context manager to auto-manage schema setup and teardown during testing:

import pytest

@pytest.mark.asyncio
async def test_example():
    async with db.conftest():
        # Tables are created and dropped automatically
        ...

Bug Tracker

Found a bug or have a suggestion? Please open an issue at: https://github.com/klen/muffin-peewee-aio/issues

Contributing

Development takes place at: https://github.com/klen/muffin-peewee-aio Pull requests are welcome!

Contributors

klen (Kirill Klenov)

License

This project is licensed under the MIT license.

Metadata

Release files for muffin-peewee-aio 3.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for muffin-peewee-aio 3.0.0
File	Size	Uploaded
muffin_peewee_aio-3.0.0.tar.gz	7.1 kB	Jun 26, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for muffin-peewee-aio 3.0.0
File	Interpreter	ABI	Platform	Reset
muffin_peewee_aio-3.0.0-py3-none-any.whl 8.3 kB Jun 26, 2026	Python 3	none	any	Details

Total release size: 15.4 kB

Release files / muffin_peewee_aio-3.0.0.tar.gz

Download URL	muffin_peewee_aio-3.0.0.tar.gz
Size	7.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`4b1ce8d4f7af1f41a0373e6dd42ac22f58320906dda539d0f2daf1c7ae76ce44`
BLAKE2b-256 checksum How to use checksums	`c2018c48c3727c35ca756713a5148649c828730b296af7196aa20ce9e92a4605`
Upload date	Jun 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / muffin_peewee_aio-3.0.0-py3-none-any.whl

Download URL	muffin_peewee_aio-3.0.0-py3-none-any.whl
Size	8.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b1c28126fe4d0301e169c38d498731b7b9de400f9bfc7d3453aa83f9c2df1770`
BLAKE2b-256 checksum How to use checksums	`c59a261de632e6c421e77641bfe1eaaf7d783e95b7330391dbdeee0006f2bf77`
Upload date	Jun 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`