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