Changes in 3.0
This document describes changes to be aware of when switching from 2.x to 3.x.
I tried to keep changes backwards-compatible as much as possible. In some
places, APIs that have changed will trigger a
get_conn()has changed to
get_cursor()has changed to
execution_context()is replaced by simply using the database instance as a context-manager.
For a connection context without a transaction, use
Database.drop_tables(), as well as
Model.drop_table()all default to
create_tablewill create if not exists,
drop_tablewill drop if exists).
connect_kwargsattribute has been renamed to
initialization parameter for custom field-type definitions has changed from
Model Meta options
db_tablehas changed to
db_table_funchas changed to
order_byhas been removed (used for specifying a default ordering to be applied to SELECT queries).
validate_backrefshas been removed. Back-references are no longer validated.
BaseModelhas been renamed to
Accessing raw model data is now done using
_prepare_instance()Model method has been removed.
sqlall()method, which output the DDL statements to generate a model and its associated indexes, has been removed.
db_columnhas changed to
db_fieldclass attribute changed to
field_type(used if you are implementing custom field subclasses)
model_classattribute has changed to
PrimaryKeyFieldhas been renamed to
ForeignKeyFieldconstructor has the following changes:
rel_modelhas changed to
to_fieldhas changed to
related_namehas changed to
ManyToManyFieldis now included in the main
Removed the extension fields
JOIN_LEFT_OUTER, etc are now
The C extension that contained implementations of the query result wrappers has been removed.
Select.aggregate_rows() has been removed. This helper
was used to de-duplicate left-join queries to give the appearance of efficiency
when iterating a model and its relations. In practice, the complexity of the
code and its somewhat limited usefulness convinced me to scrap it. You can
prefetch() to achieve the same result.
_selecthas changed to
naive()method is now
objects(), which defaults to using the model class as the constructor, but accepts any callable to use as an alternate constructor.
annotate()query method is no longer supported.
Case() helper has moved from the
into the main peewee module.
cast() method is no longer a function, but instead is
a method on all column-like objects.
InsertQuery.return_id_list() method has been replaced by a more general
pattern of using
InsertQuery.upsert() method has been replaced by the more general and
prefetch(), the collected instances will be stored in the
same attribute as the foreign-key’s
backref. Previously, you would access
joined instances using
SQL object, used to create a composable a SQL string, now
expects the second parameter to be a list/tuple of parameters.
The following extensions are no longer included in the
The SQLite extension module’s
VirtualModel class accepts slightly
arguments- used to specify arbitrary arguments appended after any columns being defined on the virtual table. Should be a list of strings.
extension_options) - arbitrary options for the virtual table that appear after columns and
prefix_arguments- a list of strings that should appear before any arguments or columns in the virtual table declaration.
So, when declaring a model for a virtual table, it will be constructed roughly like this:
CREATE VIRTUAL TABLE "table name" USING extension_module ( prefix arguments, field definitions, arguments, options)
The PostgresqlExtDatabase no longer registers the hstore extension by default. To use the hstore extension in 3.0 and onwards, pass register_hstore=True when initializing the database object.
post_init signal has been removed.
The query-builder has been rewritten from the ground-up to be more flexible and powerful. There is now a generic, lower-level API for constructing queries.
Many SQLite-specific features have been moved from the
peewee, such as:
User-defined functions, aggregates, collations, and table-functions.
The virtual-table implementation from sqlite-vtfunc has been folded into the peewee codebase.
Support for SQLite online backup API.
Murmurhash implementation has been corrected.
Couple small quirks in the BM25 ranking code have been addressed.
Numerous user-defined functions for hashing and ranking are now included.
Support for update, commit and rollback hooks.
LSMTableimplementation to support the lsm1 extension.