openstack/glance
Code Issues Proposed changes

Merge "Updated the wording in the database architecture docs."

Browse Source
This commit is contained in:
Jenkins 2016-03-10 12:59:53 +00:00 committed by Gerrit Code Review
commit 36bba726fa
1 changed files with 67 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

135
doc/source/database_architecture.rst
View File

@ -21,18 +21,18 @@ Glance database architecture
Glance Database Public API Glance Database Public API
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
Glance DB API contains several methods to process information from The Glance Database API contains several methods for moving image metadata to
and to a persistent storage. Below you can find a list of public and from persistent storage. You can find a list of public methods grouped by
methods grouped by categories. category below.
Common parameters for image methods Common parameters for image methods
----------------------------------- -----------------------------------
The following parameters can be applied to all the below image methods: The following parameters can be applied to all of the image methods below:
- ``context`` corresponds to a value with glance.context.RequestContext - ``context`` — corresponds to a glance.context.RequestContext
object, which stores the information on how a user accesses object, which stores the information on how a user accesses
the system, as well as additional request information; the system, as well as additional request information.
- ``image_id`` — a string corresponding to the image identifier; - ``image_id`` — a string corresponding to the image identifier.
- ``memb_id`` — a string corresponding to the member identifier - ``memb_id`` — a string corresponding to the member identifier
of the image. of the image.
@ -41,73 +41,72 @@ Image basic methods
**Image processing methods:** **Image processing methods:**
#. ``image_create(context, values)`` - creates a new image record #. ``image_create(context, values)`` — creates a new image record
with parameters listed in the *values* dictionary. Returns a with parameters listed in the *values* dictionary. Returns a
dictionary representation of a newly created *glance.db.sqlalchemy. dictionary representation of a newly created
models.Image* object. *glance.db.sqlalchemy.models.Image* object.
#. ``image_update(context, image_id, values, purge_props=False, #. ``image_update(context, image_id, values, purge_props=False,
from_state=None)`` - updates the existing image with an identifier from_state=None)`` — updates the existing image with the identifier
*image_id* with values listed in the *values* dictionary. Returns a *image_id* with the values listed in the *values* dictionary. Returns a
dictionary representation of a newly created *Image* object. dictionary representation of a newly created *Image* object.
Optional parameters are: Optional parameters are:
- ``purge_props`` - a flag indicating that all the existing - ``purge_props`` — a flag indicating that all the existing
properties not listed in the *values[‘properties’]* should be properties not listed in the *values['properties']* should be
deleted; deleted;
- ``from_state`` - a string filter indicating that the updated - ``from_state`` — a string filter indicating that the updated
image must be in the specified state. image must be in the specified state.
#. ``image_destroy(context, image_id)`` - deletes all the database #. ``image_destroy(context, image_id)`` — deletes all the database
record of an image with an identifier *image_id*, like tags, record of an image with the identifier *image_id* (like tags,
properties, and members, and sets a ‘deleted’ status to all the properties, and members) and sets a 'deleted' status on all the
image locations. image locations.
#. ``image_get(context, image_id, force_show_deleted=False)`` - #. ``image_get(context, image_id, force_show_deleted=False)`` —
gets an image with an identifier *image_id* and returns its gets an image with the identifier *image_id* and returns its
dictionary representation. A parameter *force_show_deleted* is dictionary representation. The parameter *force_show_deleted* is
a flag that indicates to show image info even if it was a flag that indicates to show image info even if it was
‘deleted’, or its ‘pending_delete’ statuses. 'deleted', or its 'pending_delete' statuses.
#. ``image_get_all(context, filters=None, marker=None, limit=None, #. ``image_get_all(context, filters=None, marker=None, limit=None,
sort_key=None, sort_dir=None, member_status='accepted', sort_key=None, sort_dir=None, member_status='accepted',
is_public=None, admin_as_user=False, return_tag=False)`` - gets is_public=None, admin_as_user=False, return_tag=False)`` — gets
all the images that match zero or more filters. all the images that match zero or more filters.
Optional parameters are: Optional parameters are:
- ``filters`` - dict of filter keys and values. If a 'properties' - ``filters`` — dictionary of filter keys and values. If a 'properties'
key is present, it is treated as a dict of key/value filters in key is present, it is treated as a dictionary of key/value filters in
the attribute of the image properties. the attribute of the image properties.
- ``marker`` - image id after which a page should start; - ``marker`` — image id after which a page should start.
- ``limit`` - maximum number of images to return; - ``limit`` — maximum number of images to return.
- ``sort_key`` - list of image attributes by which results should - ``sort_key`` — list of image attributes by which results should
be sorted; be sorted.
- ``sort_dir`` - directions in which results should be sorted - ``sort_dir`` — direction in which results should be sorted
(asc, desc); (asc, desc).
- ``member_status`` - only returns shared images that have this - ``member_status`` — only returns shared images that have this
membership status; membership status.
- ``is_public`` - if true, returns only public images. If false, - ``is_public`` — if true, returns only public images. If false,
returns only private and shared images. returns only private and shared images.
- ``admin_as_user`` - for backwards compatibility. If true, admin - ``admin_as_user`` — for backwards compatibility. If true, an admin
receives an equivalent set of images that he would see if he was sees the same set of images that would be seen by a regular user.
a regular user. - ``return_tag`` — indicates whether an image entry in the result
- ``return_tag`` - indicates whether an image entry in the result
includes its relevant tag entries. This can improve upper-layer includes its relevant tag entries. This can improve upper-layer
query performance and prevent using separated calls. query performance and avoid using separate calls.
Image location methods Image location methods
---------------------- ----------------------
**Image location processing methods:** **Image location processing methods:**
#. ``image_location_add(context, image_id, location)`` - #. ``image_location_add(context, image_id, location)`` —
adds a new location to an image with an identifier image_id. This adds a new location to an image with the identifier *image_id*. This
location contains values listed in the dictionary *location*. location contains values listed in the dictionary *location*.
#. ``image_location_update(context, image_id, location)`` - updates #. ``image_location_update(context, image_id, location)`` — updates
an existing location with an identifier *location[‘id’]* an existing location with the identifier *location['id']*
for an image with an identifier *image_id* with values listed in for an image with the identifier *image_id* with values listed in
the dictionary *location*. the dictionary *location*.
#. ``image_location_delete(context, image_id, location_id, status, #. ``image_location_delete(context, image_id, location_id, status,
delete_time=None)`` - sets a 'deleted' or 'pending_delete' delete_time=None)`` — sets a 'deleted' or 'pending_delete'
*status* to an existing location record with an identifier *status* to an existing location record with the identifier
*location_id* for an image with an identifier *image_id*. *location_id* for an image with the identifier *image_id*.
Image property methods Image property methods
---------------------- ----------------------
@ -118,34 +117,34 @@ Image property methods
**Image property processing methods:** **Image property processing methods:**
#. ``image_property_create(context, values)`` - creates #. ``image_property_create(context, values)`` — creates
a property record with parameters listed in the *values* dictionary a property record with parameters listed in the *values* dictionary
for an image with *values[‘id’]*. Returns a dictionary representation for an image with *values['id']*. Returns a dictionary representation
of a newly created *ImageProperty* object. of a newly created *ImageProperty* object.
#. ``image_property_delete(context, prop_ref, image_ref)`` - deletes an #. ``image_property_delete(context, prop_ref, image_ref)`` — deletes an
existing property record with a name *prop_ref* for an image with existing property record with a name *prop_ref* for an image with
an identifier *image_ref*. the identifier *image_ref*.
Image member methods Image member methods
-------------------- --------------------
**Methods to handle image memberships:** **Methods to handle image memberships:**
#. ``image_member_create(context, values)`` - creates a member record #. ``image_member_create(context, values)`` — creates a member record
with properties listed in the *values* dictionary for an image with properties listed in the *values* dictionary for an image
with *values[‘id’]*. Returns a dictionary representation with *values['id']*. Returns a dictionary representation
of a newly created *ImageMember* object. of a newly created *ImageMember* object.
#. ``image_member_update(context, memb_id, values)`` - updates an #. ``image_member_update(context, memb_id, values)`` — updates an
existing member record with properties listed in the *values* existing member record with properties listed in the *values*
dictionary for an image with *values[‘id’]*. Returns a dictionary dictionary for an image with *values['id']*. Returns a dictionary
representation of an updated member record. representation of an updated member record.
#. ``image_member_delete(context, memb_id)`` - deletes an existing #. ``image_member_delete(context, memb_id)`` — deletes an existing
member record with *memb_id*. member record with *memb_id*.
#. ``image_member_find(context, image_id=None, member=None, status=None)`` #. ``image_member_find(context, image_id=None, member=None, status=None)``
- returns all members for a given context with optional image — returns all members for a given context with optional image
identifier (*image_id*), member name (*member*), and member status identifier (*image_id*), member name (*member*), and member status
(*status*) parameters. (*status*) parameters.
#. ``image_member_count(context, image_id)`` - returns a number of image #. ``image_member_count(context, image_id)`` — returns a number of image
members for an image with *image_id*. members for an image with *image_id*.
Image tag methods Image tag methods
@ -153,30 +152,30 @@ Image tag methods
**Methods to process images tags:** **Methods to process images tags:**
#. ``image_tag_set_all(context, image_id, tags)`` - changes all the #. ``image_tag_set_all(context, image_id, tags)`` — changes all the
existing tags for an image with *image_id* to the tags listed existing tags for an image with *image_id* to the tags listed
in the *tags* param. To remove all tags, a user just should provide in the *tags* param. To remove all tags, a user just should provide
an empty list. an empty list.
#. ``image_tag_create(context, image_id, value)`` - adds a *value* #. ``image_tag_create(context, image_id, value)`` — adds a *value*
to tags for an image with *image_id*. Returns the value of a to tags for an image with *image_id*. Returns the value of a
newly created tag. newly created tag.
#. ``image_tag_delete(context, image_id, value)`` - removes a *value* #. ``image_tag_delete(context, image_id, value)`` — removes a *value*
from tags for an image with *image_id*. from tags for an image with *image_id*.
#. ``image_tag_get_all(context, image_id)`` - returns a list of tags #. ``image_tag_get_all(context, image_id)`` — returns a list of tags
for a specific image. for a specific image.
Image info methods Image info methods
------------------ ------------------
The next two methods inform a user about his ability to modify The next two methods inform a user about his or her ability to modify
and view an image. *image* param here is a dictionary representation and view an image. The *image* parameter here is a dictionary representation
of an *Image* object. of an *Image* object.
#. ``is_image_mutable(context, image)`` - informs a user #. ``is_image_mutable(context, image)`` — informs a user
about the possibility to modify an image with a given context. about the possibility to modify an image with the given context.
Returns True if the image is mutable in this context. Returns True if the image is mutable in this context.
#. ``is_image_visible(context, image, status=None)`` - informs about #. ``is_image_visible(context, image, status=None)`` — informs about
the possibility to observe the image details with a given context the possibility to see the image details with the given context
and optionally with a status. Returns True if the image is visible and optionally with a status. Returns True if the image is visible
in this context. in this context.