WAIT — Solo project — review before adopting

• Last commit today
• MIT licensed
• CI configured
• Tests present
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ Scorecard: default branch unprotected (0/10)

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against OpenSSF Scorecard}

Peewee is a lightweight, single-file Python ORM that provides an expressive query builder for SQLite, MySQL, MariaDB, and PostgreSQL with built-in asyncio support via async drivers (aiosqlite, asyncpg, aiomysql). It prioritizes simplicity and SQL expressiveness over heavyweight abstractions, allowing developers to write intuitive database queries without the complexity of SQLAlchemy while maintaining full SQL power. Monolithic single-module architecture: peewee.py is the core engine (not visible in file list but implied by 'single module' claim). The docs/ directory contains Sphinx documentation organized by feature (models.rst, querying.rst, relationships.rst, asyncio.rst, database.rst). The playhouse/ directory (implied) contains optional extensions. Tests are likely in tests/ (not shown in file list).

Python developers building small to medium-scale applications who want a minimal ORM without dependencies (peewee is a single module), particularly those working with Flask, FastAPI, or Pydantic integrations, and teams that value readable SQL over convention-heavy frameworks.

Production-ready and actively maintained since 2010. The repo shows comprehensive CI/CD setup (.github/workflows/tests.yaml, .github/workflows/wheels.yaml), extensive documentation in docs/peewee/, and support for modern async patterns. Recent wheel builds and test infrastructure indicate active maintenance, though commit recency data isn't visible here.

Single-maintainer project (coleifer) carries continuity risk, but this has been stable since 2010 with no required external dependencies. The codebase is relatively small (~2MB Python code) making it auditable. Main risk is lag time on new database driver versions or Python versions if the maintainer becomes unavailable; mitigation is the minimal dependency footprint.

Based on file structure, active areas include: asyncio support (docs/peewee/asyncio.rst exists), framework integration improvements (docs/peewee/framework_integration.rst for Flask/FastAPI), and database tool utilities (docs/peewee/db_tools.rst). The wheel building workflow (.github/workflows/wheels.yaml) suggests ongoing multi-platform distribution. Specific recent commits not visible in provided data.

Clone and install: git clone https://github.com/coleifer/peewee.git && cd peewee && pip install -e . or for database backends: pip install peewee[postgres] or pip install peewee[mysql] or pip install peewee[asyncpg]. For async: pip install peewee[aiosqlite] (see README for all variants).

Daily commands: No traditional 'server' — peewee is a library imported into applications. To test the codebase locally: python -m pytest tests/ (inferred) or python bench.py for benchmarks. To use in an app: from peewee import *; db = SqliteDatabase('app.db') then define Model subclasses.

• peewee.py — Monolithic core ORM module containing all database abstractions, query builders, models, and field definitions—the entire framework lives here.
• playhouse/postgres_ext.py — PostgreSQL-specific extensions and field types (JSONB, ARRAY, HStoreField) that extend the base ORM for advanced database features.
• playhouse/mysql_ext.py — MySQL/MariaDB-specific extensions including JSON, hybrid expressions, and dialect-specific optimizations.
• playhouse/shortcuts.py — High-level utility functions for model creation and introspection that developers use daily (create_model, etc.).
• playhouse/asyncio.py — Async/await support layer wrapping standard async drivers (aiosqlite, asyncpg, aiomysql) for non-blocking database operations.
• docs/peewee/quickstart.rst — Essential entry point documentation covering model definition, querying, and relationships for new contributors.
• tests/runtests.py — Main test harness orchestrating tests across multiple database backends and discovering all test suites.

• Database class (peewee.py) (sqlite3, psycopg2, mysql.connector, asyncpg, aiomysql, aiosqlite) — Manages connection lifecycle, dialect detection, transaction boundaries, and cursor provisioning.
  • Failure mode: Connection failures surface immediately; transaction rollback on exception; connection pool exhaustion if not managed.
• Model metaclass & Field system (peewee.py) (Python metaclasses, descriptor protocol) — Introspects field definitions, enforces type coercion, and builds SQL column definitions and Python property accessors.
  • Failure mode: Type mismatches cause python_value() exceptions; missing required fields raise validation errors; circular foreign keys cause recursion.
• Query builder (SelectQuery, UpdateQuery, etc. in peewee.py) (SQL expression grammar, parameter binding) — Constructs and caches parameterized SQL from method-chain expressions; handles JOINs, subqueries, and window functions.
  • Failure mode: Invalid SQL syntax if expressions are malformed; N+1 query problems if eager loading not used; performance degradation on large result sets.
• Expression/Clause system (peewee.py) (Python operator overloading (add, and, etc.), recursive tree traversal) — Enables composable SQL building through operator overloading; handles field references, literals, and aggregate functions.
  • Failure mode: Type errors if operators applied to incompatible field types; missing escaping leads to SQL injection if raw strings used.
• Async wrapper (playhouse/asyncio.py) (asyncio, aiosqlite, asyncpg, aiomysql) — Bridges peewee's synchronous API to async drivers; manages async context and connection pooling for coroutines.
  • Failure mode: Blocking operations on event loop cause deadlock; missing await statements fail silently; connection leaks if context managers not used.
• Database-specific extensions (playhouse/{postgres,mysql,sqlite}_ext.py) (PostgreSQL extensions, MySQL JSON, SQLite FTS) — Provides dialect-specific field types, operators, and query optimizations (JSONB, ARRAY, FTS, etc.).
  • Failure mode: Using dialect-specific features on wrong database causes runtime errors; missing field mappings result in unsupported type exceptions.
• Framework bridges (playhouse/{flask,pydantic,django}_utils.py) (Flask, FastAPI, Pydantic, Django) — Integrates peewee with web frameworks and serialization libraries; handles request context and lifecycle.
  • Failure mode: Missing db.init_app() call causes connection errors; context manager misuse causes leaks; serialization fails on unsupported field types.

• Application code → Model.select() / .create() / .save() — Declarative query API translates Python method chains into SQL.
• Model methods → Query builder (SelectQuery, UpdateQuery, DeleteQuery) — Each Model method returns a Query object with fluent interface for chaining filters, joins, and aggregates.
• Query builder → Database.execute() — Query.sql() generates parameterized SQL; Database.execute() provisions a cursor and sends it to the driver.
• Database driver → Database server (SQLite, PostgreSQL, MySQL) — Driver-specific protocol (TCP, file I/O) sends SQL and receives rows; peewee provides parameter binding and escaping.
• Database server → Query.fetch results — Rows are yielded from cursor; Field.python_value() coerces each value to Python type; Model instances assembled from row dicts.
• Model instances → Application logic — ORM returns typed objects with descriptor-based field access and relationship loaders (.get_related(), lazy loading).

Add a new Field type

1. Subclass Field in peewee.py and override init, db_value(), python_value(), and get_column_type(). (peewee.py)
2. For database-specific fields, add to playhouse/{postgres_ext,mysql_ext,sqlite_ext}.py with dialect-specific type mappings. (playhouse/postgres_ext.py)
3. Register the field in the appropriate Database.get_field_converter() or override Field.get_column_type() for SQL dialect. (peewee.py)
4. Add test cases in tests/ covering value coercion, SQL generation, and edge cases. (tests/runtests.py)

Add a new Query expression or operator

1. Subclass Expression or Operation in peewee.py and implement sql() to generate SQL fragments. (peewee.py)
2. Add operator method to Field (e.g., add(), xor()) that returns your new Expression. (peewee.py)
3. For database-specific expressions, place in playhouse/{database}_ext.py and override in Query or ModelSelect if needed. (playhouse/postgres_ext.py)
4. Document in docs/peewee/query_operators.rst and add test coverage. (docs/peewee/query_operators.rst)

Add framework integration (e.g., new web framework)

1. Create playhouse/{framework}_utils.py with Database subclass or helper functions for initialization. (playhouse/flask_utils.py)
2. Implement context managers or decorators for request-scoped connection handling (see flask_utils.py for pattern). (playhouse/flask_utils.py)
3. Add integration guide to docs/peewee/framework_integration.rst with code examples. (docs/peewee/framework_integration.rst)
4. Create a working example in examples/{framework_name}/ directory. (examples/blog/app.py)

Add async support for a new driver

1. Create a new AsyncDatabase subclass in playhouse/asyncio.py that wraps the async driver. (playhouse/asyncio.py)
2. Implement async execute(), execute_insert(), and fetch list/tuple methods matching the driver's async interface. (playhouse/asyncio.py)
3. Override cursor() or get_cursor() to return an async context manager compatible with async/await. (playhouse/asyncio.py)
4. Add test coverage in tests/ with the async driver installed and document in docs/peewee/asyncio.rst. (docs/peewee/asyncio.rst)

• Single-module design (peewee.py) — No external dependencies, easy vendoring, minimal surface area for users to understand the entire framework.
• Metaclass-based Model definition — Declarative syntax for fields and introspection without boilerplate; aligns with Django ORM user expectations.
• Asyncio integration (playhouse/asyncio.py) — Modern Python applications require non-blocking I/O; standard async drivers (aiosqlite, asyncpg) are production-ready.
• Playhouse extension pattern — Keeps core ORM lightweight; opt-in features (JSONB, FTS, framework integrations) reduce bloat for users who don't need them.
• SQL-first query builder — Exposes full database power without abstraction leakage; developers can write complex queries and raw SQL when needed.

• Single monolithic peewee.py file (~7000+ lines)

  • Why: No external dependencies, simpler distribution, all-in-one module import.
  • Consequence: Large file makes navigation harder; increases cognitive load for contributors; harder to split responsibilities cleanly.

• Async support built as opt-in wrapper rather than core feature

  • Why: Avoids forcing async patterns on synchronous users; keeps core ORM simpler.
  • Consequence: Two code paths to maintain; async users must use AsyncDatabase instead of Database; potential feature parity gaps.

• Field validation at python_value() rather than constraint layer

  • Why: Flexible; allows custom validation without database schema constraints.
  • Consequence: Invalid data can exist in the database if written via raw SQL; validation is ORM-only, not enforced at database level.

• No built-in connection pooling in core

  • Why: Different applications have different pooling needs; external libraries (e.g., pgbouncer) are mature.
  • Consequence: Users must configure pooling themselves; connection exhaustion possible in high-concurrency scenarios without explicit setup.

• Does not provide built-in connection pooling (requires external setup).
• Does not include built-in caching or query result memoization.
• Does not enforce database constraints as Python validation (constraints are schema-only).
• Does not support distributed transactions or multi-database joins.
• Does not provide GraphQL, REST API, or admin panel generation.
• Does not automatically migrate schemas (users must write explicit migration scripts or use external tools).

• Implicit N+1 queries on related field access — peewee.py (ForeignKeyField, select_related not called): Accessing .author on 100 Post instances without select_related() triggers 100

No required env vars mentioned in snippets, but database tests will need POSTGRES_USER/POSTGRES_PASSWORD or MYSQL_ROOT_PASSWORD (typical for CI systems running tests against multiple backends). Single-file/module design means no import confusion, but any modification requires understanding the entire ORM surface. Asyncio support is available but only via optional async drivers (aiosqlite, asyncpg, aiomysql) — using regular blocking driver with async code will cause issues. The 'single module' claim is marketing-focused; actual peewee may be a package with submodules.

• Query Builder Pattern — Peewee's entire API is a fluent query builder (User.select().where(...).order_by(...)) — understanding how chainable method composition exposes SQL without writing raw strings is foundational to using the ORM.
• Active Record Pattern — Peewee uses Active Record (models encapsulate both data and database operations) rather than Data Mapper (SQLAlchemy style); knowing this explains why you call User.create() on the model class directly.
• Metaclass Model Definition — Peewee uses Python metaclasses to transform Model subclass field definitions into database column descriptors at class creation time — this is non-obvious magic that affects how inheritance and introspection work.
• Async Context Managers and Coroutine Drivers — Async peewee requires understanding async/await, context managers (async with), and event loop integration with database drivers like asyncpg; peewee bridges synchronous ORM patterns to async drivers.
• Foreign Key Relationships and Backref — Peewee's ForeignKeyField with backref parameter creates bidirectional relationships at model definition time; misunderstanding this causes N+1 query problems or confusing lazy-load behavior.
• Database Abstraction via Dialects — Peewee supports SQLite, MySQL, PostgreSQL by abstracting SQL generation via a dialect system; understanding which SQL features are portable vs. database-specific is critical for cross-database code.
• Eager Loading with prefetch_related / select_related — Unlike some ORMs, peewee uses explicit prefetch_related() and select_related() calls to avoid N+1 queries; the default is lazy loading, so understanding when to prefetch is a common performance gotcha.

• sqlalchemy/sqlalchemy — Heavy-weight ORM alternative with more features and complexity; users often choose peewee specifically to avoid SQLAlchemy's boilerplate.
• django/django — Django ORM is bundled with Django framework; peewee is often used in non-Django projects or minimal frameworks as a lighter alternative.
• tortoise/tortoise-orm — Modern async-first ORM for Python with similar goals to peewee but built for asyncio from the ground up; competes on the async niche.
• magicstack/asyncpg — Fast async PostgreSQL driver that peewee supports via peewee[asyncpg] extra; critical for async peewee workloads.
• encode/databases — Minimal async database layer by Encode; used with async frameworks like Starlette/FastAPI when wanting lighter ORM than peewee.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive asyncio tests for MySQL/MariaDB drivers (aiomysql, asyncmy)

The repo has docs/peewee/asyncio.rst documenting async support for aiosqlite and asyncpg, but .github/workflows/tests.yaml likely lacks dedicated CI matrix testing for aiomysql/asyncmy async MySQL implementations. This gap means async MySQL code paths are untested in CI, risking regressions in a growing use case.

• [ ] Review current test matrix in .github/workflows/tests.yaml to confirm MySQL async drivers aren't tested
• [ ] Add test matrix entries for aiomysql and asyncmy in the GitHub Actions workflow
• [ ] Ensure tests in peewee/tests/ (or similar) cover async MySQL operations: connect, query, transactions, connection pooling
• [ ] Verify the workflow properly installs MySQL/MariaDB test database for async drivers

Document and test CockroachDB (CRDB) dialect support with specific examples

The file structure shows docs/crdb.png exists, suggesting CockroachDB support is partially implemented, but there's no docs/peewee/crdb.rst similar to docs/peewee/postgres.rst, docs/peewee/mysql.rst, etc. This leaves CRDB users without clear setup/dialect documentation and likely without integration tests.

• [ ] Create docs/peewee/crdb.rst documenting CockroachDB connection, dialect selection, and any CRDB-specific quirks
• [ ] Add examples showing CockroachDB-specific features (if any) parallel to postgres.rst and mysql.rst structure
• [ ] Add or extend .github/workflows/tests.yaml with optional CRDB test job (or document local testing)
• [ ] Verify peewee source code has CockroachDB dialect properly implemented and tested

Add integration tests for Pydantic integration (playhouse.pydantic_utils)

The README references 'pydantic' integration via docs/peewee/orm_utils.html#module-playhouse.pydantic_utils, but there's likely no dedicated test file for pydantic serialization/validation workflows. This module deserves explicit coverage since it bridges peewee models to Pydantic, a critical integration point for FastAPI users.

• [ ] Create or extend tests/ directory with test_pydantic_utils.py covering: model-to-pydantic conversion, validation errors, custom validators, nested relationships
• [ ] Test common FastAPI workflows: query result serialization, request body validation with pydantic models backed by peewee
• [ ] Add .github/workflows/tests.yaml test step to run pydantic utils tests with required pydantic version constraints
• [ ] Document any version compatibility constraints (pydantic v1 vs v2) in docs/peewee/orm_utils.rst

• Add type hints (PEP 484) to peewee core or high-value playhouse modules — the codebase is pre-type-hints era and this would improve IDE support and catch bugs without changing functionality.
• Expand docs/peewee/query_library.rst with ORM examples for common patterns missing from the library (e.g., recursive CTEs, window functions with peewee syntax, bulk upsert examples with specific database dialect examples).
• Write integration tests for peewee + Pydantic validation flow in docs/peewee/framework_integration.rst or playhouse/pydantic_utils.py — the Pydantic integration is mentioned but may lack test coverage for edge cases.

Peewee demonstrates reasonable security posture for a mature open-source ORM project. The core codebase appears well-maintained with no evidence of hardcoded secrets or critical infrastructure vulnerabilities in the visible file structure. Primary concerns are: (1) outdated pinned documentation dependency that restricts security updates, (2) inherent SQL injection risks when developers construct raw queries outside the ORM protections, and (3) absence of modern security automation (SAST, dependency scanning) in the CI/CD pipeline. The project would benefit from implementing automated security scanning, establishing a security disclosure policy, and updating dependency constraints to allow security patches.

• Medium · Outdated Sphinx Documentation Dependencies — docs/requirements.txt. The requirements.txt specifies 'docutils<0.18' which is an unusually restrictive constraint. This pins the project to older versions of docutils that may contain security vulnerabilities. The constraint appears arbitrary and may exclude security patches from newer versions. Fix: Update to a more recent version of docutils (>=0.18) and remove the artificial upper bound constraint unless there is a specific compatibility issue. Regularly update documentation dependencies to receive security patches.
• Low · Potential SQL Injection Attack Surface — peewee core module (main ORM library). Peewee is an ORM that exposes SQL query building capabilities. While the ORM itself provides parameterized query support, the codebase description mentions 'flexible query-builder that exposes full power of SQL'. If developers bypass ORM protections and construct raw SQL queries, they may introduce SQL injection vulnerabilities. This is a design pattern risk rather than a specific code vulnerability. Fix: Ensure comprehensive documentation and examples emphasize safe query construction practices. Encourage use of parameterized queries and ORM methods rather than raw SQL. Consider adding linting rules or type hints to prevent raw SQL usage where possible.
• Low · No Evidence of Security Configuration in CI/CD — .github/workflows/tests.yaml, .github/workflows/wheels.yaml. Review of GitHub Actions workflows (.github/workflows/) reveals test and wheel building workflows, but no apparent security scanning, dependency vulnerability checks, or SAST tools are configured in the visible workflow files. Fix: Add GitHub security scanning tools such as Dependabot for dependency vulnerability detection, CodeQL for static analysis, and consider integrating OWASP/security-focused linters in CI/CD pipeline.
• Low · No SECURITY.md or Security Policy — Repository root. The repository does not appear to have a SECURITY.md file or published security policy for reporting vulnerabilities responsibly. This makes it difficult for security researchers to report issues privately. Fix: Create a SECURITY.md file documenting the vulnerability disclosure process and responsible disclosure policy. Include contact information for security reports.
• Low · Travis CI Legacy Configuration — .travis.yml, .travis_deps.sh. The presence of .travis.yml and .travis_deps.sh suggests the project may be using legacy Travis CI configuration alongside GitHub Actions, which could lead to inconsistent or unmonitored CI/CD pipelines. Fix: Migrate completely to GitHub Actions if no longer using Travis CI, and remove legacy configuration files. Ensure all CI/CD security checks are consolidated in the primary pipeline.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/coleifer/peewee shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live coleifer/peewee repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/coleifer/peewee.

What it runs against: a local clone of coleifer/peewee — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in coleifer/peewee | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of coleifer/peewee. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/coleifer/peewee.git
#   cd peewee
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of coleifer/peewee and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "coleifer/peewee(\\.git)?\\b" \\
  && ok "origin remote is coleifer/peewee" \\
  || miss "origin remote is not coleifer/peewee (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "peewee.py" \\
  && ok "peewee.py" \\
  || miss "missing critical file: peewee.py"
test -f "playhouse/postgres_ext.py" \\
  && ok "playhouse/postgres_ext.py" \\
  || miss "missing critical file: playhouse/postgres_ext.py"
test -f "playhouse/mysql_ext.py" \\
  && ok "playhouse/mysql_ext.py" \\
  || miss "missing critical file: playhouse/mysql_ext.py"
test -f "playhouse/shortcuts.py" \\
  && ok "playhouse/shortcuts.py" \\
  || miss "missing critical file: playhouse/shortcuts.py"
test -f "playhouse/asyncio.py" \\
  && ok "playhouse/asyncio.py" \\
  || miss "missing critical file: playhouse/asyncio.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/coleifer/peewee"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.