Models and Fields

Model classes, Field instances and model instances all map to database concepts:

The following code shows the typical way you will define your database connection and model classes.

from peewee import *
db = SqliteDatabase('my_app.db')
class BaseModel(Model):
    class Meta:
        database = db
class User(BaseModel):
    username = CharField(unique=True)
class Tweet(BaseModel):
    user = ForeignKeyField(User, backref='tweets')
    message = TextField()
    created_date = DateTimeField(default=datetime.datetime.now)
    is_published = BooleanField(default=True)

1. Create an instance of a Database.

   db = SqliteDatabase('my_app.db')

   The db object will be used to manage the connections to the Sqlite database. In this example we’re using SqliteDatabase, but you could also use one of the other database engines.

2. Create a base model class which specifies our database.

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

   It is good practice to define a base model class which establishes the database connection. This makes your code DRY as you will not have to specify the database for subsequent models.

   Model configuration is kept namespaced in a special class called Meta. This convention is borrowed from Django. Meta configuration is passed on to subclasses, so our project’s models will all subclass BaseModel. There are many different attributes you can configure using Model.Meta.

3. Define a model class.

   class User(BaseModel):
       username = CharField(unique=True)

   Model definition uses the declarative style seen in other popular ORMs like SQLAlchemy or Django. Note that we are extending the BaseModel class so the User model will inherit the database connection.

   We have explicitly defined a single username column with a unique constraint. Because we have not specified a primary key, peewee will automatically add an auto-incrementing integer primary key field named id.

Note

If you would like to start using peewee with an existing database, you can use pwiz, a model generator to automatically generate model definitions.