deckhand.db.sqlalchemy.api module¶
Defines interface for DB access.
-
deckhand.db.sqlalchemy.api.
bucket_get_all
(session=None, **filters)[source]¶ Return list of all buckets.
Parameters: session – Database session object. Returns: List of dictionary representations of retrieved buckets.
-
deckhand.db.sqlalchemy.api.
bucket_get_or_create
(bucket_name, session=None)[source]¶ Retrieve or create bucket.
Retrieve the
Bucket
DB object bybucket_name
if it exists or else create a newBucket
DB object bybucket_name
.Parameters: - bucket_name – Unique identifier used for creating or retrieving a bucket.
- session – Database session object.
Returns: Dictionary representation of created/retrieved bucket.
-
deckhand.db.sqlalchemy.api.
document_delete
(document, revision_id, bucket, session=None)[source]¶ Delete a document
Creates a new document with the bare minimum information about the document that is to be deleted, and then sets the appropriate deleted fields
Parameters: - document – document object/dict to be deleted
- revision_id – id of the revision where the document is to be deleted
- bucket – bucket object/dict where the document will be deleted from
- session – Database session object.
Returns: dict representation of deleted document
-
deckhand.db.sqlalchemy.api.
document_get
(session=None, raw_dict=False, revision_id=None, **filters)[source]¶ Retrieve the first document for
revision_id
that matchfilters
.Parameters: - session – Database session object.
- raw_dict – Whether to retrieve the exact way the data is stored in
DB if
True
, else the way users expect the data. - revision_id – The ID corresponding to the
Revision
object. If the it is “latest”, then retrieve the latest revision, if one exists. - filters – Dictionary attributes (including nested) used to filter out revision documents.
Returns: Dictionary representation of retrieved document.
Raises: DocumentNotFound if the document wasn’t found.
-
deckhand.db.sqlalchemy.api.
document_get_all
(session=None, raw_dict=False, revision_id=None, **filters)[source]¶ Retrieve all documents for
revision_id
that matchfilters
.Parameters: - session – Database session object.
- raw_dict – Whether to retrieve the exact way the data is stored in
DB if
True
, else the way users expect the data. - revision_id – The ID corresponding to the
Revision
object. If the it is “latest”, then retrieve the latest revision, if one exists. - filters – Dictionary attributes (including nested) used to filter out revision documents.
Returns: Dictionary representation of each retrieved document.
-
deckhand.db.sqlalchemy.api.
documents_create
(bucket_name, documents, session=None)[source]¶ Create a set of documents and associated bucket.
If no changes are detected, a new revision will not be created. This allows services to periodically re-register their schemas without creating unnecessary revisions.
Parameters: - bucket_name – The name of the bucket with which to associate created documents.
- documents – List of documents to be created.
- session – Database session object.
Returns: List of created documents in dictionary format.
Raises: DocumentExists – If the document already exists in the DB for any bucket.
-
deckhand.db.sqlalchemy.api.
documents_delete_from_buckets_list
(bucket_names, session=None)[source]¶ Delete all documents in the provided list of buckets
Parameters: - bucket_names – list of bucket names for which the associated buckets and their documents need to be deleted.
- session – Database session object.
Returns: A new model.Revisions object after all the documents have been deleted.
-
deckhand.db.sqlalchemy.api.
raw_query
(query, **kwargs)[source]¶ Execute a raw query against the database.
-
deckhand.db.sqlalchemy.api.
require_revision_exists
(f)[source]¶ Decorator to require the specified revision to exist.
Requires the wrapped function to use revision_id as the first argument. If revision_id is not provided, then the check is not performed.
-
deckhand.db.sqlalchemy.api.
require_unique_document_schema
(schema=None)[source]¶ Decorator to enforce only one singleton document exists in the system.
An example of a singleton document is a
LayeringPolicy
document.Only one singleton document can exist within the system at any time. It is an error to attempt to insert a new document with the same
schema
if it has a differentmetadata.name
than the existing document.A singleton document that already exists can be updated, if the document that is passed in has the same name/schema as the existing one.
The existing singleton document can be replaced by first deleting it and only then creating a new one.
Raises: SingletonDocumentConflict – if a singleton document in the system already exists and any of the documents to be created has the same schema
but has ametadata.name
that differs from the one already registered.
-
deckhand.db.sqlalchemy.api.
revision_create
(session=None)[source]¶ Create a revision.
Parameters: session – Database session object. Returns: Dictionary representation of created revision.
-
deckhand.db.sqlalchemy.api.
revision_delete_all
()[source]¶ Delete all revisions and resets primary key index back to 1 for each table in the database.
Warning
Effectively purges all data from database.
Parameters: session – Database session object. Returns: None
-
deckhand.db.sqlalchemy.api.
revision_documents_get
(revision_id=None, include_history=True, unique_only=True, session=None, **filters)[source]¶ Return the documents that match filters for the specified revision_id.
Parameters: - revision_id – The ID corresponding to the
Revision
object. If the ID isNone
, then retrieve the latest revision, if one exists. - include_history – Return all documents for revision history prior
and up to current revision, if
True
. Default isTrue
. - unique_only – Return only unique documents if
True
. Default isTrue
. - session – Database session object.
- filters – Key-value pairs used for filtering out revision documents.
Returns: All revision documents for
revision_id
that match thefilters
, including document revision history if applicable.Raises: RevisionNotFound – if the revision was not found.
- revision_id – The ID corresponding to the
-
deckhand.db.sqlalchemy.api.
revision_get
(revision_id=None, session=None)[source]¶ Return the specified revision_id.
Parameters: - revision_id – The ID corresponding to the
Revision
object. - session – Database session object.
Returns: Dictionary representation of retrieved revision.
Raises: RevisionNotFound – if the revision was not found.
- revision_id – The ID corresponding to the
-
deckhand.db.sqlalchemy.api.
revision_get_all
(session=None, **filters)[source]¶ Return list of all revisions.
Parameters: session – Database session object. Returns: List of dictionary representations of retrieved revisions.
-
deckhand.db.sqlalchemy.api.
revision_get_latest
(session=None)[source]¶ Return the latest revision.
Parameters: session – Database session object. Returns: Dictionary representation of latest revision.
-
deckhand.db.sqlalchemy.api.
revision_rollback
(revision_id, latest_revision, session=None)[source]¶ Rollback the latest revision to revision specified by
revision_id
.Rolls back the latest revision to the revision specified by
revision_id
thereby creating a new, carbon-copy revision.Parameters: - revision_id – Revision ID to which to rollback.
- latest_revision – Dictionary representation of the latest revision in the system.
Returns: The newly created revision.
-
deckhand.db.sqlalchemy.api.
revision_tag_create
(revision_id, tag, data=None, session=None)[source]¶ Create a revision tag.
If a tag already exists by name
tag
, the request is ignored.Parameters: - revision_id – ID corresponding to
Revision
DB object. - tag – Name of the revision tag.
- data – Dictionary of data to be associated with tag.
- session – Database session object.
Returns: The tag that was created if not already present in the database, else None.
Raises: RevisionTagBadFormat – If data is neither None nor dictionary.
- revision_id – ID corresponding to
-
deckhand.db.sqlalchemy.api.
revision_tag_delete
(revision_id, tag, session=None)[source]¶ Delete a specific tag for a revision.
Parameters: - revision_id – ID corresponding to
Revision
DB object. - tag – Name of the revision tag.
- session – Database session object.
Returns: None
- revision_id – ID corresponding to
-
deckhand.db.sqlalchemy.api.
revision_tag_delete_all
(revision_id, session=None)[source]¶ Delete all tags for a revision.
Parameters: - revision_id – ID corresponding to
Revision
DB object. - session – Database session object.
Returns: None
- revision_id – ID corresponding to
-
deckhand.db.sqlalchemy.api.
revision_tag_get
(revision_id, tag, session=None)[source]¶ Retrieve tag details.
Parameters: - revision_id – ID corresponding to
Revision
DB object. - tag – Name of the revision tag.
- session – Database session object.
Returns: None
Raises: RevisionTagNotFound – If
tag
forrevision_id
was not found.- revision_id – ID corresponding to
-
deckhand.db.sqlalchemy.api.
revision_tag_get_all
(revision_id, session=None)[source]¶ Return list of tags for a revision.
Parameters: - revision_id – ID corresponding to
Revision
DB object. - tag – Name of the revision tag.
- session – Database session object.
Returns: List of tags for
revision_id
, ordered by the tag name by default.- revision_id – ID corresponding to
-
deckhand.db.sqlalchemy.api.
validation_create
(revision_id, val_name, val_data, session=None)[source]¶