.. Copyright 2015 OpenStack Foundation All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ============================ Glance database architecture ============================ Glance Database Public API ~~~~~~~~~~~~~~~~~~~~~~~~~~ The Glance Database API contains several methods for moving image metadata to and from persistent storage. You can find a list of public methods grouped by category below. Common parameters for image methods ----------------------------------- The following parameters can be applied to all of the image methods below: - ``context`` — corresponds to a glance.context.RequestContext object, which stores the information on how a user accesses the system, as well as additional request information. - ``image_id`` — a string corresponding to the image identifier. - ``memb_id`` — a string corresponding to the member identifier of the image. Image basic methods ------------------- **Image processing methods:** #. ``image_create(context, values)`` — creates a new image record with parameters listed in the *values* dictionary. Returns a dictionary representation of a newly created *glance.db.sqlalchemy.models.Image* object. #. ``image_update(context, image_id, values, purge_props=False, from_state=None)`` — updates the existing image with the identifier *image_id* with the values listed in the *values* dictionary. Returns a dictionary representation of the updated *Image* object. Optional parameters are: - ``purge_props`` — a flag indicating that all the existing properties not listed in the *values['properties']* should be deleted; - ``from_state`` — a string filter indicating that the updated image must be in the specified state. #. ``image_destroy(context, image_id)`` — deletes all database records of an image with the identifier *image_id* (like tags, properties, and members) and sets a 'deleted' status on all the image locations. #. ``image_get(context, image_id, force_show_deleted=False)`` — gets an image with the identifier *image_id* and returns its dictionary representation. The parameter *force_show_deleted* is a flag that indicates to show image info even if it was 'deleted', or its 'pending_delete' statuses. #. ``image_get_all(context, filters=None, marker=None, limit=None, sort_key=None, sort_dir=None, member_status='accepted', is_public=None, admin_as_user=False, return_tag=False)`` — gets all the images that match zero or more filters. Optional parameters are: - ``filters`` — dictionary of filter keys and values. If a 'properties' key is present, it is treated as a dictionary of key/value filters in the attribute of the image properties. - ``marker`` — image id after which a page should start. - ``limit`` — maximum number of images to return. - ``sort_key`` — list of image attributes by which results should be sorted. - ``sort_dir`` — direction in which results should be sorted (asc, desc). - ``member_status`` — only returns shared images that have this membership status. - ``is_public`` — if true, returns only public images. If false, returns only private and shared images. - ``admin_as_user`` — for backwards compatibility. If true, an admin sees the same set of images that would be seen by a regular user. - ``return_tag`` — indicates whether an image entry in the result includes its relevant tag entries. This can improve upper-layer query performance and avoid using separate calls. Image location methods ---------------------- **Image location processing methods:** #. ``image_location_add(context, image_id, location)`` — adds a new location to an image with the identifier *image_id*. This location contains values listed in the dictionary *location*. #. ``image_location_update(context, image_id, location)`` — updates an existing location with the identifier *location['id']* for an image with the identifier *image_id* with values listed in the dictionary *location*. #. ``image_location_delete(context, image_id, location_id, status, delete_time=None)`` — sets a 'deleted' or 'pending_delete' *status* to an existing location record with the identifier *location_id* for an image with the identifier *image_id*. Image property methods ---------------------- .. warning:: There is no public property update method. So if you want to modify it, you have to delete it first and then create a new one. **Image property processing methods:** #. ``image_property_create(context, values)`` — creates a property record with parameters listed in the *values* dictionary for an image with *values['id']*. Returns a dictionary representation of a newly created *ImageProperty* object. #. ``image_property_delete(context, prop_ref, image_ref)`` — deletes an existing property record with a name *prop_ref* for an image with the identifier *image_ref*. Image member methods -------------------- **Methods to handle image memberships:** #. ``image_member_create(context, values)`` — creates a member record with properties listed in the *values* dictionary for an image with *values['id']*. Returns a dictionary representation of a newly created *ImageMember* object. #. ``image_member_update(context, memb_id, values)`` — updates an existing member record with properties listed in the *values* dictionary for an image with *values['id']*. Returns a dictionary representation of an updated member record. #. ``image_member_delete(context, memb_id)`` — deletes an existing member record with *memb_id*. #. ``image_member_find(context, image_id=None, member=None, status=None)`` — returns all members for a given context with optional image identifier (*image_id*), member name (*member*), and member status (*status*) parameters. #. ``image_member_count(context, image_id)`` — returns a number of image members for an image with *image_id*. Image tag methods ----------------- **Methods to process images tags:** #. ``image_tag_set_all(context, image_id, tags)`` — changes all the 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 an empty list. #. ``image_tag_create(context, image_id, value)`` — adds a *value* to tags for an image with *image_id*. Returns the value of a newly created tag. #. ``image_tag_delete(context, image_id, value)`` — removes a *value* from tags for an image with *image_id*. #. ``image_tag_get_all(context, image_id)`` — returns a list of tags for a specific image. Image info methods ------------------ The next two methods inform a user about his or her ability to modify and view an image. The *image* parameter here is a dictionary representation of an *Image* object. #. ``is_image_mutable(context, image)`` — informs a user about the possibility to modify an image with the given context. Returns True if the image is mutable in this context. #. ``is_image_visible(context, image, status=None)`` — informs about the possibility to see the image details with the given context and optionally with a status. Returns True if the image is visible in this context. **Glance database schema** .. figure:: ../images/glance_db.png :figwidth: 100% :align: center :alt: The glance database schema is depicted by 5 tables. The table named Images has the following columns: id: varchar(36); name: varchar(255), nullable; size: bigint(20), nullable; status: varchar(30); is_public: tinyint(1); created_at: datetime; updated_at: datetime, nullable; deleted_at: datetime, nullable; deleted: tinyint(1); disk_format: varchar(20), nullable; container_format: varchar(20), nullable; checksum: varchar(32), nullable; owner: varchar(255), nullable min_disk: int(11); min_ram: int(11); protected: tinyint(1); and virtual_size: bigint(20), nullable;. The table named image_locations has the following columns: id: int(11), primary; image_id: varchar(36), refers to column named id in table Images; value: text; created_at: datetime; updated_at: datetime, nullable; deleted_at: datetime, nullable; deleted: tinyint(1); meta_data: text, nullable; and status: varchar(30);. The table named image_members has the following columns: id: int(11), primary; image_id: varchar(36), refers to column named id in table Images; member: varchar(255); can_share: tinyint(1); created_at: datetime; updated_at: datetime, nullable; deleted_at: datetime, nullable; deleted: tinyint(1); and status: varchar(20;. The table named image_tags has the following columns: id: int(11), primary; image_id: varchar(36), refers to column named id in table Images; value: varchar(255); created_at: datetime; updated_at: datetime, nullable; deleted_at: datetime, nullable; and deleted: tinyint(1);. The table named image_properties has the following columns: id: int(11), primary; image_id: varchar(36), refers to column named id in table Images; name: varchar(255); value: text, nullable; created_at: datetime; updated_at: datetime, nullable; deleted_at: datetime, nullable; and deleted: tinyint(1);. .. centered:: Image 1. Glance images DB schema Glance Database Backends ~~~~~~~~~~~~~~~~~~~~~~~~ Migration Backends ------------------ .. list-plugins:: glance.database.migration_backend :detailed: Metadata Backends ----------------- .. list-plugins:: glance.database.metadata_backend :detailed: