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

Example showing an atomic update:

>>> q = PageView.update(count=PageView.count + 1).where(PageView.url == url)
>>> q.execute() # <-- execute the query
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()
1
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() # <-- execute it

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 expose 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 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() # <-- creates the table for SomeModel
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])

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

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
class_prepared()

Simple hook for Field classes to indicate when the Model class the field exists on has been created.

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'
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'
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'
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 SelectQuery 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)
... )

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 SelectQuery 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.

sql(compiler)
Parameters:compiler – an instance of QueryCompiler
Return type:a 2-tuple containing the appropriate SQL query and a tuple of parameters
execute()

Execute the given query

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:

>>> sq = User.select(
...     User, fn.Count(Tweet.id).alias('count')
... ).join(Tweet).group_by(User).order_by(
...     fn.Count(Tweet.id).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.

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)
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:
  • modelModel 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() # run the query

Example of an atomic update:

>>> atomic_update = UpdateQuery(PageCount, count = PageCount.count + 1).where(PageCount.url == url)
>>> atomic_update.execute() # run the query
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>
execute()
Return type:a QueryResultWrapper for iterating over the result set. The results are instances of the given model.

Performs the query

Database and its subclasses

class Database(database[, threadlocals=False[, autocommit=True[, **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()
  • 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
get_compiler()
Return type:an instance of QueryCompiler using the field and op overrides specified.
execute(query)
Param :a query instance, such as a SelectQuery
Return type:the resulting cursor
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_classModel class to create table for
create_index(model_class, fields[, unique=False])
Parameters:
  • model_classModel 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_classModel table on which to create foreign key index / constraint
  • fieldField 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_classModel 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
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
raw_sql(query)
Parameters:query – a Query instance.
Return type:2-tuple of SQL query and parameters for the given query

Table Of Contents

Previous topic

Databases

Next topic

Playhouse, a collection of addons

This Page