]>
Commit | Line | Data |
---|---|---|
f6a2e156 AW |
1 | .ST "Database Values" |
2 | .PP | |
3 | Each column in the database accepts a fixed type of data. The | |
4 | currently defined basic types, and their representations, are: | |
5 | .IP "integer" | |
6 | A decimal integer in the range \-2**63 to 2**63\-1, inclusive. | |
7 | .IP "real" | |
8 | A floating-point number. | |
9 | .IP "Boolean" | |
10 | True or false, written \fBtrue\fR or \fBfalse\fR, respectively. | |
11 | .IP "string" | |
12 | An arbitrary Unicode string, except that null bytes are not allowed. | |
13 | Quotes are optional for most strings that begin with an English letter | |
14 | or underscore and consist only of letters, underscores, hyphens, and | |
15 | periods. However, \fBtrue\fR and \fBfalse\fR and strings that match | |
16 | the syntax of UUIDs (see below) must be enclosed in double quotes to | |
17 | distinguish them from other basic types. When double quotes are used, | |
18 | the syntax is that of strings in JSON, e.g. backslashes may be used to | |
19 | escape special characters. The empty string must be represented as a | |
20 | pair of double quotes (\fB""\fR). | |
21 | .IP "UUID" | |
22 | Either a universally unique identifier in the style of RFC 4122, | |
23 | e.g. \fBf81d4fae\-7dec\-11d0\-a765\-00a0c91e6bf6\fR, or an \fB@\fIname\fR | |
24 | defined by a \fBget\fR or \fBcreate\fR command within the same \fB\*(PN\fR | |
25 | invocation. | |
26 | .PP | |
27 | Multiple values in a single column may be separated by spaces or a | |
28 | single comma. When multiple values are present, duplicates are not | |
29 | allowed, and order is not important. Conversely, some database | |
30 | columns can have an empty set of values, represented as \fB[]\fR, and | |
31 | square brackets may optionally enclose other non-empty sets or single | |
1ab39058 LR |
32 | values as well. For a column accepting a set of integers, database commands |
33 | accept a range. A range is represented by two integers separated by | |
34 | \fB-\fR. A range is inclusive. A range has a maximum size of 4096 | |
35 | elements. If more elements are needed, they can be specified in seperate | |
36 | ranges. | |
f6a2e156 AW |
37 | .PP |
38 | A few database columns are ``maps'' of key-value pairs, where the key | |
39 | and the value are each some fixed database type. These are specified | |
40 | in the form \fIkey\fB=\fIvalue\fR, where \fIkey\fR and \fIvalue\fR | |
41 | follow the syntax for the column's key type and value type, | |
42 | respectively. When multiple pairs are present (separated by spaces or | |
43 | a comma), duplicate keys are not allowed, and again the order is not | |
44 | important. Duplicate values are allowed. An empty map is represented | |
45 | as \fB{}\fR. Curly braces may optionally enclose non-empty maps as | |
46 | well (but use quotes to prevent the shell from expanding | |
47 | \fBother-config={0=x,1=y}\fR into \fBother-config=0=x | |
48 | other-config=1=y\fR, which may not have the desired effect). | |
49 | . | |
50 | .ST "Database Command Syntax" | |
51 | . | |
52 | .IP "[\fB\-\-if\-exists\fR] [\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBlist \fItable \fR[\fIrecord\fR]..." | |
53 | Lists the data in each specified \fIrecord\fR. If no | |
54 | records are specified, lists all the records in \fItable\fR. | |
55 | .IP | |
56 | If \fB\-\-columns\fR is specified, only the requested columns are | |
57 | listed, in the specified order. Otherwise, all columns are listed, in | |
58 | alphabetical order by column name. | |
59 | .IP | |
60 | Without \fB\-\-if-exists\fR, it is an error if any specified | |
61 | \fIrecord\fR does not exist. With \fB\-\-if-exists\fR, the command | |
62 | ignores any \fIrecord\fR that does not exist, without producing any | |
63 | output. | |
64 | . | |
65 | .IP "[\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBfind \fItable \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..." | |
66 | Lists the data in each record in \fItable\fR whose \fIcolumn\fR equals | |
67 | \fIvalue\fR or, if \fIkey\fR is specified, whose \fIcolumn\fR contains | |
68 | a \fIkey\fR with the specified \fIvalue\fR. The following operators | |
69 | may be used where \fB=\fR is written in the syntax summary: | |
70 | .RS | |
71 | .IP "\fB= != < > <= >=\fR" | |
72 | Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] equals, does not | |
73 | equal, is less than, is greater than, is less than or equal to, or is | |
74 | greater than or equal to \fIvalue\fR, respectively. | |
75 | .IP | |
76 | Consider \fIcolumn\fR[\fB:\fIkey\fR] and \fIvalue\fR as sets of | |
77 | elements. Identical sets are considered equal. Otherwise, if the | |
78 | sets have different numbers of elements, then the set with more | |
79 | elements is considered to be larger. Otherwise, consider a element | |
80 | from each set pairwise, in increasing order within each set. The | |
81 | first pair that differs determines the result. (For a column that | |
82 | contains key-value pairs, first all the keys are compared, and values | |
83 | are considered only if the two sets contain identical keys.) | |
84 | .IP "\fB{=} {!=}\fR" | |
85 | Test for set equality or inequality, respectively. | |
86 | .IP "\fB{<=}\fR" | |
87 | Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] is a subset of | |
88 | \fIvalue\fR. For example, \fBflood-vlans{<=}1,2\fR selects records in | |
89 | which the \fBflood-vlans\fR column is the empty set or contains 1 or 2 | |
90 | or both. | |
91 | .IP "\fB{<}\fR" | |
92 | Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] is a proper | |
93 | subset of \fIvalue\fR. For example, \fBflood-vlans{<}1,2\fR selects | |
94 | records in which the \fBflood-vlans\fR column is the empty set or | |
95 | contains 1 or 2 but not both. | |
96 | .IP "\fB{>=} {>}\fR" | |
97 | Same as \fB{<=}\fR and \fB{<}\fR, respectively, except that the | |
98 | relationship is reversed. For example, \fBflood-vlans{>=}1,2\fR | |
99 | selects records in which the \fBflood-vlans\fR column contains both 1 | |
100 | and 2. | |
101 | .RE | |
102 | .IP | |
103 | For arithmetic operators (\fB= != < > <= >=\fR), when \fIkey\fR is | |
104 | specified but a particular record's \fIcolumn\fR does not contain | |
105 | \fIkey\fR, the record is always omitted from the results. Thus, the | |
106 | condition \fBother-config:mtu!=1500\fR matches records that have a | |
107 | \fBmtu\fR key whose value is not 1500, but not those that lack an | |
108 | \fBmtu\fR key. | |
109 | .IP | |
110 | For the set operators, when \fIkey\fR is specified but a particular | |
111 | record's \fIcolumn\fR does not contain \fIkey\fR, the comparison is | |
112 | done against an empty set. Thus, the condition | |
113 | \fBother-config:mtu{!=}1500\fR matches records that have a \fBmtu\fR | |
114 | key whose value is not 1500 and those that lack an \fBmtu\fR key. | |
115 | .IP | |
116 | Don't forget to escape \fB<\fR or \fB>\fR from interpretation by the | |
117 | shell. | |
118 | .IP | |
119 | If \fB\-\-columns\fR is specified, only the requested columns are | |
120 | listed, in the specified order. Otherwise all columns are listed, in | |
121 | alphabetical order by column name. | |
122 | .IP | |
123 | The UUIDs shown for rows created in the same \fB\*(PN\fR | |
124 | invocation will be wrong. | |
125 | . | |
126 | .IP "[\fB\-\-if\-exists\fR] [\fB\-\-id=@\fIname\fR] \fBget \fItable record \fR[\fIcolumn\fR[\fB:\fIkey\fR]]..." | |
127 | Prints the value of each specified \fIcolumn\fR in the given | |
128 | \fIrecord\fR in \fItable\fR. For map columns, a \fIkey\fR may | |
129 | optionally be specified, in which case the value associated with | |
130 | \fIkey\fR in the column is printed, instead of the entire map. | |
131 | .IP | |
132 | Without \fB\-\-if\-exists\fR, it is an error if \fIrecord\fR does not | |
133 | exist or \fIkey\fR is specified, if \fIkey\fR does not exist in | |
134 | \fIrecord\fR. With \fB\-\-if\-exists\fR, a missing \fIrecord\fR | |
135 | yields no output and a missing \fIkey\fR prints a blank line. | |
136 | .IP | |
137 | If \fB@\fIname\fR is specified, then the UUID for \fIrecord\fR may be | |
138 | referred to by that name later in the same \fB\*(PN\fR | |
139 | invocation in contexts where a UUID is expected. | |
140 | .IP | |
141 | Both \fB\-\-id\fR and the \fIcolumn\fR arguments are optional, but | |
142 | usually at least one or the other should be specified. If both are | |
143 | omitted, then \fBget\fR has no effect except to verify that | |
144 | \fIrecord\fR exists in \fItable\fR. | |
145 | .IP | |
146 | \fB\-\-id\fR and \fB\-\-if\-exists\fR cannot be used together. | |
147 | . | |
148 | .IP "[\fB\-\-if\-exists\fR] \fBset \fItable record column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..." | |
149 | Sets the value of each specified \fIcolumn\fR in the given | |
150 | \fIrecord\fR in \fItable\fR to \fIvalue\fR. For map columns, a | |
151 | \fIkey\fR may optionally be specified, in which case the value | |
152 | associated with \fIkey\fR in that column is changed (or added, if none | |
153 | exists), instead of the entire map. | |
154 | .IP | |
155 | Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not | |
156 | exist. With \fB\-\-if-exists\fR, this command does nothing if | |
157 | \fIrecord\fR does not exist. | |
158 | . | |
159 | .IP "[\fB\-\-if\-exists\fR] \fBadd \fItable record column \fR[\fIkey\fB=\fR]\fIvalue\fR..." | |
160 | Adds the specified value or key-value pair to \fIcolumn\fR in | |
161 | \fIrecord\fR in \fItable\fR. If \fIcolumn\fR is a map, then \fIkey\fR | |
162 | is required, otherwise it is prohibited. If \fIkey\fR already exists | |
163 | in a map column, then the current \fIvalue\fR is not replaced (use the | |
164 | \fBset\fR command to replace an existing value). | |
165 | .IP | |
166 | Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not | |
167 | exist. With \fB\-\-if-exists\fR, this command does nothing if | |
168 | \fIrecord\fR does not exist. | |
169 | . | |
170 | .IP "[\fB\-\-if\-exists\fR] \fBremove \fItable record column \fR\fIvalue\fR..." | |
171 | .IQ "[\fB\-\-if\-exists\fR] \fBremove \fItable record column \fR\fIkey\fR..." | |
172 | .IQ "[\fB\-\-if\-exists\fR] \fBremove \fItable record column \fR\fIkey\fB=\fR\fIvalue\fR..." | |
173 | Removes the specified values or key-value pairs from \fIcolumn\fR in | |
174 | \fIrecord\fR in \fItable\fR. The first form applies to columns that | |
175 | are not maps: each specified \fIvalue\fR is removed from the column. | |
176 | The second and third forms apply to map columns: if only a \fIkey\fR | |
177 | is specified, then any key-value pair with the given \fIkey\fR is | |
178 | removed, regardless of its value; if a \fIvalue\fR is given then a | |
179 | pair is removed only if both key and value match. | |
180 | .IP | |
181 | It is not an error if the column does not contain the specified key or | |
182 | value or pair. | |
183 | .IP | |
184 | Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not | |
185 | exist. With \fB\-\-if-exists\fR, this command does nothing if | |
186 | \fIrecord\fR does not exist. | |
187 | . | |
188 | .IP "[\fB\-\-if\-exists\fR] \fBclear\fR \fItable record column\fR..." | |
189 | Sets each \fIcolumn\fR in \fIrecord\fR in \fItable\fR to the empty set | |
190 | or empty map, as appropriate. This command applies only to columns | |
191 | that are allowed to be empty. | |
192 | .IP | |
193 | Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not | |
194 | exist. With \fB\-\-if-exists\fR, this command does nothing if | |
195 | \fIrecord\fR does not exist. | |
196 | . | |
197 | .IP "[\fB\-\-id=@\fIname\fR] \fBcreate\fR \fItable column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..." | |
198 | Creates a new record in \fItable\fR and sets the initial values of | |
199 | each \fIcolumn\fR. Columns not explicitly set will receive their | |
200 | default values. Outputs the UUID of the new row. | |
201 | .IP | |
202 | If \fB@\fIname\fR is specified, then the UUID for the new row may be | |
203 | referred to by that name elsewhere in the same \fB\*(PN\fR | |
204 | invocation in contexts where a UUID is expected. Such references may | |
205 | precede or follow the \fBcreate\fR command. | |
206 | . | |
207 | .RS | |
5198d836 | 208 | .IP "Caution (ovs-vsctl as example)" |
f6a2e156 AW |
209 | Records in the Open vSwitch database are significant only when they |
210 | can be reached directly or indirectly from the \fBOpen_vSwitch\fR | |
211 | table. Except for records in the \fBQoS\fR or \fBQueue\fR tables, | |
212 | records that are not reachable from the \fBOpen_vSwitch\fR table are | |
213 | automatically deleted from the database. This deletion happens | |
214 | immediately, without waiting for additional \fBovs\-vsctl\fR commands | |
215 | or other database activity. Thus, a \fBcreate\fR command must | |
216 | generally be accompanied by additional commands \fIwithin the same | |
217 | \fBovs\-vsctl\fI invocation\fR to add a chain of references to the | |
218 | newly created record from the top-level \fBOpen_vSwitch\fR record. | |
219 | The \fBEXAMPLES\fR section gives some examples that show how to do | |
220 | this. | |
221 | .RE | |
222 | . | |
223 | .IP "\fR[\fB\-\-if\-exists\fR] \fBdestroy \fItable record\fR..." | |
224 | Deletes each specified \fIrecord\fR from \fItable\fR. Unless | |
225 | \fB\-\-if\-exists\fR is specified, each \fIrecord\fRs must exist. | |
226 | .IP "\fB\-\-all destroy \fItable\fR" | |
227 | Deletes all records from the \fItable\fR. | |
228 | . | |
229 | .RS | |
5198d836 | 230 | .IP "Caution (ovs-vsctl as example)" |
f6a2e156 AW |
231 | The \fBdestroy\fR command is only useful for records in the \fBQoS\fR |
232 | or \fBQueue\fR tables. Records in other tables are automatically | |
233 | deleted from the database when they become unreachable from the | |
234 | \fBOpen_vSwitch\fR table. This means that deleting the last reference | |
235 | to a record is sufficient for deleting the record itself. For records | |
236 | in these tables, \fBdestroy\fR is silently ignored. See the | |
237 | \fBEXAMPLES\fR section below for more information. | |
238 | .RE | |
239 | . | |
240 | .IP "\fBwait\-until \fItable record \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..." | |
241 | Waits until \fItable\fR contains a record named \fIrecord\fR whose | |
242 | \fIcolumn\fR equals \fIvalue\fR or, if \fIkey\fR is specified, whose | |
243 | \fIcolumn\fR contains a \fIkey\fR with the specified \fIvalue\fR. Any | |
244 | of the operators \fB!=\fR, \fB<\fR, \fB>\fR, \fB<=\fR, or \fB>=\fR may | |
245 | be substituted for \fB=\fR to test for inequality, less than, greater | |
246 | than, less than or equal to, or greater than or equal to, | |
247 | respectively. (Don't forget to escape \fB<\fR or \fB>\fR from | |
248 | interpretation by the shell.) | |
249 | .IP | |
250 | If no \fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR arguments are given, | |
251 | this command waits only until \fIrecord\fR exists. If more than one | |
252 | such argument is given, the command waits until all of them are | |
253 | satisfied. | |
254 | . | |
255 | .RS | |
5198d836 | 256 | .IP "Caution (ovs-vsctl as example)" |
f6a2e156 AW |
257 | Usually \fBwait\-until\fR should be placed at the beginning of a set |
258 | of \fBovs\-vsctl\fR commands. For example, \fBwait\-until bridge br0 | |
259 | \-\- get bridge br0 datapath_id\fR waits until a bridge named | |
260 | \fBbr0\fR is created, then prints its \fBdatapath_id\fR column, | |
261 | whereas \fBget bridge br0 datapath_id \-\- wait\-until bridge br0\fR | |
262 | will abort if no bridge named \fBbr0\fR exists when \fBovs\-vsctl\fR | |
263 | initially connects to the database. | |
264 | .RE | |
265 | .IP | |
266 | Consider specifying \fB\-\-timeout=0\fR along with | |
267 | \fB\-\-wait\-until\fR, to prevent \fB\*(PN\fR from terminating | |
268 | after waiting only at most 5 seconds. | |
269 | .IP "\fBcomment \fR[\fIarg\fR]..." | |
270 | This command has no effect on behavior, but any database log record | |
271 | created by the command will include the command and its arguments. |