Backwards-incompatible

I tried to keep changes backwards-compatible as much as possible. In someplaces, 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 asa context-manager.
• For a connection context without a transaction, useDatabase.connection_context().
• Database.create_tables() and Database.drop_tables(), aswell as Model.create_table() and Model.drop_table() alldefault 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 changedfrom 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 beapplied to SELECT queries).
• validate_backrefs has been removed. Back-references are no longervalidated.

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 modeland 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 areimplementing 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 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 hasbeen removed.

Additionally, Select.aggregate_rows() has been removed. This helperwas used to de-duplicate left-join queries to give the appearance of efficiencywhen iterating a model and its relations. In practice, the complexity of thecode and its somewhat limited usefulness convinced me to scrap it. You caninstead use prefetch() to achieve the same result.

• Select query attribute _select has changed to _returning
• The naive() method is now objects(), which defaultsto using the model class as the constructor, but accepts any callable to useas an alternate constructor.
• The annotate() query method is no longer supported.

The Case() helper has moved from the playhouse.shortcuts moduleinto the main peewee module.

The cast() method is no longer a function, but instead isa method on all column-like objects.

The InsertQuery.return_id_list() method has been replaced by a more generalpattern of using _WriteQuery.returning().

The InsertQuery.upsert() method has been replaced by the more general andflexible Insert.on_conflict() method.

When using prefetch(), the collected instances will be stored in thesame attribute as the foreign-key’s backref. Previously, you would accessjoined instances using (backref)_prefetch.

The SQL object, used to create a composable a SQL string, nowexpects 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 slightlydifferent Meta options:

• arguments - used to specify arbitrary arguments appended after anycolumns being defined on the virtual table. Should be a list of strings.
• extension_module (unchanged)
• options (replaces extension_options) - arbitrary options for thevirtual table that appear after columns and arguments.
• prefix_arguments - a list of strings that should appear before anyarguments or columns in the virtual table declaration.

So, when declaring a model for a virtual table, it will be constructed roughlylike 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 bydefault. To use the hstore extension in 3.0 and onwards, passregister_hstore=True when initializing the database object.

Signals Extension

The post_init signal has been removed.