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.
-
classmethod
-
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: List[Union[str, Tuple[str, ...]]] = None, required: 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: List[Union[str, Tuple[str, ...]]] = None, required: 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.
-
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.