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.partitioning.PostgresPartitioningManager(configs: List[psqlextra.partitioning.config.PostgresPartitioningConfig])

Helps managing partitions by automatically creating new partitions and deleting old ones according to the configuration.

find_config_for_model(model: psqlextra.models.partitioned.PostgresPartitionedModel) → Optional[psqlextra.partitioning.config.PostgresPartitioningConfig]

Finds the partitioning config for the specified model.

plan(skip_create: bool = False, skip_delete: bool = False, using: Optional[str] = None) → psqlextra.partitioning.plan.PostgresPartitioningPlan

Plans which partitions should be deleted/created.

Parameters
  • skip_create – If set to True, no partitions will be marked for creation, regardless of the configuration.

  • skip_delete – If set to True, no partitions will be marked for deletion, regardless of the configuration.

  • using – Name of the database connection to use.

Returns

A plan describing what partitions would be created and deleted if the plan is applied.

psqlextra.partitioning.partition_by_current_time(model: psqlextra.models.partitioned.PostgresPartitionedModel, count: int, years: Optional[int] = None, months: Optional[int] = None, weeks: Optional[int] = None, days: Optional[int] = None, max_age: Optional[dateutil.relativedelta.relativedelta] = None) → psqlextra.partitioning.config.PostgresPartitioningConfig

Short-hand for generating a partitioning config that partitions the specified model by time.

One specifies one of the years, months, weeks or days parameter to indicate the size of each partition. These parameters cannot be combined.

Parameters
  • count – The amount of partitions to create ahead of the current date/time.

  • years – The amount of years each partition should contain.

  • months – The amount of months each partition should contain.

  • weeks – The amount of weeks each partition should contain.

  • days – The amount of days each partition should contain.

  • max_age

    The maximum age of a partition (calculated from the start of the partition).

    Partitions older than this are deleted when running a delete/cleanup run.

exception psqlextra.partitioning.PostgresPartitioningError

Raised when the partitioning configuration is broken or automatically creating/deleting partitions fails.

class psqlextra.partitioning.PostgresPartitioningPlan(model_plans: List[psqlextra.partitioning.plan.PostgresModelPartitioningPlan])

Describes the partitions that are going to be created/deleted.

apply(using: Optional[str] = None) → None

Applies this plan by creating/deleting all planned partitions.

property creations

Gets a complete flat list of the partitions that are going to be created.

property deletions

Gets a complete flat list of the partitions that are going to be deleted.

print() → None

Prints this plan to the terminal in a readable format.

class psqlextra.partitioning.PostgresModelPartitioningPlan(config: psqlextra.partitioning.config.PostgresPartitioningConfig, creations: List[psqlextra.partitioning.partition.PostgresPartition] = <factory>, deletions: List[psqlextra.partitioning.partition.PostgresPartition] = <factory>)

Describes the partitions that are going to be created/deleted for a particular partitioning config.

A “partitioning config” applies to one model.

apply(using: Optional[str]) → None

Applies this partitioning plan by creating and deleting the planned partitions.

Applying the plan runs in a transaction.

Parameters

using – Name of the database connection to use.

print() → None

Prints this model plan to the terminal in a readable format.

class psqlextra.partitioning.PostgresPartition

Base class for a PostgreSQL table partition.

abstract create(model: psqlextra.models.partitioned.PostgresPartitionedModel, schema_editor: psqlextra.backend.schema.PostgresSchemaEditor, comment: Optional[str] = None) → None

Creates this partition in the database.

deconstruct() → dict

Deconstructs this partition into a dict of attributes/fields.

abstract delete(model: psqlextra.models.partitioned.PostgresPartitionedModel, schema_editor: psqlextra.backend.schema.PostgresSchemaEditor) → None

Deletes this partition from the database.

abstract name() → str

Generates/computes the name for this partition.

class psqlextra.partitioning.PostgresRangePartition(from_values: Any, to_values: Any)

Base class for a PostgreSQL table partition in a range partitioned table.

create(model: psqlextra.models.partitioned.PostgresPartitionedModel, schema_editor: psqlextra.backend.schema.PostgresSchemaEditor, comment: Optional[str] = None) → None

Creates this partition in the database.

deconstruct() → dict

Deconstructs this partition into a dict of attributes/fields.

delete(model: psqlextra.models.partitioned.PostgresPartitionedModel, schema_editor: psqlextra.backend.schema.PostgresSchemaEditor) → None

Deletes this partition from the database.

class psqlextra.partitioning.PostgresTimePartition(size: psqlextra.partitioning.time_partition_size.PostgresTimePartitionSize, start_datetime: datetime.datetime)

Time-based range table partition.

:see:PostgresTimePartitioningStrategy for more info.

deconstruct() → dict

Deconstructs this partition into a dict of attributes/fields.

name() → str

Generates/computes the name for this partition.

class psqlextra.partitioning.PostgresPartitioningStrategy

Base class for implementing a partitioning strategy for a partitioned table.

abstract to_create() → Generator[psqlextra.partitioning.partition.PostgresPartition, None, None]

Generates a list of partitions to be created.

abstract to_delete() → Generator[psqlextra.partitioning.partition.PostgresPartition, None, None]

Generates a list of partitions to be deleted.

class psqlextra.partitioning.PostgresTimePartitioningStrategy(start_datetime: datetime.datetime, size: psqlextra.partitioning.time_partition_size.PostgresTimePartitionSize, count: int, max_age: Optional[dateutil.relativedelta.relativedelta] = None)
class psqlextra.partitioning.PostgresRangePartitioningStrategy

Base class for implementing a partitioning strategy for a range partitioned table.

class psqlextra.partitioning.PostgresCurrentTimePartitioningStrategy(size: psqlextra.partitioning.time_partition_size.PostgresTimePartitionSize, count: int, max_age: Optional[dateutil.relativedelta.relativedelta] = None)

Implments a time based partitioning strategy where each partition contains values for a specific time period.

All buckets will be equal in size and start at the start of the unit. With monthly partitioning, partitions start on the 1st and with weekly partitioning, partitions start on monday.

to_create() → Generator[psqlextra.partitioning.time_partition.PostgresTimePartition, None, None]

Generates a list of partitions to be created.

to_delete() → Generator[psqlextra.partitioning.time_partition.PostgresTimePartition, None, None]

Generates a list of partitions to be deleted.

class psqlextra.partitioning.PostgresPartitioningConfig(model: psqlextra.models.partitioned.PostgresPartitionedModel, strategy: psqlextra.partitioning.strategy.PostgresPartitioningStrategy)

Configuration for partitioning a specific model according to the specified strategy.

class psqlextra.partitioning.PostgresTimePartitionSize(years: Optional[int] = None, months: Optional[int] = None, weeks: Optional[int] = None, days: Optional[int] = None)

Size of a time-based range partition table.

class psqlextra.backend.migrations.operations.ApplyState(state_operation: django.db.migrations.operations.base.Operation)

Takes an abritrary operation and migrates the project state but does not apply the operation to the database.

This is very similar to the :see:RunSQL state_operations parameter. This is useful if you want to tell Django that an operation was applied without actually applying it.

database_backwards(app_label, schema_editor, from_state, to_state)

Perform the mutation on the database schema in the reverse direction - e.g. if this were CreateModel, it would in fact drop the model’s table.

database_forwards(app_label, schema_editor, from_state, to_state)

Perform the mutation on the database schema in the normal (forwards) direction.

deconstruct()

Return a 3-tuple of class import path (or just name if it lives under django.db.migrations), positional arguments, and keyword arguments.

describe()

Output a brief summary of what the action does.

property reversible

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

state_forwards(app_label, state)

Take the state from the previous migration, and mutate it so that it matches what this migration would perform.

class psqlextra.backend.migrations.operations.PostgresAddHashPartition(model_name: str, name: str, modulus: int, remainder: int)

Adds a new hash partition to a :see:PartitionedPostgresModel.

Each partition will hold the rows for which the hash value of the partition key divided by the specified modulus will produce the specified remainder.

database_backwards(app_label, schema_editor, from_state, to_state)

Perform the mutation on the database schema in the reverse direction - e.g. if this were CreateModel, it would in fact drop the model’s table.

database_forwards(app_label, schema_editor, from_state, to_state)

Perform the mutation on the database schema in the normal (forwards) direction.

deconstruct()

Return a 3-tuple of class import path (or just name if it lives under django.db.migrations), positional arguments, and keyword arguments.

describe() → str

Output a brief summary of what the action does.

state_forwards(app_label, state)

Take the state from the previous migration, and mutate it so that it matches what this migration would perform.

class psqlextra.backend.migrations.operations.PostgresAddListPartition(model_name, name, values)

Adds a new list partition to a :see:PartitionedPostgresModel.

database_backwards(app_label, schema_editor, from_state, to_state)

Perform the mutation on the database schema in the reverse direction - e.g. if this were CreateModel, it would in fact drop the model’s table.

database_forwards(app_label, schema_editor, from_state, to_state)

Perform the mutation on the database schema in the normal (forwards) direction.

deconstruct()

Return a 3-tuple of class import path (or just name if it lives under django.db.migrations), positional arguments, and keyword arguments.

describe() → str

Output a brief summary of what the action does.

state_forwards(app_label, state)

Take the state from the previous migration, and mutate it so that it matches what this migration would perform.

class psqlextra.backend.migrations.operations.PostgresAddRangePartition(model_name: str, name: str, from_values, to_values)

Adds a new range partition to a :see:PartitionedPostgresModel.

database_backwards(app_label, schema_editor, from_state, to_state)

Perform the mutation on the database schema in the reverse direction - e.g. if this were CreateModel, it would in fact drop the model’s table.

database_forwards(app_label, schema_editor, from_state, to_state)

Perform the mutation on the database schema in the normal (forwards) direction.

deconstruct()

Return a 3-tuple of class import path (or just name if it lives under django.db.migrations), positional arguments, and keyword arguments.

describe() → str

Output a brief summary of what the action does.

state_forwards(app_label, state)

Take the state from the previous migration, and mutate it so that it matches what this migration would perform.

class psqlextra.backend.migrations.operations.PostgresAddDefaultPartition(model_name: str, name: str)

Adds a new default partition to a :see:PartitionedPostgresModel.

database_backwards(app_label, schema_editor, from_state, to_state)

Perform the mutation on the database schema in the reverse direction - e.g. if this were CreateModel, it would in fact drop the model’s table.

database_forwards(app_label, schema_editor, from_state, to_state)

Perform the mutation on the database schema in the normal (forwards) direction.

describe() → str

Output a brief summary of what the action does.

state_forwards(app_label, state)

Take the state from the previous migration, and mutate it so that it matches what this migration would perform.

class psqlextra.backend.migrations.operations.PostgresDeleteDefaultPartition(model_name: str, name: str)

Deletes a default partition that’s part of a.

:see:PartitionedPostgresModel.

database_backwards(app_label, schema_editor, from_state, to_state)

Perform the mutation on the database schema in the reverse direction - e.g. if this were CreateModel, it would in fact drop the model’s table.

describe() → str

Output a brief summary of what the action does.

class psqlextra.backend.migrations.operations.PostgresDeleteHashPartition(model_name: str, name: str)

Deletes a hash partition that’s part of a.

:see:PartitionedPostgresModel.

database_backwards(app_label, schema_editor, from_state, to_state)

Perform the mutation on the database schema in the reverse direction - e.g. if this were CreateModel, it would in fact drop the model’s table.

describe() → str

Output a brief summary of what the action does.

class psqlextra.backend.migrations.operations.PostgresDeleteListPartition(model_name: str, name: str)

Deletes a list partition that’s part of a.

:see:PartitionedPostgresModel.

database_backwards(app_label, schema_editor, from_state, to_state)

Perform the mutation on the database schema in the reverse direction - e.g. if this were CreateModel, it would in fact drop the model’s table.

describe() → str

Output a brief summary of what the action does.

class psqlextra.backend.migrations.operations.PostgresDeleteRangePartition(model_name: str, name: str)

Deletes a range partition that’s part of a.

:see:PartitionedPostgresModel.

database_backwards(app_label, schema_editor, from_state, to_state)

Perform the mutation on the database schema in the reverse direction - e.g. if this were CreateModel, it would in fact drop the model’s table.

describe() → str

Output a brief summary of what the action does.

class psqlextra.backend.migrations.operations.PostgresCreatePartitionedModel(name, fields, options=None, partitioning_options={}, bases=None, managers=None)

Creates the model as a native PostgreSQL 11.x partitioned table.

database_backwards(app_label, schema_editor, from_state, to_state)

Apply this migration operation backwards.

database_forwards(app_label, schema_editor, from_state, to_state)

Apply this migration operation forwards.

deconstruct()

Return a 3-tuple of class import path (or just name if it lives under django.db.migrations), positional arguments, and keyword arguments.

describe()

Gets a human readable text describing this migration.

reduce(*args, **kwargs)

Return either a list of operations the actual operation should be replaced with or a boolean that indicates whether or not the specified operation can be optimized across.

state_forwards(app_label, state)

Take the state from the previous migration, and mutate it so that it matches what this migration would perform.

class psqlextra.backend.migrations.operations.PostgresDeletePartitionedModel(name)

Deletes the specified partitioned model.

database_backwards(app_label, schema_editor, from_state, to_state)

Apply this migration operation backwards.

database_forwards(app_label, schema_editor, from_state, to_state)

Apply this migration operation forwards.

describe()

Gets a human readable text describing this migration.

class psqlextra.backend.migrations.operations.PostgresCreateViewModel(name, fields, options=None, view_options={}, bases=None, managers=None)

Creates the model as a native PostgreSQL 11.x view.

database_backwards(app_label, schema_editor, from_state, to_state)

Apply this migration operation backwards.

database_forwards(app_label, schema_editor, from_state, to_state)

Apply this migration operation forwards.

deconstruct()

Return a 3-tuple of class import path (or just name if it lives under django.db.migrations), positional arguments, and keyword arguments.

describe()

Gets a human readable text describing this migration.

state_forwards(app_label, state)

Take the state from the previous migration, and mutate it so that it matches what this migration would perform.

class psqlextra.backend.migrations.operations.PostgresCreateMaterializedViewModel(name, fields, options=None, view_options={}, bases=None, managers=None)

Creates the model as a native PostgreSQL 11.x materialzed view.

database_backwards(app_label, schema_editor, from_state, to_state)

Apply this migration operation backwards.

database_forwards(app_label, schema_editor, from_state, to_state)

Apply this migration operation forwards.

deconstruct()

Return a 3-tuple of class import path (or just name if it lives under django.db.migrations), positional arguments, and keyword arguments.

describe()

Gets a human readable text describing this migration.

state_forwards(app_label, state)

Take the state from the previous migration, and mutate it so that it matches what this migration would perform.

class psqlextra.backend.migrations.operations.PostgresDeleteViewModel(name)

Deletes the specified view model.

database_backwards(app_label, schema_editor, from_state, to_state)

Apply this migration operation backwards.

database_forwards(app_label, schema_editor, from_state, to_state)

Apply this migration operation forwards.

describe()

Gets a human readable text describing this migration.

class psqlextra.backend.migrations.operations.PostgresDeleteMaterializedViewModel(name)

Deletes the specified materialized view model.

database_backwards(app_label, schema_editor, from_state, to_state)

Apply this migration operation backwards.

database_forwards(app_label, schema_editor, from_state, to_state)

Apply this migration operation forwards.

describe()

Gets a human readable text describing this migration.

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.