Changes in 3.0
This document describes changes to be aware of when switching from 2.x to 3.x.
Backwards-incompatible
I tried to keep changes backwards-compatible as much as possible. In some
places, APIs that have changed will trigger a DeprecationWarning
.
Database
get_conn()
has changed toDatabase.connection()
get_cursor()
has changed toDatabase.cursor()
execution_context()
is replaced by simply using the database instance as a context-manager.For a connection context without a transaction, use
Database.connection_context()
.Database.create_tables()
andDatabase.drop_tables()
, as well asModel.create_table()
andModel.drop_table()
all default tosafe=True
(create_table
will create if not exists,drop_table
will drop if exists).connect_kwargs
attribute has been renamed toconnect_params
initialization parameter for custom field-type definitions has changed from
fields
tofield_types
.
Model Meta options
db_table
has changed totable_name
db_table_func
has changed totable_function
order_by
has been removed (used for specifying a default ordering to be applied to SELECT queries).validate_backrefs
has been removed. Back-references are no longer validated.
Models
BaseModel
has been renamed toModelBase
Accessing raw model data is now done using
__data__
instead of_data
The
_prepare_instance()
Model method has been removed.The
sqlall()
method, which output the DDL statements to generate a model and its associated indexes, has been removed.
Fields
db_column
has changed tocolumn_name
db_field
class attribute changed tofield_type
(used if you are implementing custom field subclasses)model_class
attribute has changed tomodel
PrimaryKeyField
has been renamed toAutoField
ForeignKeyField
constructor has the following changes:rel_model
has changed tomodel
to_field
has changed tofield
related_name
has changed tobackref
ManyToManyField
is now included in the mainpeewee.py
moduleRemoved the extension fields
PasswordField
,PickledField
andAESEncryptedField
.
Querying
JOIN_INNER
, JOIN_LEFT_OUTER
, etc are now JOIN.INNER
,
JOIN.LEFT_OUTER
, etc.
The C extension that contained implementations of the query result wrappers has been removed.
Additionally, 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
instead use prefetch()
to achieve the same result.
Select
query attribute_select
has changed to_returning
The
naive()
method is nowobjects()
, which defaults to using the model class as the constructor, but accepts any callable to use as an alternate constructor.The
annotate()
query method is no longer supported.
The Case()
helper has moved from the playhouse.shortcuts
module
into the main peewee module.
The cast()
method is no longer a function, but instead is
a method on all column-like objects.
The InsertQuery.return_id_list()
method has been replaced by a more general
pattern of using _WriteQuery.returning()
.
The InsertQuery.upsert()
method has been replaced by the more general and
flexible Insert.on_conflict()
method.
When using prefetch()
, the collected instances will be stored in the
same attribute as the foreign-key’s backref
. Previously, you would access
joined instances using (backref)_prefetch
.
The SQL
object, used to create a composable a SQL string, now
expects the second parameter to be a list/tuple of parameters.
Removed Extensions
The following extensions are no longer included in the playhouse
:
berkeleydb
csv_utils
djpeewee
gfk
kv
pskel
read_slave
SQLite Extension
The SQLite extension module’s VirtualModel
class accepts slightly
different Meta
options:
arguments
- used to specify arbitrary arguments appended after any columns being defined on the virtual table. Should be a list of strings.extension_module
(unchanged)options
(replacesextension_options
) - arbitrary options for the virtual table that appear after columns andarguments
.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)
Postgresql Extension
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.
Signals Extension
The post_init
signal has been removed.
New stuff
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.
SQLite
Many SQLite-specific features have been moved from the playhouse.sqlite_ext
module into peewee
, such as:
User-defined functions, aggregates, collations, and table-functions.
Loading extensions.
Specifying pragmas.
See the “Using SQLite” section and “SQLite extensions” documents for more details.
SQLite Extension
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.
BloomFilter
implementation.Incremental
Blob
I/O support.Support for update, commit and rollback hooks.
LSMTable
implementation to support the lsm1 extension.