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 :py:meth:`Database.connection`
get_cursor()has changed to :py:meth:`Database.cursor`
execution_context()is replaced by simply using the database instance as a context-manager.
- For a connection context without a transaction, use :py:meth:`Database.connection_context`.
- :py:meth:`Database.create_tables` and :py:meth:`Database.drop_tables`, as
well as :py:meth:`Model.create_table` and :py:meth:`Model.drop_table` all
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
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.
- :py:class:`BaseModel` has been renamed to :py:class:`ModelBase`
- 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
- :py:class:`PrimaryKeyField` has been renamed to :py:class:`AutoField`
- :py:class:`ForeignKeyField` constructor has the following changes:
rel_modelhas changed to
to_fieldhas changed to
related_namehas changed to
- :py:class:`ManyToManyField` is 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.
Additionally, :py:meth:`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 :py:func:`prefetch` to achieve the same result.
- :py:class:`Select` query attribute
_selecthas changed to
naive()method is now :py:meth:`~BaseQuery.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.
The :py:func:`Case` helper has moved from the
into the main peewee module.
The :py:meth:`~BaseColumn.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 :py:meth:`_WriteQuery.returning`.
InsertQuery.upsert() method has been replaced by the more general and
flexible :py:meth:`Insert.on_conflict` method.
When using :py:func:`prefetch`, the collected instances will be stored in the
same attribute as the foreign-key's
backref. Previously, you would access
joined instances using
The :py:class:`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 :py:class:`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, :ref:`lower-level API <query-builder>` for constructing queries.
Many SQLite-specific features have been moved from the
peewee, such as:
- User-defined functions, aggregates, collations, and table-functions.
- Loading extensions.
- Specifying pragmas.
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.
- :py:class:`BloomFilter` implementation.
- Incremental :py:class:`Blob` I/O support.
- Support for update, commit and rollback hooks.
- :py:class:`LSMTable` implementation to support the lsm1 extension.