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()
• get_cursor() has changed to Database.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() and Database.drop_tables(), as well as Model.create_table() and Model.drop_table() all default to safe=True (create_table will create if not exists, drop_table will drop if exists).
• connect_kwargs attribute has been renamed to connect_params
• initialization parameter for custom field-type definitions has changed from fields to field_types.

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

• BaseModel has been renamed to ModelBase
• 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 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

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 now objects(), 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 (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)

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.