Merge pull request #6071 from owncloud/db-documentation

Add some documentation to db_structure.xml

db_structure.xml

@@ -9,6 +9,11 @@
 
 	<table>
 
+		<!--
+		Namespaced Key-Value Store for Application Configuration.
+		 - Keys are namespaced per appid.
+		 - E.g. (core, global_cache_gc_lastrun) -> 1385463286
+		-->
 		<name>*dbprefix*appconfig</name>
 
 		<declaration>
@@ -62,6 +67,13 @@
 
 	<table>
 
+		<!--
+		Bidirectional Map for Storage Names and Storage Ids.
+		 - Assigns each storage name a unique storage id integer.
+		 - Long storage names are hashed.
+		 - E.g.                     local::/tmp/ <-> 2
+		 - E.g. b5db994aa8c6625100e418406c798269 <-> 27
+		-->
 		<name>*dbprefix*storages</name>
 
 		<declaration>
@@ -159,6 +171,12 @@
 
 	<table>
 
+		<!--
+		Bidirectional Map for Mimetypes and Mimetype Id
+		 - Assigns each mimetype (and supertype) a unique mimetype id integer.
+		 - E.g.     application <-> 5
+		 - E.g. application/pdf <-> 6
+		-->
 		<name>*dbprefix*mimetypes</name>
 
 		<declaration>
@@ -195,6 +213,16 @@
 
 	<table>
 
+		<!--
+		Main file table containing one row for each directory and file.
+		 - Assigns a unique integer fileid to each file (and directory)
+		 - Assigns an etag to each file (and directory)
+		 - Caches various file/dir properties such as:
+		  - path (filename, e.g. files/combinatoricslib-2.0_doc.zip)
+		  - path_hash = md5(path)
+		  - name (basename, e.g. combinatoricslib-2.0_doc.zip)
+		  - size (for directories this is the sum of all contained file sizes)
+		-->
 		<name>*dbprefix*filecache</name>
 
 		<declaration>
@@ -208,6 +236,7 @@
 				<length>4</length>
 			</field>
 
+			<!-- Foreign Key storages::numeric_id -->
 			<field>
 				<name>storage</name>
 				<type>integer</type>
@@ -232,6 +261,7 @@
 				<length>32</length>
 			</field>
 
+			<!-- Foreign Key filecache::fileid -->
 			<field>
 				<name>parent</name>
 				<type>integer</type>
@@ -248,6 +278,7 @@
 				<length>250</length>
 			</field>
 
+			<!-- Foreign Key mimetypes::id -->
 			<field>
 				<name>mimetype</name>
 				<type>integer</type>
@@ -256,6 +287,7 @@
 				<length>4</length>
 			</field>
 
+			<!-- Foreign Key mimetypes::id -->
 			<field>
 				<name>mimepart</name>
 				<type>integer</type>
@@ -367,10 +399,15 @@
 
 	<table>
 
+		<!--
+		Maps (fileid, user) to an integer which is a permission bitfield.
+		 - E.g. (4, admin) -> 27
+		-->
 		<name>*dbprefix*permissions</name>
 
 		<declaration>
 
+			<!-- Foreign Key filecache::fileid -->
 			<field>
 				<name>fileid</name>
 				<type>integer</type>
@@ -379,6 +416,7 @@
 				<length>4</length>
 			</field>
 
+			<!-- Foreign Key users::uid -->
 			<field>
 				<name>user</name>
 				<type>text</type>
@@ -413,10 +451,16 @@
 
 	<table>
 
+		<!--
+		Stores which groups have which users as members in an n:m relationship.
+		 - Maps group id (gid) to a set of users (uid)
+		 - Maps user id (uid) to a set of groups (gid) (but without index)
+		-->
 		<name>*dbprefix*group_user</name>
 
 		<declaration>
 
+			<!-- Foreign Key groups::gid -->
 			<field>
 				<name>gid</name>
 				<type>text</type>
@@ -425,6 +469,7 @@
 				<length>64</length>
 			</field>
 
+			<!-- Foreign Key users::uid -->
 			<field>
 				<name>uid</name>
 				<type>text</type>
@@ -453,10 +498,19 @@
 
 	<table>
 
+		<!--
+		Stores which groups have which users as admins in an n:m relationship.
+		 - Maps group id (gid) to a set of users (uid)
+		 - Maps user id (uid) to a set of groups (gid)
+
+		NOTE: This could (very likely) be reduced to a single bit in group_user
+		      instead of repeating varchars gid and uid here
+		-->
 		<name>*dbprefix*group_admin</name>
 
 		<declaration>
 
+			<!-- Foreign Key groups::gid -->
 			<field>
 				<name>gid</name>
 				<type>text</type>
@@ -465,6 +519,7 @@
 				<length>64</length>
 			</field>
 
+			<!-- Foreign Key users::uid -->
 			<field>
 				<name>uid</name>
 				<type>text</type>
@@ -500,6 +555,9 @@
 
 	<table>
 
+		<!--
+		A simple list of groups.
+		-->
 		<name>*dbprefix*groups</name>
 
 		<declaration>
@@ -527,6 +585,9 @@
 
 	<table>
 
+		<!--
+		Locks held by WebDAV clients via OC_Connector_Sabre_Locks.
+		-->
 		<name>*dbprefix*locks</name>
 
 		<declaration>
@@ -541,6 +602,7 @@
 				<length>4</length>
 			</field>
 
+			<!-- Foreign Key users::uid -->
 			<field>
 				<name>userid</name>
 				<type>text</type>
@@ -606,10 +668,16 @@
 
 	<table>
 
+		<!--
+		Namespaced Key-Value Store for User Preferences
+		 - Keys are namespaced per userid and appid.
+		 - E.g. (admin, files, cache_version) -> 5
+		-->
 		<name>*dbprefix*preferences</name>
 
 		<declaration>
 
+			<!-- Foreign Key users::uid -->
 			<field>
 				<name>userid</name>
 				<type>text</type>
@@ -664,6 +732,9 @@
 
 	<table>
 
+		<!--
+		WebDAV properties.
+		-->
 		<name>*dbprefix*properties</name>
 
 		<declaration>
@@ -677,6 +748,7 @@
 				<length>4</length>
 			</field>
 
+			<!-- Foreign Key users::uid -->
 			<field>
 				<name>userid</name>
 				<type>text</type>
@@ -722,6 +794,9 @@
 
 	<table>
 
+		<!--
+		Shares of all types (user-to-user, external-via-link, etc.)
+		-->
 		<name>*dbprefix*share</name>
 
 		<declaration>
@@ -735,6 +810,7 @@
 				<length>4</length>
 			</field>
 
+			<!-- Constant OCP\Share::SHARE_TYPE_* -->
 			<field>
 				<name>share_type</name>
 				<type>integer</type>
@@ -743,6 +819,7 @@
 				<length>1</length>
 			</field>
 
+			<!-- Foreign Key users::uid or NULL -->
 			<field>
 				<name>share_with</name>
 				<type>text</type>
@@ -751,6 +828,7 @@
 				<length>255</length>
 			</field>
 
+			<!-- Foreign Key users::uid -->
 			<field>
 				<name>uid_owner</name>
 				<type>text</type>
@@ -759,6 +837,7 @@
 				<length>255</length>
 			</field>
 
+			<!-- Foreign Key share::id or NULL -->
 			<field>
 				<name>parent</name>
 				<type>integer</type>
@@ -766,6 +845,7 @@
 				<length>4</length>
 			</field>
 
+			<!-- E.g. file or folder -->
 			<field>
 				<name>item_type</name>
 				<type>text</type>
@@ -774,6 +854,7 @@
 				<length>64</length>
 			</field>
 
+			<!-- Foreign Key filecache::fileid -->
 			<field>
 				<name>item_source</name>
 				<type>text</type>
@@ -790,6 +871,7 @@
 				<length>255</length>
 			</field>
 
+			<!-- Foreign Key filecache::fileid -->
 			<field>
 				<name>file_source</name>
 				<type>integer</type>
@@ -805,6 +887,7 @@
 				<length>512</length>
 			</field>
 
+			<!-- Permission bitfield -->
 			<field>
 				<name>permissions</name>
 				<type>integer</type>
@@ -813,6 +896,7 @@
 				<length>1</length>
 			</field>
 
+			<!-- Time of share creation -->
 			<field>
 				<name>stime</name>
 				<type>integer</type>
@@ -821,6 +905,7 @@
 				<length>8</length>
 			</field>
 
+			<!-- Whether the receiver accepted the share, if share_with is set. -->
 			<field>
 				<name>accepted</name>
 				<type>integer</type>
@@ -829,6 +914,7 @@
 				<length>1</length>
 			</field>
 
+			<!-- Time of share expiration -->
 			<field>
 				<name>expiration</name>
 				<type>timestamp</type>
@@ -883,6 +969,10 @@
 
 	<table>
 
+		<!--
+		Scheduled background jobs.
+		See OC\BackgroundJob\JobList.
+		-->
 		<name>*dbprefix*jobs</name>
 
 		<declaration>
@@ -934,6 +1024,9 @@
 
 	<table>
 
+		<!--
+		List of usernames, their display name and login password.
+		-->
 		<name>*dbprefix*users</name>
 
 		<declaration>
@@ -976,6 +1069,9 @@
 
 	<table>
 
+		<!--
+		List of tags (category) + a unique tag id (id) per user (uid) and type.
+		-->
 		<name>*dbprefix*vcategory</name>
 
 		<declaration>
@@ -990,6 +1086,7 @@
 				<length>4</length>
 			</field>
 
+			<!-- Foreign Key users::uid -->
 			<field>
 				<name>uid</name>
 				<type>text</type>
@@ -1043,6 +1140,9 @@
 
 	<table>
 
+		<!--
+		Object-Tag associations per tag type.
+		-->
 		<name>*dbprefix*vcategory_to_object</name>
 
 		<declaration>
@@ -1056,6 +1156,7 @@
 			<length>4</length>
 		</field>
 
+		<!-- Foreign Key vcategory::id -->
 		<field>
 			<name>categoryid</name>
 			<type>integer</type>
@@ -1109,6 +1210,11 @@
 
 	<table>
 
+		<!--
+		Namespaced Key-Value Store for arbitrary data.
+		 - Keys are namespaced per userid and appid.
+		 - E.g. (admin, files, foo) -> bar
+		-->
 		<name>*dbprefix*privatedata</name>
 
 		<declaration>
@@ -1123,6 +1229,7 @@
 			<autoincrement>1</autoincrement>
 		</field>
 
+		<!-- Foreign Key users::uid -->
 		<field>
 			<name>user</name>
 			<type>text</type>