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 by bucket_name if it exists or else create a new Bucket DB object by bucket_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 match filters.

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 match filters.

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.drop_db()[source]
deckhand.db.sqlalchemy.api.get_engine()[source]
deckhand.db.sqlalchemy.api.get_session(autocommit=True, expire_on_commit=False)[source]
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 different metadata.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 a metadata.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 is None, 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 is True.
  • unique_only – Return only unique documents if True. Default is True.
  • session – Database session object.
  • filters – Key-value pairs used for filtering out revision documents.
Returns:

All revision documents for revision_id that match the filters, including document revision history if applicable.

Raises:

RevisionNotFound – if the revision was not found.

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.

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.

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

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

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 for revision_id was not found.

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.

deckhand.db.sqlalchemy.api.setup_db(connection_string, create_tables=False)[source]
deckhand.db.sqlalchemy.api.validation_create(revision_id, val_name, val_data, session=None)[source]
deckhand.db.sqlalchemy.api.validation_get_all(revision_id, session=None)[source]
deckhand.db.sqlalchemy.api.validation_get_all_entries(revision_id, val_name=None, session=None)[source]
deckhand.db.sqlalchemy.api.validation_get_entry(revision_id, val_name, entry_id, session=None)[source]