Peewee ORM

Peewee ORM

Original author(s)	Charles Leifer[1]
Initial release	October 11, 2010[2]
Stable release	2.6.4 / September 22, 2015
Development status	Active
Written in	Python
Operating system	Cross-platform
Type	Object-relational mapping
License	MIT License
Website	peewee-orm.com

Peewee is an open source object-relational mapper (ORM) for the Python programming language released under the MIT License.

Peewee provides a lightweight, expressive Python API for interacting with relational databases. Peewee follows the active record pattern used by a number of other object-relational mappers. Peewee supports PostgreSQL, MySQL and SQLite and has many database-specific extensions included in the Playhouse collection of add-ons.

Peewee was first released on October 11, 2010.^[2] In October 2012, Peewee was completely rewritten and version 2.0 was released.^[3]

Example

The following example represents an n-to-1 relationship between people and their status updates. It shows how user-defined Python classes are mapped to database tables, and how to execute common database queries.

Schema definition

Creating two Python classes and according database tables in the DBMS:

from peewee import *

db = SqliteDatabase('app.db')

class BaseModel(Model):
    class Meta:
        database = db

class Person(BaseModel):
    name = CharField(max_length=100, index=True)

class StatusUpdate(BaseModel):
    person = ForeignKeyField(Person, related_name='statuses')
    status = TextField()
    timestamp = DateTimeField(default=datetime.datetime.now, index=True)

Person.create_table()
StatusUpdate.create_table()

Data insertion

Inserting people and their status updates:

# New rows can be added by creating an instance and calling save():
huey = Person(name='Huey')
huey.save()

# Or the create() method can be used:
charlie = Person.create(name='Charlie')

StatusUpdate.create(person=charlie, status='Hello, world')
StatusUpdate.create(person=charlie, status='Hello, peewee')

# Using a transaction.
with db.atomic():
    StatusUpdate.create(person=huey, status='Hello')

Querying

people = Person.select().order_by(Person.name)
for person in people:
    print person.name
    for status in person.statuses.order_by(StatusUpdate.timestamp):
        print '*', status.status

The output:

Charlie
* Hello, world
* Hello, peewee
Huey
* Hello

Performing a join:

charlie_statuses = (StatusUpdate
                    .select(StatusUpdate, Person)
                    .join(Person)
                    .where(Person.name == 'Charlie')
                    .order_by(StatusUpdate.timestamp.desc()))
for status in charlie_statuses:
    print status.person.name, '-', status.status

The output:

Charlie - Hello, peewee
Charlie - Hello, world

Features

• Support for PostgreSQL, MySQL and SQLite
• Postgresql HStore, Arrays, JSON data type, UUID data type, server-side cursors.
• SQLite full-text search, custom aggregates, collations and user-defined functions.
• APSW advanced SQLite driver.
• Schema migrations.
• Connection pooling.
• Read replicas.
• SQLCipher encrypted SQLite database.

See also

• SQLAlchemy
• Django

References

1. Charles Leifer is the creator of peewee ORM.
2. Leifer, Charles (October 11, 2010). "[ANN] Peewee 0.1". Peewee. Retrieved October 11, 2010.
3. Leifer, Charles (October 8, 2012). "[ANN] Peewee 2.0". Peewee. Retrieved October 8, 2012.

External links

• Peewee documentation
• Peewee on GitHub
• Peewee 2.0 announcement
• Using Databases in Python tutorial
• Awesome Python list of ORMs