# 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.

  use_in_migrations = True

    If set to True the manager will be serialized into migrations and will thus be available in e.g. RunPython operations.

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: Optional[Union[Expression, Q, str]] = None, return_model: bool = False, using: Optional[str] = None, update_condition: Optional[Union[Expression, Q, str]] = 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: ConflictAction, index_predicate: Optional[Union[Expression, Q, str]] = None, update_condition: Optional[Union[Expression, Q, str]] = 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: Optional[Union[Expression, Q, str]] = None, using: Optional[str] = None, update_condition: Optional[Union[Expression, Q, str]] = 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: Optional[Union[Expression, Q, str]] = None, using: Optional[str] = None, update_condition: Optional[Union[Expression, Q, str]] = 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.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.PostgresModel(*args, **kwargs)

  Base class for for taking advantage of PostgreSQL specific features.

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

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

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

  Base class for creating a model that is a view.

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(*args, **kwargs)

  Inline reference to a HStore key.

  Allows selecting individual keys in annotations.

class psqlextra.expressions.DateTimeEpoch(*args, **kwargs)

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

class psqlextra.expressions.ExcludedCol(*args, **kwargs)

  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.backend.migrations.operations.ApplyState(*args, **kwargs)

  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.PostgresAddDefaultPartition(*args, **kwargs)

  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.PostgresAddHashPartition(*args, **kwargs)

  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(*args, **kwargs)

  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(*args, **kwargs)

  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.PostgresCreateMaterializedViewModel(*args, **kwargs)

  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.PostgresCreatePartitionedModel(*args, **kwargs)

  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.PostgresCreateViewModel(*args, **kwargs)

  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.PostgresDeleteDefaultPartition(*args, **kwargs)

  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(*args, **kwargs)

  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(*args, **kwargs)

  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.PostgresDeleteMaterializedViewModel(*args, **kwargs)

  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.backend.migrations.operations.PostgresDeletePartitionedModel(*args, **kwargs)

  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.PostgresDeleteRangePartition(*args, **kwargs)

  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.PostgresDeleteViewModel(*args, **kwargs)

  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.types.ConflictAction(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

  Possible actions to take on a conflict.

  NOTHING = 'NOTHING'
  UPDATE = 'UPDATE'
  classmethod all() → List[ConflictAction]

class psqlextra.types.PostgresPartitioningMethod(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

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

  HASH = 'hash'
  LIST = 'list'
  RANGE = 'range'

class psqlextra.types.StrEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
  classmethod all() → List[StrEnum]
  classmethod values() → List[str]

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.