API Reference

class psqlextra.manager.PostgresManager(*args, **kwargs)

Adds support for PostgreSQL specifics.

truncate(cascade: bool = False, using: Optional[str] = None) → None

Truncates this model/table using the TRUNCATE statement.

This DELETES ALL ROWS. No signals will be fired.

See: https://www.postgresql.org/docs/9.1/sql-truncate.html

Parameters

cascade – Whether to delete dependent rows. If set to False, an error will be raised if there are rows in other tables referencing the rows you’re trying to delete.

class psqlextra.query.PostgresQuerySet(model=None, query=None, using=None, hints=None)

Adds support for PostgreSQL specifics.

bulk_insert(rows: List[dict], return_model: bool = False, using: Optional[str] = None)

Creates multiple new records in the database.

This allows specifying custom conflict behavior using .on_conflict(). If no special behavior was specified, this uses the normal Django create(..)

Parameters
  • rows – An iterable of dictionaries, where each dictionary describes the fields to insert.

  • (default (return_model) – False): If model instances should be returned rather than just dicts.

  • using – Name of the database connection to use for this query.

Returns

A list of either the dicts of the rows inserted, including the pk or the models of the rows inserted with defaults for any fields not specified

bulk_upsert(conflict_target: List[Union[str, Tuple[str]]], rows: Iterable[Dict], index_predicate: Union[django.db.models.expressions.Expression, django.db.models.query_utils.Q, str, None] = None, return_model: bool = False, using: Optional[str] = None, update_condition: Union[django.db.models.expressions.Expression, django.db.models.query_utils.Q, str, None] = None)

Creates a set of new records or updates the existing ones with the specified data.

Parameters
  • conflict_target – Fields to pass into the ON CONFLICT clause.

  • rows – Rows to upsert.

  • index_predicate – The index predicate to satisfy an arbiter partial index (i.e. what partial index to use for checking conflicts)

  • (default (return_model) – False): If model instances should be returned rather than just dicts.

  • using – The name of the database connection to use for this query.

  • update_condition – Only update if this SQL expression evaluates to true.

Returns

A list of either the dicts of the rows upserted, including the pk or the models of the rows upserted

insert(using: Optional[str] = None, **fields)

Creates a new record in the database.

This allows specifying custom conflict behavior using .on_conflict(). If no special behavior was specified, this uses the normal Django create(..)

Parameters
  • fields – The fields of the row to create.

  • using – The name of the database connection to use for this query.

Returns

The primary key of the record that was created.

insert_and_get(using: Optional[str] = None, **fields)

Creates a new record in the database and then gets the entire row.

This allows specifying custom conflict behavior using .on_conflict(). If no special behavior was specified, this uses the normal Django create(..)

Parameters
  • fields – The fields of the row to create.

  • using – The name of the database connection to use for this query.

Returns

The model instance representing the row that was created.

on_conflict(fields: List[Union[str, Tuple[str]]], action: psqlextra.types.ConflictAction, index_predicate: Union[django.db.models.expressions.Expression, django.db.models.query_utils.Q, str, None] = None, update_condition: Union[django.db.models.expressions.Expression, django.db.models.query_utils.Q, str, None] = None)

Sets the action to take when conflicts arise when attempting to insert/create a new row.

Parameters
  • fields – The fields the conflicts can occur in.

  • action – The action to take when the conflict occurs.

  • index_predicate – The index predicate to satisfy an arbiter partial index (i.e. what partial index to use for checking conflicts)

  • update_condition – Only update if this SQL expression evaluates to true.

upsert(conflict_target: List[Union[str, Tuple[str]]], fields: dict, index_predicate: Union[django.db.models.expressions.Expression, django.db.models.query_utils.Q, str, None] = None, using: Optional[str] = None, update_condition: Union[django.db.models.expressions.Expression, django.db.models.query_utils.Q, str, None] = None) → int

Creates a new record or updates the existing one with the specified data.

Parameters
  • conflict_target – Fields to pass into the ON CONFLICT clause.

  • fields – Fields to insert/update.

  • index_predicate – The index predicate to satisfy an arbiter partial index (i.e. what partial index to use for checking conflicts)

  • using – The name of the database connection to use for this query.

  • update_condition – Only update if this SQL expression evaluates to true.

Returns

The primary key of the row that was created/updated.

upsert_and_get(conflict_target: List[Union[str, Tuple[str]]], fields: dict, index_predicate: Union[django.db.models.expressions.Expression, django.db.models.query_utils.Q, str, None] = None, using: Optional[str] = None, update_condition: Union[django.db.models.expressions.Expression, django.db.models.query_utils.Q, str, None] = None)

Creates a new record or updates the existing one with the specified data and then gets the row.

Parameters
  • conflict_target – Fields to pass into the ON CONFLICT clause.

  • fields – Fields to insert/update.

  • index_predicate – The index predicate to satisfy an arbiter partial index (i.e. what partial index to use for checking conflicts)

  • using – The name of the database connection to use for this query.

  • update_condition – Only update if this SQL expression evaluates to true.

Returns

The model instance representing the row that was created/updated.

class psqlextra.models.PostgresModel(*args, **kwargs)

Base class for for taking advantage of PostgreSQL specific features.

class psqlextra.models.PostgresViewModel(*args, **kwargs)

Base class for creating a model that is a view.

class psqlextra.models.PostgresMaterializedViewModel(*args, **kwargs)

Base class for creating a model that is a materialized view.

classmethod refresh(concurrently: bool = False, using: Optional[str] = None) → None

Refreshes this materialized view.

Parameters
  • concurrently – Whether to tell PostgreSQL to refresh this materialized view concurrently.

  • using – Optionally, the name of the database connection to use for refreshing the materialized view.

class psqlextra.models.PostgresPartitionedModel(*args, **kwargs)

Base class for taking advantage of PostgreSQL’s 11.x native support for table partitioning.

class psqlextra.fields.HStoreField(*args, uniqueness: Optional[List[Union[str, Tuple[str, ...]]]] = None, required: Optional[List[str]] = None, **kwargs)

Improved version of Django’s :see:HStoreField that adds support for database-level constraints.

Notes

  • For the implementation of uniqueness, see the custom database back-end.

__init__(*args, uniqueness: Optional[List[Union[str, Tuple[str, ...]]]] = None, required: Optional[List[str]] = None, **kwargs)

Initializes a new instance of :see:HStoreField.

Parameters
  • uniqueness – List of keys to enforce as unique. Use tuples to enforce multiple keys together to be unique.

  • required – List of keys that should be enforced as required.

class psqlextra.expressions.HStoreRef(name: str, key: str)

Inline reference to a HStore key.

Allows selecting individual keys in annotations.

class psqlextra.expressions.DateTimeEpoch(name)

Gets the date/time column as a UNIX epoch timestamp.

class psqlextra.expressions.ExcludedCol(name: str)

References a column in PostgreSQL’s special EXCLUDED column, which is used in upserts to refer to the data about to be inserted/updated.

See: https://www.postgresql.org/docs/9.5/sql-insert.html#SQL-ON-CONFLICT

class psqlextra.indexes.UniqueIndex(*expressions, fields=(), name=None, db_tablespace=None, opclasses=(), condition=None, include=None)
class psqlextra.indexes.ConditionalUniqueIndex(condition: str, fields=[], name=None)

Creates a partial unique index based on a given condition.

Useful, for example, if you need unique combination of foreign keys, but you might want to include NULL as a valid value. In that case, you can just use:

>>> class Meta:
>>>    indexes = [
>>>        ConditionalUniqueIndex(fields=['a', 'b', 'c'], condition='"c" IS NOT NULL'),
>>>        ConditionalUniqueIndex(fields=['a', 'b'], condition='"c" IS NULL')
>>>    ]
class psqlextra.indexes.CaseInsensitiveUniqueIndex(*expressions, fields=(), name=None, db_tablespace=None, opclasses=(), condition=None, include=None)
class psqlextra.types.ConflictAction

Possible actions to take on a conflict.

NOTHING = 'NOTHING'
UPDATE = 'UPDATE'
all = <bound method ConflictAction.all of <enum 'ConflictAction'>>
class psqlextra.types.PostgresPartitioningMethod

Methods of partitioning supported by PostgreSQL 11.x native support for table partitioning.

HASH = 'hash'
LIST = 'list'
RANGE = 'range'
class psqlextra.types.StrEnum

An enumeration.

all = <bound method StrEnum.all of <enum 'StrEnum'>>
values = <bound method StrEnum.values of <enum 'StrEnum'>>
psqlextra.util.postgres_manager(model)

Allows you to use the :see:PostgresManager with the specified model instance on the fly.

Parameters

model – The model or model instance to use this on.