openstack/glance
Code Issues Proposed changes

Glance database architecture section

Browse Source 
Adds a database architecture description section
to the Glance Developer guide.

Change-Id: Ice951ecc344a1172d5bffc4f5d0dc329b75e9483
Co-Authored-By: Mike Fedosin <mfedosin@mirantis.com>
Co-Authored-By: Olena Logvinova <ologvinova@mirantis.com>
This commit is contained in:
Olena Logvinova 2015-03-14 16:27:51 +02:00
parent b98c33002a
commit 351e5f1ad7
4 changed files with 408 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

190
doc/source/database_architecture.rst Normal file
View File

@ -0,0 +1,190 @@
..
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
~~~~~~~~~~~~~~~~~~~~~~~~~~
Glance DB API contains several methods to process information from
and to a persistent storage. Below you can find a list of public
methods grouped by categories.
Common parameters for image methods
-----------------------------------
The following parameters can be applied to all the below image methods:
- ``context`` corresponds to a value with 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 an identifier
*image_id* with values listed in the *values* dictionary. Returns a
dictionary representation of a newly created *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 the database
record of an image with an identifier *image_id*, like tags,
properties, and members, and sets a ‘deleted’ status to all the
image locations.
#. ``image_get(context, image_id, force_show_deleted=False)`` -
gets an image with an identifier *image_id* and returns its
dictionary representation. A 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`` - dict of filter keys and values. If a 'properties'
key is present, it is treated as a dict 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`` - directions 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, admin
receives an equivalent set of images that he would see if he was
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 prevent using separated calls.
Image location methods
----------------------
**Image location processing methods:**
#. ``image_location_add(context, image_id, location)`` -
adds a new location to an image with an identifier image_id. This
location contains values listed in the dictionary *location*.
#. ``image_location_update(context, image_id, location)`` - updates
an existing location with an identifier *location[‘id’]*
for an image with an 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 an identifier
*location_id* for an image with an 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
an 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 ability to modify
and view an image. *image* param 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 a given context.
Returns True if the image is mutable in this context.
#. ``is_image_visible(context, image, status=None)`` - informs about
the possibility to observe the image details with a 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: Glance images DB schema
.. centered:: Image 1. Glance images DB schema

BIN
doc/source/images/glance_db.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 106 KiB

217
doc/source/images_src/glance_db.graphml Normal file
View File

@ -0,0 +1,217 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:y="http://www.yworks.com/xml/graphml" xmlns:yed="http://www.yworks.com/xml/yed/3" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://www.yworks.com/xml/schema/graphml/1.1/ygraphml.xsd">
<!--Created by yEd 3.14-->
<key attr.name="Description" attr.type="string" for="graph" id="d0"/>
<key for="port" id="d1" yfiles.type="portgraphics"/>
<key for="port" id="d2" yfiles.type="portgeometry"/>
<key for="port" id="d3" yfiles.type="portuserdata"/>
<key attr.name="url" attr.type="string" for="node" id="d4"/>
<key attr.name="description" attr.type="string" for="node" id="d5"/>
<key for="node" id="d6" yfiles.type="nodegraphics"/>
<key for="graphml" id="d7" yfiles.type="resources"/>
<key attr.name="url" attr.type="string" for="edge" id="d8"/>
<key attr.name="description" attr.type="string" for="edge" id="d9"/>
<key for="edge" id="d10" yfiles.type="edgegraphics"/>
<graph edgedefault="directed" id="G">
<data key="d0"/>
<node id="n0">
<data key="d6">
<y:GenericNode configuration="com.yworks.entityRelationship.big_entity">
<y:Geometry height="278.0" width="252.0" x="1659.671875" y="40.32376155433313"/>
<y:Fill color="#E8EEF7" color2="#B7C9E3" transparent="false"/>
<y:BorderStyle color="#000000" type="line" width="1.0"/>
<y:NodeLabel alignment="center" autoSizePolicy="content" backgroundColor="#B7C9E3" configuration="com.yworks.entityRelationship.label.name" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasLineColor="false" height="17.96875" modelName="internal" modelPosition="t" textColor="#000000" visible="true" width="47.833984375" x="102.0830078125" y="4.0">Images</y:NodeLabel>
<y:NodeLabel alignment="left" autoSizePolicy="content" configuration="com.yworks.entityRelationship.label.attributes" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="241.46875" modelName="custom" textColor="#000000" visible="true" width="240.671875" x="2.0" y="29.96875">id: varchar(36), primary
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)
virtual_size: bigint(20), nullable<y:LabelModel>
<y:ErdAttributesNodeLabelModel/>
</y:LabelModel>
<y:ModelParameter>
<y:ErdAttributesNodeLabelModelParameter/>
</y:ModelParameter>
</y:NodeLabel>
<y:StyleProperties>
<y:Property class="java.lang.Boolean" name="y.view.ShadowNodePainter.SHADOW_PAINTING" value="true"/>
</y:StyleProperties>
</y:GenericNode>
</data>
</node>
<node id="n1">
<data key="d6">
<y:GenericNode configuration="com.yworks.entityRelationship.big_entity">
<y:Geometry height="168.0" width="193.0" x="1382.671875" y="29.5"/>
<y:Fill color="#E8EEF7" color2="#B7C9E3" transparent="false"/>
<y:BorderStyle color="#000000" type="line" width="1.0"/>
<y:NodeLabel alignment="center" autoSizePolicy="content" backgroundColor="#B7C9E3" configuration="com.yworks.entityRelationship.label.name" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasLineColor="false" height="17.96875" modelName="internal" modelPosition="t" textColor="#000000" visible="true" width="101.2421875" x="45.87890625" y="4.0">image_locations</y:NodeLabel>
<y:NodeLabel alignment="right" autoSizePolicy="content" configuration="com.yworks.entityRelationship.label.attributes" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="129.71875" modelName="custom" textColor="#000000" visible="true" width="189.1796875" x="2.0" y="29.96875">id: int(11), primary
image_id: varchar(36)
value: text
created_at: datetime
updated_at: datetime, nullable
deleted_at: datetime, nullable
deleted: tinyint(1)
meta_data: text, nullable
status: varchar(30)<y:LabelModel>
<y:ErdAttributesNodeLabelModel/>
</y:LabelModel>
<y:ModelParameter>
<y:ErdAttributesNodeLabelModelParameter/>
</y:ModelParameter>
</y:NodeLabel>
<y:StyleProperties>
<y:Property class="java.lang.Boolean" name="y.view.ShadowNodePainter.SHADOW_PAINTING" value="true"/>
</y:StyleProperties>
</y:GenericNode>
</data>
</node>
<node id="n2">
<data key="d6">
<y:GenericNode configuration="com.yworks.entityRelationship.big_entity">
<y:Geometry height="168.0" width="193.0" x="1382.671875" y="217.5"/>
<y:Fill color="#E8EEF7" color2="#B7C9E3" transparent="false"/>
<y:BorderStyle color="#000000" type="line" width="1.0"/>
<y:NodeLabel alignment="center" autoSizePolicy="content" backgroundColor="#B7C9E3" configuration="com.yworks.entityRelationship.label.name" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasLineColor="false" height="17.96875" modelName="internal" modelPosition="t" textColor="#000000" visible="true" width="104.32421875" x="44.337890625" y="4.0">image_members</y:NodeLabel>
<y:NodeLabel alignment="right" autoSizePolicy="content" configuration="com.yworks.entityRelationship.label.attributes" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="129.71875" modelName="custom" textColor="#000000" visible="true" width="189.1796875" x="2.0" y="29.96875">id: int(11), primary
image_id: varchar(36)
member: varchar(255)
can_share: tiny_int(1)
created_at: datetime
updated_at: datetime, nullable
deleted_at: datetime, nullable
deleted: tinyint(1)
status: varchar(20)<y:LabelModel>
<y:ErdAttributesNodeLabelModel/>
</y:LabelModel>
<y:ModelParameter>
<y:ErdAttributesNodeLabelModelParameter/>
</y:ModelParameter>
</y:NodeLabel>
<y:StyleProperties>
<y:Property class="java.lang.Boolean" name="y.view.ShadowNodePainter.SHADOW_PAINTING" value="true"/>
</y:StyleProperties>
</y:GenericNode>
</data>
</node>
<node id="n3">
<data key="d6">
<y:GenericNode configuration="com.yworks.entityRelationship.big_entity">
<y:Geometry height="151.0" width="202.0" x="1659.671875" y="389.49999999999994"/>
<y:Fill color="#E8EEF7" color2="#B7C9E3" transparent="false"/>
<y:BorderStyle color="#000000" type="line" width="1.0"/>
<y:NodeLabel alignment="center" autoSizePolicy="content" backgroundColor="#B7C9E3" configuration="com.yworks.entityRelationship.label.name" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasLineColor="false" height="17.96875" modelName="internal" modelPosition="t" textColor="#000000" visible="true" width="108.876953125" x="46.5615234375" y="4.0">image_properties</y:NodeLabel>
<y:NodeLabel alignment="left" autoSizePolicy="content" configuration="com.yworks.entityRelationship.label.attributes" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="115.75" modelName="custom" textColor="#000000" visible="true" width="189.1796875" x="2.0" y="29.96875">id: int(11), primary
image_id: varchar(36)
name: varchar(255)
value: text, nullable
created_at: datetime
updated_at: datetime, nullable
deleted_at: datetime, nullable
deleted: tinyint(1)<y:LabelModel>
<y:ErdAttributesNodeLabelModel/>
</y:LabelModel>
<y:ModelParameter>
<y:ErdAttributesNodeLabelModelParameter/>
</y:ModelParameter>
</y:NodeLabel>
<y:StyleProperties>
<y:Property class="java.lang.Boolean" name="y.view.ShadowNodePainter.SHADOW_PAINTING" value="true"/>
</y:StyleProperties>
</y:GenericNode>
</data>
</node>
<node id="n4">
<data key="d6">
<y:GenericNode configuration="com.yworks.entityRelationship.big_entity">
<y:Geometry height="135.0" width="193.0" x="1382.671875" y="405.5"/>
<y:Fill color="#E8EEF7" color2="#B7C9E3" transparent="false"/>
<y:BorderStyle color="#000000" type="line" width="1.0"/>
<y:NodeLabel alignment="center" autoSizePolicy="content" backgroundColor="#B7C9E3" configuration="com.yworks.entityRelationship.label.name" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasLineColor="false" height="17.96875" modelName="internal" modelPosition="t" textColor="#000000" visible="true" width="73.3046875" x="59.84765625" y="4.0">image_tags</y:NodeLabel>
<y:NodeLabel alignment="right" autoSizePolicy="content" configuration="com.yworks.entityRelationship.label.attributes" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="101.78125" modelName="custom" textColor="#000000" visible="true" width="189.1796875" x="2.0" y="29.96875">id: int(11), primary
image_id: varchar(36)
value: varchar(255)
created_at: datetime
updated_at: datetime, nullable
deleted_at: datetime, nullable
deleted: tinyint(1)<y:LabelModel>
<y:ErdAttributesNodeLabelModel/>
</y:LabelModel>
<y:ModelParameter>
<y:ErdAttributesNodeLabelModelParameter/>
</y:ModelParameter>
</y:NodeLabel>
<y:StyleProperties>
<y:Property class="java.lang.Boolean" name="y.view.ShadowNodePainter.SHADOW_PAINTING" value="true"/>
</y:StyleProperties>
</y:GenericNode>
</data>
</node>
<edge id="e0" source="n1" target="n0">
<data key="d10">
<y:PolyLineEdge>
<y:Path sx="96.48096090818854" sy="-30.67623844566687" tx="-109.82812499999955" ty="-96.5"/>
<y:LineStyle color="#000000" type="line" width="1.0"/>
<y:Arrows source="none" target="standard"/>
<y:BendStyle smoothed="false"/>
</y:PolyLineEdge>
</data>
</edge>
<edge id="e1" source="n2" target="n0">
<data key="d10">
<y:PolyLineEdge>
<y:Path sx="96.47411120251581" sy="-30.038120541989258" tx="-125.98882899999853" ty="-96.61516790136467">
<y:Point x="1616.8437500000005" y="271.46187945801074"/>
<y:Point x="1616.8437500000005" y="82.8264639203809"/>
</y:Path>
<y:LineStyle color="#000000" type="line" width="1.0"/>
<y:Arrows source="none" target="standard"/>
<y:BendStyle smoothed="false"/>
</y:PolyLineEdge>
</data>
</edge>
<edge id="e2" source="n4" target="n0">
<data key="d10">
<y:PolyLineEdge>
<y:Path sx="53.49966990390271" sy="-15.373298128564159" tx="-94.50547499999993" ty="-97.16292541089732">
<y:Point x="1616.8125514447026" y="457.62670187143584"/>
<y:Point x="1616.8125514447026" y="440.9728874438656"/>
<y:Point x="1616.8125514447026" y="83.0975848659289"/>
<y:Point x="1657.7996210822898" y="82.82736888828667"/>
</y:Path>
<y:LineStyle color="#000000" type="line" width="1.0"/>
<y:Arrows source="none" target="standard"/>
<y:BendStyle smoothed="false"/>
</y:PolyLineEdge>
</data>
</edge>
<edge id="e3" source="n3" target="n0">
<data key="d10">
<y:PolyLineEdge>
<y:Path sx="-101.00459041858676" sy="-23.86462912373645" tx="-56.1665950000006" ty="-97.09176155433317">
<y:Point x="1616.8288299295962" y="441.1353708762635"/>
<y:Point x="1616.8288299295962" y="82.98791424409598"/>
</y:Path>
<y:LineStyle color="#000000" type="line" width="1.0"/>
<y:Arrows source="none" target="standard"/>
<y:BendStyle smoothed="false"/>
</y:PolyLineEdge>
</data>
</edge>
</graph>
<data key="d7">
<y:Resources/>
</data>
</graphml>

1
doc/source/index.rst
View File

@ -51,6 +51,7 @@ Glance Background Concepts
:maxdepth: 1
architecture
database_architecture
identifiers
statuses
formats