API Reference — peewee 2.1.3 documentation

### Navigation

- index
- next |
- previous |
- peewee 2.1.3 documentation »

# API Reference

## Expressions

Peewee was designed to provide a simple, expressive, and pythonic way of executing queries. This section will provide a quick overview of some common types of expressions.

There are two primary types of objects that can be composed to create expressions:

- `Field` instances
- SQL aggregations and functions using `fn`

We will assume a simple “User” model with fields for username and other things. It looks like this:

    class User(Model):
        username = CharField()
        is_admin = BooleanField()
        is_active = BooleanField()
        last_login = DateTimeField()
        login_count = IntegerField()
        failed_logins = IntegerField()

Comparisons use the Column lookups:

    # username is equal to 'charlie'
    User.username == 'charlie'

    # user has logged in less than 5 times
    User.login_count < 5

Comparisons can be combined using bitwise “and” and “or”. Operator precedence is controlled by python and comparisons can be nested to an arbitrary depth:

    # user is both and admin and has logged in today
    (User.is_admin == True) & (User.last_login >= today)

    # user's username is either charlie or charles
    (User.username == 'charlie') | (User.username == 'charles')

Comparisons can be used with functions as well:

    # user's username starts with a 'g' or a 'G':
    fn.Lower(fn.Substr(User.username, 1, 1)) == 'g'

We can do some fairly interesting things, as expressions can be compared against other expressions. Expressions also support arithmetic operations:

    # users who entered the incorrect more than half the time and have logged
    # in at least 10 times
    (User.failed_logins > (User.login_count * .5)) & (User.login_count > 10)

Expressions allow us to do atomic updates:

    # when a user logs in we want to increment their login count:
    User.update(login_count=User.login_count + 1).where(User.id == user_id)

Expressions can be used in all parts of a query, so experiment!

## Models

class `Model`(**kwargs)

  Models provide a 1-to-1 mapping to database tables. Subclasses of `Model` declare any number of `Field` instances as class attributes. These fields correspond to columns on the table.

  Table-level operations, such as select/update/insert/delete queries, are implemented as classmethods. Row-level operations such as saving or deleting individual instances are implemented as instancemethods.

  Parameters: | kwargs – Initialize the model, assigning the given key/values to the appropriate fields.

  Example:

      class User(Model):
          username = CharField()
          join_date = DateTimeField()
          is_admin = BooleanField()

      u = User(username='charlie', is_admin=True)

  classmethod `select`(*selection)

    Parameters: | selection – a list of model classes, field instances, functions or expressions
    Return type: | a `SelectQuery` for the given `Model`

    Examples of selecting all columns (default):

        User.select().where(User.active == True).order_by(User.username)

    Example of selecting all columns on `Tweet` and the parent model, `User`. When the `user` foreign key is accessed on a `Tweet` instance no additional query will be needed:

        (Tweet
          .select(Tweet, User)
          .join(User)
          .order_by(Tweet.created_date.desc()))

  classmethod `update`(**update)

    Parameters: | update – mapping of field-name to expression
    Return type: | an `UpdateQuery` for the given `Model`

    Example showing users being marked inactive if their registration expired:

        q = User.update(active=False).where(User.registration_expired == True)
        q.execute()  # execute the query, updating the database.

    Example showing an atomic update:

        q = PageView.update(count=PageView.count + 1).where(PageView.url == url)
        q.execute()  # execute the query, updating the database.

  classmethod `insert`(**insert)

    Parameters: | insert – mapping of field-name to expression
    Return type: | an `InsertQuery` for the given `Model`

    Example showing creation of a new user:

        q = User.insert(username='admin', active=True, registration_expired=False)
        q.execute()  # perform the insert.

  classmethod `delete`()

    Return type: | a `DeleteQuery` for the given `Model`

    Example showing the deletion of all inactive users:

        q = User.delete().where(User.active == False)
        q.execute()  # remove the rows

    Warning

    This method performs a delete on the entire table. To delete a single instance, see `Model.delete_instance()`.

  classmethod `raw`(sql, *params)

    Parameters: | sql – a string SQL expression params – any number of parameters to interpolate
    Return type: | a `RawQuery` for the given `Model`

    Example selecting rows from the User table:

        q = User.raw('select id, username from users')
        for user in q:
            print user.id, user.username

    Note

    Generally the use of `raw` is reserved for those cases where you can significantly optimize a select query. It is useful for select queries since it will return instances of the model.

  classmethod `create`(**attributes)

    Parameters: | attributes – key/value pairs of model attributes
    Return type: | a model instance with the provided attributes

    Example showing the creation of a user (a row will be added to the database):

        user = User.create(username='admin', password='test')

    Note

    The create() method is a shorthand for instantiate-then-save.

  classmethod `get`(*args, **kwargs)

    Parameters: | args – a list of query expressions, e.g. `User.username == 'foo'` kwargs – a mapping of column + lookup to value, e.g. “age__gt=55”
    Return type: | `Model` instance or raises `DoesNotExist` exception

    Get a single row from the database that matches the given query. Raises a `<model-class>.DoesNotExist` if no rows are returned:

        user = User.get(User.username == username, User.password == password)

    This method is also exposed via the `SelectQuery`, though it takes no parameters:

        active = User.select().where(User.active == True)
        try:
            users = active.where(User.username == username, User.password == password)
            user = users.get()
        except User.DoesNotExist:
            user = None

    Note

    The `get()` method is shorthand for selecting with a limit of 1. It has the added behavior of raising an exception when no matching row is found. If more than one row is found, the first row returned by the database cursor will be used.

    Warning

    the “kwargs” style syntax is provided for compatibility with version 1.0. The expression-style syntax is preferable.

  classmethod `get_or_create`(**attributes)

    Deprecated since version 2.0: Because this relies of “django-style” expressions, it has been deprecated as of 2.0. Use `Model.get()` and `Model.create()` explicitly.

    Parameters: | attributes – key/value pairs of model attributes
    Return type: | a `Model` instance

    Get the instance with the given attributes set. If the instance does not exist it will be created.

    Example showing get/create an object cached in the database:

        CachedObj.get_or_create(key=key, val=some_val)

  classmethod `filter`(*args, **kwargs)

    Deprecated since version 2.0: Use `select` instead.

    Parameters: | args – a list of `DQ` or expression objects kwargs – a mapping of column + lookup to value, e.g. “age__gt=55”
    Return type: | `SelectQuery` with appropriate `WHERE` clauses

    Provides a django-like syntax for building a query. The key difference between `filter()` and `SelectQuery.where()` is that `filter()` supports traversing joins using django’s “double-underscore” syntax:

        sq = Entry.filter(blog__title='Some Blog')

  classmethod `alias`()

    Return type: | `ModelAlias` instance

    The alias() method is used to build queries that use self-joins.

    Example:

        Parent = Category.alias()
        sq = (Category
          .select(Category, Parent)
          .join(Parent, on=(Category.parent == Parent.id))
          .where(Parent.name == 'parent category'))

    Note

    You must explicitly specify which columns to join on

  classmethod `create_table`([fail_silently=False])

    Parameters: | fail_silently (bool) – If set to `True`, the method will check for the existence of the table before attempting to create.

    Create the table for the given model.

    Example:

        database.connect()
        SomeModel.create_table()  # Execute the create table query.

  classmethod `drop_table`([fail_silently=False])

    Parameters: | fail_silently (bool) – If set to `True`, the query will check for the existence of the table before attempting to remove.

    Drop the table for the given model.

    Note

    Cascading deletes are not handled by this method, nor is the removal of any constraints.

  classmethod `table_exists`()

    Return type: | Boolean whether the table for this model exists in the database

  `save`([force_insert=False[, only=None]])

    Parameters: | force_insert (bool) – Whether to force execution of an insert only (list) – A list of fields to persist – when supplied, only the given fields will be persisted.

    Save the given instance, creating or updating depending on whether it has a primary key. If `force_insert=True` an `INSERT` will be issued regardless of whether or not the primary key exists.

    Example showing saving a model instance:

        user = User()
        user.username = 'some-user'  # does not touch the database
        user.save()  # change is persisted to the db

  `delete_instance`([recursive=False[, delete_nullable=False]])

    Parameters: | recursive – Delete this instance and anything that depends on it, optionally updating those that have nullable dependencies delete_nullable – If doing a recursive delete, delete all dependent objects regardless of whether it could be updated to NULL

    Delete the given instance. Any foreign keys set to cascade on delete will be deleted automatically. For more programmatic control, you can call with recursive=True, which will delete any non-nullable related models (those that are nullable will be set to NULL). If you wish to delete all dependencies regardless of whether they are nullable, set `delete_nullable=True`.

    example:

        some_obj.delete_instance()  # it is gone forever

  `dependencies`([search_nullable=False])

    Parameters: | search_nullable (bool) – Search models related via a nullable foreign key
    Return type: | Generator expression yielding queries and foreign key fields

    Generate a list of queries of dependent models. Yields a 2-tuple containing the query and corresponding foreign key field. Useful for searching dependencies of a model, i.e. things that would be orphaned in the event of a delete.

## Fields

class `Field`(null=False, index=False, unique=False, verbose_name=None, help_text=None, db_column=None, default=None, choices=None, *args, **kwargs)

  The base class from which all other field types extend.

  Parameters: | null (bool) – whether this column can accept `None` or `NULL` values index (bool) – whether to create an index for this column when creating the table unique (bool) – whether to create a unique index for this column when creating the table verbose_name (string) – specify a “verbose name” for this field, useful for metadata purposes help_text (string) – specify some instruction text for the usage/meaning of this field db_column (string) – column name to use for underlying storage, useful for compatibility with legacy databases default – a value to use as an uninitialized default choices – an iterable of 2-tuples mapping `value` to `display` primary_key (bool) – whether to use this as the primary key for the table sequence (string) – name of sequence (if backend supports it) kwargs – named attributes containing values that may pertain to specific field subclasses, such as “max_length” or “decimal_places”

  `db_field = '<some field type>'`

    Attribute used to map this field to a column type, e.g. “string” or “datetime”

  `template = '%(column_type)s'`

    A template for generating the SQL for this field

  `_is_bound`

    Boolean flag indicating if the field is attached to a model class.

  `model_class`

    The model the field belongs to. Only applies to bound fields.

  `name`

    The name of the field. Only applies to bound fields.

  `db_value`(value)

    Parameters: | value – python data type to prep for storage in the database
    Return type: | converted python datatype

  `python_value`(value)

    Parameters: | value – data coming from the backend storage
    Return type: | python data type

  `coerce`(value)

    This method is a shorthand that is used, by default, by both `db_value` and `python_value`. You can usually get away with just implementing this.

    Parameters: | value – arbitrary data from app or backend
    Return type: | python data type

  `field_attributes`()

    This method is responsible for return a dictionary containing the default field attributes for the column, e.g. `{'max_length': 255}`

    Return type: | a python dictionary

  `between`(low, high)

    Return an expression suitable for performing “BETWEEN” queries.

    Return type: | an `Expression` object.

        # select employees making between $50 and $60
        Employee.select().where(Employee.salary.between(50, 60))

class `IntegerField`

  Stores: integers

  `db_field = 'int'`

class `BigIntegerField`

  Stores: big integers

  `db_field = 'bigint'`

class `PrimaryKeyField`

  Stores: auto-incrementing integer fields suitable for use as primary key.

  `db_field = 'primary_key'`

class `FloatField`

  Stores: floating-point numbers

  `db_field = 'float'`

class `DoubleField`

  Stores: double-precision floating-point numbers

  `db_field = 'double'`

class `DecimalField`

  Stores: decimal numbers, using python standard library `Decimal` objects

  Additional attributes and values:

  `max_digits` | `10`
  `decimal_places` | `5`
  `auto_round` | `False`
  `rounding` | `decimal.DefaultContext.rounding`

  `db_field = 'decimal'`
  `template = '%(column_type)s(%(max_digits)d, %(decimal_places)d)'`

class `CharField`

  Stores: small strings (0-255 bytes)

  Additional attributes and values:

  `max_length` | `255`

  `db_field = 'string'`
  `template = '%(column_type)s(%(max_length)s)'`

class `TextField`

  Stores: arbitrarily large strings

  `db_field = 'text'`

class `DateTimeField`

  Stores: python `datetime.datetime` instances

  Accepts a special parameter `formats`, which contains a list of formats the datetime can be encoded with. The default behavior is:

      '%Y-%m-%d %H:%M:%S.%f' # year-month-day hour-minute-second.microsecond
      '%Y-%m-%d %H:%M:%S' # year-month-day hour-minute-second
      '%Y-%m-%d' # year-month-day

  Note

  If the incoming value does not match a format, it will be returned as-is

  `db_field = 'datetime'`
  `year`

    An expression suitable for extracting the year, for example to retrieve all blog posts from 2013:

        Blog.select().where(Blog.pub_date.year == 2013)

  `month`

    Same as `year`, except extract month.

  `day`

    Same as `year`, except extract day.

  `hour`

    Same as `year`, except extract hour.

  `minute`

    Same as `year`, except extract minute.

  `second`

    Same as `year`, except extract second..

class `DateField`

  Stores: python `datetime.date` instances

  Accepts a special parameter `formats`, which contains a list of formats the date can be encoded with. The default behavior is:

      '%Y-%m-%d' # year-month-day
      '%Y-%m-%d %H:%M:%S' # year-month-day hour-minute-second
      '%Y-%m-%d %H:%M:%S.%f' # year-month-day hour-minute-second.microsecond

  Note

  If the incoming value does not match a format, it will be returned as-is

  `db_field = 'date'`
  `year`

    An expression suitable for extracting the year, for example to retrieve all people born in 1980:

        Person.select().where(Person.dob.year == 1983)

  `month`

    Same as `year`, except extract month.

  `day`

    Same as `year`, except extract day.

class `TimeField`

  Stores: python `datetime.time` instances

  Accepts a special parameter `formats`, which contains a list of formats the time can be encoded with. The default behavior is:

      '%H:%M:%S.%f' # hour:minute:second.microsecond
      '%H:%M:%S' # hour:minute:second
      '%H:%M' # hour:minute
      '%Y-%m-%d %H:%M:%S.%f' # year-month-day hour-minute-second.microsecond
      '%Y-%m-%d %H:%M:%S' # year-month-day hour-minute-second

  Note

  If the incoming value does not match a format, it will be returned as-is

  `db_field = 'time'`
  `hour`

    Extract the hour from a time, for example to retreive all events occurring in the evening:

        Event.select().where(Event.time.hour > 17)

  `minute`

    Same as `hour`, except extract minute.

  `second`

    Same as `hour`, except extract second..

class `BooleanField`

  Stores: `True` / `False`

  `db_field = 'bool'`

class `ForeignKeyField`(rel_model[, related_name=None[, cascade=False[, ...]]])

  Stores: relationship to another model

  Parameters: | rel_model – related `Model` class or the string ‘self’ if declaring a self-referential foreign key related_name (string) – attribute to expose on related model cascade (bool) – set up foreign key to do cascading deletes

      class User(Model):
          name = CharField()

      class Tweet(Model):
          user = ForeignKeyField(User, related_name='tweets')
          content = TextField()

      # "user" attribute
      >>> some_tweet.user
      <User: charlie>

      # "tweets" related name attribute
      >>> for tweet in charlie.tweets:
      ...     print tweet.content
      Some tweet
      Another tweet
      Yet another tweet

  Note

  Foreign keys do not have a particular `db_field` as they will take their field type depending on the type of primary key on the model they are related to.

## Query Types

class `Query`

  The parent class from which all other query classes are drived.

  `where`(*expressions)

    Parameters: | expressions – a list of one or more expressions
    Return type: | a `Query` instance

    Example selection users where the username is equal to ‘somebody’:

        sq = SelectQuery(User).where(User.username == 'somebody')

    Example selecting tweets made by users who are either editors or administrators:

        sq = SelectQuery(Tweet).join(User).where(
            (User.is_editor == True) |
            (User.is_admin == True))

    Example of deleting tweets by users who are no longer active:

        dq = DeleteQuery(Tweet).where(
            Tweet.user << User.select().where(User.active == False))
        dq.execute()  # perform the delete query

    Note

    `where()` calls are chainable. Multiple calls will be “AND”-ed together.

  `join`(model, join_type=None, on=None)

    Parameters: | model – the model to join on. there must be a `ForeignKeyField` between the current `query context` and the model passed in. join_type – allows the type of `JOIN` used to be specified explicitly, one of `JOIN_INNER`, `JOIN_LEFT_OUTER`, `JOIN_FULL` on – if multiple foreign keys exist between two models, this parameter is the ForeignKeyField to join on.
    Return type: | a `Query` instance

    Generate a `JOIN` clause from the current `query context` to the `model` passed in, and establishes `model` as the new `query context`.

    Example selecting tweets and joining on user in order to restrict to only those tweets made by “admin” users:

        sq = SelectQuery(Tweet).join(User).where(User.is_admin == True)

    Example selecting users and joining on a particular foreign key field. See the example app for a real-life usage:

        sq = SelectQuery(User).join(Relationship, on=Relationship.to_user)

  `switch`(model)

    Parameters: | model – model to switch the `query context` to.
    Return type: | a clone of the query with a new query context

    Switches the `query context` to the given model. Raises an exception if the model has not been selected or joined on previously. Useful for performing multiple joins from a single table.

    The following example selects from blog and joins on both entry and user:

        sq = SelectQuery(Blog).join(Entry).switch(Blog).join(User)

  `filter`(*args, **kwargs)

    Deprecated since version 2.0: Use instead `Query.where()`

    Parameters: | args – a list of `DQ` or `Node` objects kwargs – a mapping of column + lookup to value, e.g. “age__gt=55”
    Return type: | `SelectQuery` with appropriate `WHERE` clauses

    Provides a django-like syntax for building a query. The key difference between `filter()` and `SelectQuery.where()` is that `filter()` supports traversing joins using django’s “double-underscore” syntax:

        sq = Entry.filter(blog__title='Some Blog')

    This method is chainable:

        base_q = User.filter(active=True)
        some_user = base_q.filter(username='charlie')

    Note

    this method is provided for compatibility with peewee 1.

  `alias`(alias=None)

    Parameters: | alias (str) – A string to alias the result of this query
    Return type: | a Query instance

    Assign an alias to given query, which can be used as part of a subquery.

  `sql`()

    Return type: | a 2-tuple containing the appropriate SQL query and a tuple of parameters

  `execute`()

    Execute the given query

  `scalar`([as_tuple=False])

    Parameters: | as_tuple (bool) – return the row as a tuple or a single value
    Return type: | the resulting row, either as a single value or tuple

    Provide a way to retrieve single values from select queries, for instance when performing an aggregation.

        >>> PageView.select(fn.Count(fn.Distinct(PageView.url))).scalar()
        100 # <-- there are 100 distinct URLs in the pageview table

class `SelectQuery`(model, *selection)

  By far the most complex of the query classes available in peewee. It supports all clauses commonly associated with select queries.

  Methods on the select query can be chained together.

  `SelectQuery` implements an `__iter__()` method, allowing it to be iterated to return model instances.

  Parameters: | model – a `Model` class to perform query on selection – a list of models, fields, functions or expressions

  If no selection is provided, it will default to all the fields of the given model.

  Example selecting some user instances from the database. Only the `id` and `username` columns are selected. When iterated, will return instances of the `User` model:

      sq = SelectQuery(User, User.id, User.username)
      for user in sq:
          print user.username

  Example selecting users and additionally the number of tweets made by the user. The `User` instances returned will have an additional attribute, ‘count’, that corresponds to the number of tweets made:

      sq = (SelectQuery(
          User, User, fn.Count(Tweet.id).alias('count'))
          .join(Tweet)
          .group_by(User))

  `group_by`(*clauses)

    Parameters: | clauses – a list of expressions, which can be model classes or individual field instances
    Return type: | `SelectQuery`

    Group by one or more columns. If a model class is provided, all the fields on that model class will be used.

    Example selecting users, joining on tweets, and grouping by the user so a count of tweets can be calculated for each user:

        sq = (User
            .select(User, fn.Count(Tweet.id).alias('count'))
            .join(Tweet)
            .group_by(User))

  `having`(*expressions)

    Parameters: | expressions – a list of one or more expressions
    Return type: | `SelectQuery`

    Here is the above example selecting users and tweet counts, but restricting the results to those users who have created 100 or more tweets:

        sq = (User
            .select(User, fn.Count(Tweet.id).alias('count'))
            .join(Tweet)
            .group_by(User)
            .having(fn.Count(Tweet.id) > 100))

  `order_by`(*clauses)

    Parameters: | clauses – a list of fields, calls to `field.[asc|desc]()` or one or more expressions
    Return type: | `SelectQuery`

    Example of ordering users by username:

        User.select().order_by(User.username)

    Example of selecting tweets and ordering them first by user, then newest first:

        Tweet.select().join(User).order_by(
            User.username, Tweet.created_date.desc())

    A more complex example ordering users by the number of tweets made (greatest to least), then ordered by username in the event of a tie:

        tweet_ct = fn.Count(Tweet.id)
        sq = (User
            .select(User, tweet_ct.alias('count'))
            .join(Tweet)
            .group_by(User)
            .order_by(tweet_ct.desc(), User.username))

  `limit`(num)

    Parameters: | num (int) – limit results to `num` rows

  `offset`(num)

    Parameters: | num (int) – offset results by `num` rows

  `paginate`(page_num, paginate_by=20)

    Parameters: | page_num – a 1-based page number to use for paginating results paginate_by – number of results to return per-page
    Return type: | `SelectQuery`

    Shorthand for applying a `LIMIT` and `OFFSET` to the query.

        User.select().order_by(User.username).paginate(3, 20)  # get users 41-60

  `distinct`()

    Return type: | `SelectQuery`

    indicates that this query should only return distinct rows. results in a `SELECT DISTINCT` query.

  `for_update`([for_update=True])

    Return type: | `SelectQuery`

    indicates that this query should lock rows for update

  `naive`()

    Return type: | `SelectQuery`

    Flag this query indicating it should only attempt to reconstruct a single model instance for every row returned by the cursor. If multiple tables were queried, the columns returned are patched directly onto the single model instance.

    Generally this method is useful for speeding up the time needed to construct model instances given a database cursor.

    Note

    this can provide a significant speed improvement when doing simple iteration over a large result set.

  `tuples`()

    Return type: | `SelectQuery`

    Flag this query indicating it should simply return raw tuples from the cursor. This method is useful when you either do not want or do not need full model instances.

  `dicts`()

    Return type: | `SelectQuery`

    Flag this query indicating it should simply return dictionaries from the cursor. This method is useful when you either do not want or do not need full model instances.

  `annotate`(related_model, aggregation=None)

    Parameters: | related_model – related `Model` on which to perform aggregation, must be linked by `ForeignKeyField`. aggregation – the type of aggregation to use, e.g. `fn.Count(Tweet.id).alias('count')`
    Return type: | `SelectQuery`

    Annotate a query with an aggregation performed on a related model, for example, “get a list of users with the number of tweets for each”:

        >>> User.select().annotate(Tweet)

    If `aggregation` is None, it will default to `fn.Count(related_model.id).alias('count')` but can be anything:

        >>> user_latest = User.select().annotate(Tweet, fn.Max(Tweet.created_date).alias('latest'))

    Note

    If the `ForeignKeyField` is `nullable`, then a `LEFT OUTER` join may need to be used:

        User.select().join(Tweet, JOIN_LEFT_OUTER).annotate(Tweet)

  `aggregate`(aggregation)

    Parameters: | aggregation – a function specifying what aggregation to perform, for example `fn.Max(Tweet.created_date)`.

    Method to look at an aggregate of rows using a given function and return a scalar value, such as the count of all rows or the average value of a particular column.

  `count`()

    Return type: | an integer representing the number of rows in the current query

        >>> sq = SelectQuery(Tweet)
        >>> sq.count()
        45  # number of tweets
        >>> sq.where(Tweet.status == DELETED)
        >>> sq.count()
        3  # number of tweets that are marked as deleted

  `wrapped_count`()

    Return type: | an integer representing the number of rows in the current query

    Wrap the count query in a subquery. Additional overhead but will give correct counts when performing `DISTINCT` queries or those with `GROUP BY` clauses.

    Note

    `count()` will automatically default to `wrapped_count()` in the event the query is distinct or has a grouping.

  `exists`()

    Return type: | boolean whether the current query will return any rows. uses an optimized lookup, so use this rather than `get()`.

        sq = User.select().where(User.active == True)
        if sq.where(User.username == username, User.password == password).exists():
            authenticated = True

  `get`()

    Return type: | `Model` instance or raises `DoesNotExist` exception

    Get a single row from the database that matches the given query. Raises a `<model-class>.DoesNotExist` if no rows are returned:

        active = User.select().where(User.active == True)
        try:
            user = active.where(User.username == username).get()
        except User.DoesNotExist:
            user = None

    This method is also exposed via the `Model` api, in which case it accepts arguments that are translated to the where clause:

    > user = User.get(User.active == True, User.username == username)

  `first`()

    Return type: | `Model` instance or `None` if no results

    Fetch the first row from a query. The result will be cached in case the entire query result-set should be iterated later.

  `execute`()

    Return type: | `QueryResultWrapper`

    Executes the query and returns a `QueryResultWrapper` for iterating over the result set. The results are managed internally by the query and whenever a clause is added that would possibly alter the result set, the query is marked for re-execution.

  `__iter__`()

    Executes the query and returns populated model instances:

        for user in User.select().where(User.active == True):
            print user.username

class `UpdateQuery`(model, **kwargs)

  Parameters: | model – `Model` class on which to perform update kwargs – mapping of field/value pairs containing columns and values to update

  Example in which users are marked inactive if their registration expired:

      uq = UpdateQuery(User, active=False).where(User.registration_expired == True)
      uq.execute()  # Perform the actual update

  Example of an atomic update:

      atomic_update = UpdateQuery(PageCount, count = PageCount.count + 1).where(
          PageCount.url == url)
      atomic_update.execute()  # will perform the actual update

  `execute`()

    Return type: | Number of rows updated

    Performs the query

class `InsertQuery`(model, **kwargs)

  Creates an `InsertQuery` instance for the given model where kwargs is a dictionary of field name to value:

      >>> iq = InsertQuery(User, username='admin', password='test', active=True)
      >>> iq.execute()  # insert new row and return primary key
      2L

  `execute`()

    Return type: | primary key of the new row

    Performs the query

class `DeleteQuery`

  Creates a `DeleteQuery` instance for the given model.

  Note

  DeleteQuery will not traverse foreign keys or ensure that constraints are obeyed, so use it with care.

  Example deleting users whose account is inactive:

      dq = DeleteQuery(User).where(User.active == False)

  `execute`()

    Return type: | Number of rows deleted

    Performs the query

class `RawQuery`

  Allows execution of an arbitrary query and returns instances of the model via a `QueryResultsWrapper`.

  Note

  Generally you will only need this for executing highly optimized SELECT queries.

  Warning

  If you are executing a parameterized query, you must use the correct interpolation string for your database. SQLite uses `'?'` and most others use `'%s'`.

  Example selecting users with a given username:

      >>> rq = RawQuery(User, 'SELECT * FROM users WHERE username = ?', 'admin')
      >>> for obj in rq.execute():
      ...     print obj
      <User: admin>

  `tuples`()

    Return type: | `RawQuery`

    Flag this query indicating it should simply return raw tuples from the cursor. This method is useful when you either do not want or do not need full model instances.

  `dicts`()

    Return type: | `RawQuery`

    Flag this query indicating it should simply return raw dicts from the cursor. This method is useful when you either do not want or do not need full model instances.

  `execute`()

    Return type: | a `QueryResultWrapper` for iterating over the result set. The results are instances of the given model.

    Performs the query

`prefetch`(sq, *subqueries)

  Parameters: | sq – `SelectQuery` instance subqueries – one or more `SelectQuery` instances to prefetch for `sq`. You can also pass models, but they will be converted into SelectQueries.
  Return type: | `SelectQuery` with related instances pre-populated

  Pre-fetch the appropriate instances from the subqueries and apply them to their corresponding parent row in the outer query. This function will eagerly load the related instances specified in the subqueries. This is a technique used to save doing O(n) queries for n rows, and rather is O(k) queries for k subqueries.

  For example, consider you have a list of users and want to display all their tweets:

      # let's impost some small restrictions on our queries
      users = User.select().where(User.active == True)
      tweets = Tweet.select().where(Tweet.published == True)

      # this will perform 2 queries
      users_pf = prefetch(users, tweets)

      # now we can:
      for user in users_pf:
          print user.username
          for tweet in user.tweets_prefetch:
              print '- ', tweet.content

  You can prefetch an arbitrary number of items. For instance, suppose we have a photo site, User -> Photo -> (Comments, Tags). That is, users can post photos, and these photos can have tags and comments on them. If we wanted to fetch a list of users, all their photos, and all the comments and tags on the photos:

      users = User.select()
      published_photos = Photo.select().where(Photo.published == True)
      published_comments = Comment.select().where(
          (Comment.is_spam == False) &
          (Comment.num_flags < 3))

      # note that we are just passing the Tag model -- it will be converted
      # to a query automatically
      users_pf = prefetch(users, published_photos, published_comments, Tag)

      # now we can iterate users, photos, and comments/tags
      for user in users_pf:
          for photo in user.photo_set_prefetch:
              for comment in photo.comment_set_prefetch:
                  # ...
              for tag in photo.tag_set_prefetch:
                  # ...

  Note

  Subqueries must be related by foreign key and can be arbitrarily deep

  Warning

  `prefetch()` can use up lots of RAM when the result set is large, and will not warn you if you are doing something dangerous, so it is up to you to know when to use it. Additionally, because of the semantics of subquerying, there may be some cases when prefetch does not act as you expect (for instnace, when applying a `LIMIT` to subqueries, but there may be others) – please report anything you think is a bug to github.

## Database and its subclasses

class `Database`(database[, threadlocals=False[, autocommit=True[, fields=None[, ops=None[, **connect_kwargs]]]]])

  Parameters: | database – the name of the database (or filename if using sqlite) threadlocals – whether to store connections in a threadlocal autocommit – automatically commit every query executed by calling `execute()` fields (dict) – a mapping of `db_field` to database column type, e.g. ‘string’ => ‘varchar’ ops (dict) – a mapping of operations understood by the querycompiler to expressions connect_kwargs – any arbitrary parameters to pass to the database driver when connecting

  Note

  if your database name is not known when the class is declared, you can pass `None` in as the database name which will mark the database as “deferred” and any attempt to connect while in this state will raise an exception. To initialize your database, call the `Database.init()` method with the database name

  A high-level api for working with the supported database engines. `Database` provides a wrapper around some of the functions performed by the `Adapter`, in addition providing support for:

  - execution of SQL queries
  - creating and dropping tables and indexes
  `commit_select = False`

    Whether to issue a commit after executing a select query. With some engines can prevent implicit transactions from piling up.

  `compiler_class = QueryCompiler`

    A class suitable for compiling queries

  `field_overrides = {}`

    A mapping of field types to database column types, e.g. `{'primary_key': 'SERIAL'}`

  `for_update = False`

    Whether the given backend supports selecting rows for update

  `interpolation = '?'`

    The string used by the driver to interpolate query parameters

  `op_overrides = {}`

    A mapping of operation codes to string operations, e.g. `{OP_LIKE: 'LIKE BINARY'}`

  `quote_char = '"'`

    The string used by the driver to quote names

  `reserved_tables = []`

    Table names that are reserved by the backend – if encountered in the application a warning will be issued.

  `sequences = False`

    Whether the given backend supports sequences

  `subquery_delete_same_table = True`

    Whether the given backend supports deleting rows using a subquery that selects from the same table

  `init`(database[, **connect_kwargs])

    If the database was instantiated with `database=None`, the database is said to be in a ‘deferred’ state (see notes) – if this is the case, you can initialize it at any time by calling the `init` method.

    Parameters: | database – the name of the database (or filename if using sqlite) connect_kwargs – any arbitrary parameters to pass to the database driver when connecting

  `connect`()

    Establishes a connection to the database

    Note

    If you initialized with `threadlocals=True`, then this will store the connection inside a threadlocal, ensuring that connections are not shared across threads.

  `close`()

    Closes the connection to the database (if one is open)

    Note

    If you initialized with `threadlocals=True`, only a connection local to the calling thread will be closed.

  `get_conn`()

    Return type: | a connection to the database, creates one if does not exist

  `get_cursor`()

    Return type: | a cursor for executing queries

  `last_insert_id`(cursor, model)

    Parameters: | cursor – the database cursor used to perform the insert query model – the model class that was just created
    Return type: | the primary key of the most recently inserted instance

  `rows_affected`(cursor)

    Return type: | number of rows affected by the last query

  `compiler`()

    Return type: | an instance of `QueryCompiler` using the field and op overrides specified.

  `execute_sql`(sql[, params=None[, require_commit=True]])

    Parameters: | sql – a string sql query params – a list or tuple of parameters to interpolate

    Note

    You can configure whether queries will automatically commit by using the `set_autocommit()` and `Database.get_autocommit()` methods.

  `begin`()

    Initiate a new transaction. By default not implemented as this is not part of the DB-API 2.0, but provided for API compatibility.

  `commit`()

    Call `commit()` on the active connection, committing the current transaction

  `rollback`()

    Call `rollback()` on the active connection, rolling back the current transaction

  `set_autocommit`(autocommit)

    Parameters: | autocommit – a boolean value indicating whether to turn on/off autocommit for the current connection

  `get_autocommit`()

    Return type: | a boolean value indicating whether autocommit is on for the current connection

  `get_tables`()

    Return type: | a list of table names in the database

    Warning

    Not implemented – implementations exist in subclasses

  `get_indexes_for_table`(table)

    Parameters: | table – the name of table to introspect
    Return type: | a list of `(index_name, is_unique)` tuples

    Warning

    Not implemented – implementations exist in subclasses

  `sequence_exists`(sequence_name)

    Rtype boolean: |

    Warning

    Not implemented – implementations exist in subclasses

  `create_table`(model_class)

    Parameters: | model_class – `Model` class to create table for

  `create_index`(model_class, fields[, unique=False])

    Parameters: | model_class – `Model` table on which to create index fields – field(s) to create index on (either field instances or field names) unique – whether the index should enforce uniqueness

  `create_foreign_key`(model_class, field)

    Parameters: | model_class – `Model` table on which to create foreign key index / constraint field – `Field` object

  `create_sequence`(sequence_name)

    Parameters: | sequence_name – name of sequence to create

    Note

    only works with database engines that support sequences

  `drop_table`(model_class[, fail_silently=False])

    Parameters: | model_class – `Model` table to drop fail_silently – if `True`, query will add a `IF EXISTS` clause

    Note

    Cascading drop tables are not supported at this time, so if a constraint exists that prevents a table being dropped, you will need to handle that in application logic.

  `drop_sequence`(sequence_name)

    Parameters: | sequence_name – name of sequence to drop

    Note

    only works with database engines that support sequences

  `transaction`()

    Return a context manager that executes statements in a transaction. If an error is raised inside the context manager, the transaction will be rolled back, otherwise statements are committed when exiting.

        # delete a blog instance and all its associated entries, but
        # do so within a transaction
        with database.transaction():
            blog.delete_instance(recursive=True)

  `commit_on_success`(func)

    Decorator that wraps the given function in a single transaction, which, upon success will be committed. If an error is raised inside the function, the transaction will be rolled back and the error will be re-raised.

    Parameters: | func – function to decorate

        @database.commit_on_success
        def transfer_money(from_acct, to_acct, amt):
            from_acct.charge(amt)
            to_acct.pay(amt)
            return amt

  classmethod `register_fields`(fields)

    Register a mapping of field overrides for the database class. Used to register custom fields or override the defaults.

    Parameters: | fields (dict) – A mapping of `db_field` to column type

  classmethod `register_ops`(ops)

    Register a mapping of operations understood by the QueryCompiler to their SQL equivalent, e.g. `{OP_EQ: '='}`. Used to extend the types of field comparisons.

    Parameters: | fields (dict) – A mapping of `db_field` to column type

  `extract_date`(date_part, date_field)

    Return an expression suitable for extracting a date part from a date field. For instance, extract the year from a `DateTimeField`.

    Parameters: | date_part (str) – The date part attribute to retrieve. Valid options are: “year”, “month”, “day”, “hour”, “minute” and “second”. date_field (Field) – field instance storing a datetime, date or time.
    Return type: | an expression object.

class `SqliteDatabase`(Database)

  `Database` subclass that communicates to the “sqlite3” driver

class `MySQLDatabase`(Database)

  `Database` subclass that communicates to the “MySQLdb” driver

class `PostgresqlDatabase`(Database)

  `Database` subclass that communicates to the “psycopg2” driver

## Misc

class `fn`

  A helper class that will convert arbitrary function calls to SQL function calls.

  To express functions in peewee, use the `fn` object. The way it works is anything to the right of the “dot” operator will be treated as a function. You can pass that function arbitrary parameters which can be other valid expressions.

  For example:

  Peewee expression | Equivalent SQL
  --- | ---
  `fn.Count(Tweet.id).alias('count')` | `Count(t1."id") AS count`
  `fn.Lower(fn.Substr(User.username, 1, 1))` | `Lower(Substr(t1."username", 1, 1))`
  `fn.Rand().alias('random')` | `Rand() AS random`
  `fn.Stddev(Employee.salary).alias('sdv')` | `Stddev(t1."salary") AS sdv`

### Navigation

- index
- next |
- previous |
- peewee 2.1.3 documentation »