Skip to main content

a little orm

Project description


  • a small, expressive orm

  • written in python (2.6+, 3.2+)

  • built-in support for sqlite, mysql and postgresql and special extensions like hstore

For flask integration, including an admin interface and RESTful API, check out flask-peewee.

For notes on the upgrade from 1.0 to 2.0, check out the upgrade docs.

Check out the quickstart IPython notebook.

Example queries:

# a simple query selecting a user
User.get(User.username == 'charles')

# get the staff and super users
editors =
    (User.is_staff == True) |
    (User.is_superuser == True)

# get tweets by editors ("<<" maps to IN) << editors)

# how many active users are there? == True).count()

# paginate the user table and show me page 3 (users 41-60), 20)

# order users by number of tweets

# a similar way of expressing the same
tweet_ct = fn.Count(
  .select(User, tweet_ct.alias('ct'))

# do an atomic update
Counter.update(count=Counter.count + 1).where(
    Counter.url == request.url

Check out the quick start for more!

Learning more

the official peewee cookbook has recipes for common operations and is a good place to get started.

check the documentation for more examples.

specific question? come hang out in the #peewee channel on, or post to the mailing list,

lastly, peewee runs on python 2.6+ or 3.2+.

Still want more info?


peewee began when I was working on a small app in flask and found myself writing lots of queries and wanting a very simple abstraction on top of the sql. I had so much fun working on it that I kept adding features. peewee is small enough that its my hope anyone with an interest in orms will be able to understand the code without much trouble.

model definitions and schema creation

smells like django:

from peewee import *

class Blog(Model):
    title = CharField()

    def __unicode__(self):
        return self.title

class Entry(Model):
    title = CharField(max_length=50)
    content = TextField()
    pub_date = DateTimeField()
    blog = ForeignKeyField(Blog, related_name='entries')

    def __unicode__(self):
        return '%s: %s' % (, self.title)

open a connection to the database:

>>> from peewee import database
>>> database.connect()

create a set of tables from models

>>> from peewee import create_model_tables
>>> create_model_tables([Blog, Entry]) # will be sorted topologically

create a specific table

>>> Blog.create_table()
>>> Entry.create_table()

drop a specific table

>>> Blog.drop_table()
>>> Entry.drop_table()

drop a set of tables from models

>>> from peewee import drop_model_tables
>>> drop_model_tables([Blog, Entry]) # Drop tables for all given models (in the right order)

foreign keys work like django’s

>>> b = Blog(title="Peewee's Big Adventure")
>>> e = Entry(title="Greatest movie ever?", content="YES!", blog=b)
<Blog: Peewee's Big Adventure>
>>> for e in b.entries:
...     print e.title
Greatest movie ever?


queries come in 5 flavors (select/update/insert/delete/”raw”).

there’s the notion of a query context which is the model being selected or joined on: == True).order_by(User.username)

since User is the model being selected, the where clause and the order_by will pertain to attributes on the User model. User is the current query context when the .where() and .order_by() are evaluated.

an example using joins:

  .where((Tweet.deleted == False) & ( == True))

this will select non-deleted tweets from active users.

using sqlite

from peewee import *

database = SqliteDatabase('my.db')

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

class Blog(BaseModel):
    creator = CharField()
    name = CharField()

class Entry(BaseModel):
    creator = CharField()
    name = CharField()

using postgresql

you can now use postgresql:

from peewee import *

database = PostgresqlDatabase('my_db', user='root')

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

# ... same as above sqlite example ...

using mysql

you can now use MySQL:

from peewee import *

database = MySQLDatabase('my_db', user='root')

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

# ... same as above sqlite example ...

what now?

Check out the quick start

Project details

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

peewee-2.1.5.tar.gz (827.2 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page