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 to Database.connection()
• 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() and Database.drop_tables(), as well as Model.create_table() and Model.drop_table() all default to safe=True (create if not exists, drop if exists).
• connect_kwargs attribute has been renamed to connect_params

Model Meta options

• db_table has changed to table_name
• db_table_func has changed to table_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

• Accessing raw model data is now done using __data__ instead of _data

Fields

• db_column has changed to column_name
• db_field class attribute changed to field_type (used if you are implementing custom field subclasses)
• model_class attribute has changed to model
• PrimaryKeyField has been renamed to AutoField
• ForeignKeyField constructor has the following changes: * rel_model has changed to model * to_field has changed to field * related_name has changed to backref
• ManyToManyField is now included in the main peewee.py module
• Removed the extension fields PasswordField, PickledField and AESEncryptedField.

Querying

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 it’s relations. In practice, the complexity of the code and it’s 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 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.

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 (replaces extension_options) - arbitrary options for the virtual table that appear after columns and arguments.
• 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)

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 Extension

The virtual-table implementation from sqlite-vtfunc has been folded into the peewee codebase.

• 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.
• Support for SQLite online backup API.
• LSMTable implementation to support the lsm1 extension.