]>
Commit | Line | Data |
---|---|---|
7ba0c32f WL |
1 | <?xml version="1.0" encoding="utf-8"?> |
2 | <p> | |
3 | <p><var>Database Values</var></p> | |
4 | ||
5 | <p> | |
6 | Each column in the database accepts a fixed type of data. The | |
7 | currently defined basic types, and their representations, are: | |
8 | </p> | |
9 | ||
10 | <dl> | |
11 | <dt>integer</dt> | |
12 | <dd> | |
13 | A decimal integer in the range -2**63 to 2**63-1, inclusive. | |
14 | </dd> | |
15 | ||
16 | <dt>real</dt> | |
17 | <dd> | |
18 | A floating-point number. | |
19 | </dd> | |
20 | ||
21 | <dt>Boolean</dt> | |
22 | <dd> | |
23 | True or false, written <code>true</code> or <code>false</code>, respectively. | |
24 | </dd> | |
25 | ||
26 | <dt>string</dt> | |
27 | <dd> | |
28 | An arbitrary Unicode string, except that null bytes are not allowed. | |
29 | Quotes are optional for most strings that begin with an English letter | |
30 | or underscore and consist only of letters, underscores, hyphens, and | |
31 | periods. However, <code>true</code> and <code>false</code> and strings that match | |
32 | the syntax of UUIDs (see below) must be enclosed in double quotes to | |
33 | distinguish them from other basic types. When double quotes are used, | |
34 | the syntax is that of strings in JSON, e.g. backslashes may be used to | |
35 | escape special characters. The empty string must be represented as a | |
36 | pair of double quotes (<code>""</code>). | |
37 | </dd> | |
38 | ||
39 | <dt>UUID</dt> | |
40 | <dd> | |
41 | Either a universally unique identifier in the style of RFC 4122, | |
42 | e.g. <code>f81d4fae-7dec-11d0-a765-00a0c91e6bf6</code>, or an <code>@</code><var>name</var> | |
43 | defined by a <code>get</code> or <code>create</code> command within the same <code>ovn-nbctl</code> | |
44 | invocation. | |
45 | </dd> | |
46 | ||
47 | </dl> | |
48 | ||
49 | <p> | |
50 | Multiple values in a single column may be separated by spaces or a | |
51 | single comma. When multiple values are present, duplicates are not | |
52 | allowed, and order is not important. Conversely, some database | |
53 | columns can have an empty set of values, represented as <code>[]</code>, and | |
54 | square brackets may optionally enclose other non-empty sets or single | |
55 | values as well. | |
56 | </p> | |
57 | ||
58 | <p> | |
59 | A few database columns are ``maps'' of key-value pairs, where the key | |
60 | and the value are each some fixed database type. These are specified | |
61 | in the form <var>key</var><code>=</code><var>value</var>, where <var>key</var> and <var>value</var> | |
62 | follow the syntax for the column's key type and value type, | |
63 | respectively. When multiple pairs are present (separated by spaces or | |
64 | a comma), duplicate keys are not allowed, and again the order is not | |
65 | important. Duplicate values are allowed. An empty map is represented | |
66 | as <code>{}</code>. Curly braces may optionally enclose non-empty maps as | |
67 | well (but use quotes to prevent the shell from expanding | |
68 | <code>other-config={0=x,1=y}</code> into <code>other-config=0=x | |
69 | other-config=1=y</code>, which may not have the desired effect). | |
70 | </p> | |
71 | ||
72 | <p><var>Database Command Syntax</var></p> | |
73 | ||
74 | <dl> | |
75 | <dt>[<code>--if-exists</code>] [<code>--columns=</code><var>column</var>[<code>,</code><var>column</var>]...] <code>list</code> <var>table</var> [<var>record</var>]...</dt> | |
76 | <dd> | |
77 | <p> | |
78 | Lists the data in each specified <var>record</var>. If no | |
79 | records are specified, lists all the records in <var>table</var>. | |
80 | </p> | |
81 | <p> | |
82 | If <code>--columns</code> is specified, only the requested columns are | |
83 | listed, in the specified order. Otherwise, all columns are listed, in | |
84 | alphabetical order by column name. | |
85 | </p> | |
86 | <p> | |
87 | Without <code>--if-exists</code>, it is an error if any specified | |
88 | <var>record</var> does not exist. With <code>--if-exists</code>, the command | |
89 | ignores any <var>record</var> that does not exist, without producing any | |
90 | output. | |
91 | </p> | |
92 | </dd> | |
93 | ||
94 | <dt>[<code>--columns=</code><var>column</var>[<code>,</code><var>column</var>]...] <code>find</code> <var>table</var> [<var>column</var>[<code>:</code><var>key</var>]<code>=</code><var>value</var>]...</dt> | |
95 | <dd> | |
96 | <p> | |
97 | Lists the data in each record in <var>table</var> whose <var>column</var> equals | |
98 | <var>value</var> or, if <var>key</var> is specified, whose <var>column</var> contains | |
99 | a <var>key</var> with the specified <var>value</var>. The following operators | |
100 | may be used where <code>=</code> is written in the syntax summary: | |
101 | </p> | |
102 | <dl> | |
103 | <dt><code>= != < > <= >=</code></dt> | |
104 | <dd> | |
105 | <p> | |
106 | Selects records in which <var>column</var>[<code>:</code><var>key</var>] equals, does not | |
107 | equal, is less than, is greater than, is less than or equal to, or is | |
108 | greater than or equal to <var>value</var>, respectively.</p> | |
109 | <p>Consider <var>column</var>[<code>:</code><var>key</var>] and <var>value</var> as sets of | |
110 | elements. Identical sets are considered equal. Otherwise, if the | |
111 | sets have different numbers of elements, then the set with more | |
112 | elements is considered to be larger. Otherwise, consider a element | |
113 | from each set pairwise, in increasing order within each set. The | |
114 | first pair that differs determines the result. (For a column that | |
115 | contains key-value pairs, first all the keys are compared, and values | |
116 | are considered only if the two sets contain identical keys.) | |
117 | </p> | |
118 | </dd> | |
119 | ||
120 | <dt><code>{=} {!=}</code></dt> | |
121 | <dd> | |
122 | Test for set equality or inequality, respectively. | |
123 | </dd> | |
124 | ||
125 | <dt><code>{<=}</code></dt> | |
126 | <dd> | |
127 | Selects records in which <var>column</var>[<code>:</code><var>key</var>] is a subset of | |
128 | <var>value</var>. For example, <code>flood-vlans{<=}1,2</code> selects records in | |
129 | which the <code>flood-vlans</code> column is the empty set or contains 1 or 2 | |
130 | or both. | |
131 | </dd> | |
132 | ||
133 | <dt><code>{<}</code></dt> | |
134 | <dd> | |
135 | Selects records in which <var>column</var>[<code>:</code><var>key</var>] is a proper | |
136 | subset of <var>value</var>. For example, <code>flood-vlans{<}1,2</code> selects | |
137 | records in which the <code>flood-vlans</code> column is the empty set or | |
138 | contains 1 or 2 but not both. | |
139 | </dd> | |
140 | ||
141 | <dt><code>{>=} {>}</code></dt> | |
142 | <dd> | |
143 | Same as <code>{<=}</code> and <code>{<}</code>, respectively, except that the | |
144 | relationship is reversed. For example, <code>flood-vlans{>=}1,2</code> | |
145 | selects records in which the <code>flood-vlans</code> column contains both 1 | |
146 | and 2. | |
147 | </dd> | |
148 | ||
149 | </dl> | |
150 | ||
151 | <p> | |
152 | For arithmetic operators (<code>= != < > <= >=</code>), when <var>key</var> is | |
153 | specified but a particular record's <var>column</var> does not contain | |
154 | <var>key</var>, the record is always omitted from the results. Thus, the | |
155 | condition <code>other-config:mtu!=1500</code> matches records that have a | |
156 | <code>mtu</code> key whose value is not 1500, but not those that lack an | |
157 | <code>mtu</code> key. | |
158 | </p> | |
159 | ||
160 | <p> | |
161 | For the set operators, when <var>key</var> is specified but a particular | |
162 | record's <var>column</var> does not contain <var>key</var>, the comparison is | |
163 | done against an empty set. Thus, the condition | |
164 | <code>other-config:mtu{!=}1500</code> matches records that have a <code>mtu</code> | |
165 | key whose value is not 1500 and those that lack an <code>mtu</code> key. | |
166 | </p> | |
167 | ||
168 | <p> | |
169 | Don't forget to escape <code><</code> or <code>></code> from interpretation by the | |
170 | shell. | |
171 | </p> | |
172 | ||
173 | <p> | |
174 | If <code>--columns</code> is specified, only the requested columns are | |
175 | listed, in the specified order. Otherwise all columns are listed, in | |
176 | alphabetical order by column name. | |
177 | </p> | |
178 | ||
179 | <p> | |
180 | The UUIDs shown for rows created in the same <code>ovn-nbctl</code> | |
181 | invocation will be wrong. | |
182 | </p> | |
183 | ||
184 | </dd> | |
185 | ||
186 | <dt>[<code>--if-exists</code>] [<code>--id=@</code><var>name</var>] <code>get</code> <var>table record</var> [<var>column</var>[<code>:</code><var>key</var>]]...</dt> | |
187 | <dd> | |
188 | <p> | |
189 | Prints the value of each specified <var>column</var> in the given | |
190 | <var>record</var> in <var>table</var>. For map columns, a <var>key</var> may | |
191 | optionally be specified, in which case the value associated with | |
192 | <var>key</var> in the column is printed, instead of the entire map. | |
193 | </p> | |
194 | <p> | |
195 | Without <code>--if-exists</code>, it is an error if <var>record</var> does not | |
196 | exist or <var>key</var> is specified, if <var>key</var> does not exist in | |
197 | <var>record</var>. With <code>--if-exists</code>, a missing <var>record</var> | |
198 | yields no output and a missing <var>key</var> prints a blank line. | |
199 | </p> | |
200 | <p> | |
201 | If <code>@</code><var>name</var> is specified, then the UUID for <var>record</var> may be | |
202 | referred to by that name later in the same <code>ovn-nbctl</code> | |
203 | invocation in contexts where a UUID is expected. | |
204 | </p> | |
205 | <p> | |
206 | Both <code>--id</code> and the <var>column</var> arguments are optional, but | |
207 | usually at least one or the other should be specified. If both are | |
208 | omitted, then <code>get</code> has no effect except to verify that | |
209 | <var>record</var> exists in <var>table</var>. | |
210 | </p> | |
211 | <p> | |
212 | <code>--id</code> and <code>--if-exists</code> cannot be used together. | |
213 | </p> | |
214 | </dd> | |
215 | ||
216 | <dt>[<code>--if-exists</code>] <code>set</code> <var>table record column</var>[<code>:</code><var>key</var>]<code>=</code><var>value</var>...</dt> | |
217 | <dd> | |
218 | <p> | |
219 | Sets the value of each specified <var>column</var> in the given | |
220 | <var>record</var> in <var>table</var> to <var>value</var>. For map columns, a | |
221 | <var>key</var> may optionally be specified, in which case the value | |
222 | associated with <var>key</var> in that column is changed (or added, if none | |
223 | exists), instead of the entire map. | |
224 | </p> | |
225 | <p> | |
226 | Without <code>--if-exists</code>, it is an error if <var>record</var> does not | |
227 | exist. With <code>--if-exists</code>, this command does nothing if | |
228 | <var>record</var> does not exist. | |
229 | </p> | |
230 | </dd> | |
231 | <dt>[<code>--if-exists</code>] <code>add</code> <var>table record column</var> [<var>key</var><code>=</code>]<var>value</var>...</dt> | |
232 | <dd> | |
233 | <p> | |
234 | Adds the specified value or key-value pair to <var>column</var> in | |
235 | <var>record</var> in <var>table</var>. If <var>column</var> is a map, then <var>key</var> | |
236 | is required, otherwise it is prohibited. If <var>key</var> already exists | |
237 | in a map column, then the current <var>value</var> is not replaced (use the | |
238 | <code>set</code> command to replace an existing value). | |
239 | </p> | |
240 | <p> | |
241 | Without <code>--if-exists</code>, it is an error if <var>record</var> does not | |
242 | exist. With <code>--if-exists</code>, this command does nothing if | |
243 | <var>record</var> does not exist. | |
244 | </p> | |
245 | </dd> | |
246 | ||
247 | <dt> | |
248 | <p> | |
249 | [<code>--if-exists</code>] <code>remove</code> <var>table record column value</var>... | |
250 | </p> | |
251 | <p> | |
252 | [<code>--if-exists</code>] <code>remove</code> <var>table record column key</var>... | |
253 | </p> | |
254 | <p> | |
255 | [<code>--if-exists</code>] <code>remov</code> <var>table record column key</var><code>=</code><var>value</var>... | |
256 | </p> | |
257 | </dt> | |
258 | <dd> | |
259 | <p> | |
260 | Removes the specified values or key-value pairs from <var>column</var> in | |
261 | <var>record</var> in <var>table</var>. The first form applies to columns that | |
262 | are not maps: each specified <var>value</var> is removed from the column. | |
263 | The second and third forms apply to map columns: if only a <var>key</var> | |
264 | is specified, then any key-value pair with the given <var>key</var> is | |
265 | removed, regardless of its value; if a <var>value</var> is given then a | |
266 | pair is removed only if both key and value match. | |
267 | </p> | |
268 | <p> | |
269 | It is not an error if the column does not contain the specified key or | |
270 | value or pair. | |
271 | </p> | |
272 | <p> | |
273 | Without <code>--if-exists</code>, it is an error if <var>record</var> does not | |
274 | exist. With <code>--if-exists</code>, this command does nothing if | |
275 | <var>record</var> does not exist. | |
276 | </p> | |
277 | </dd> | |
278 | ||
279 | <dt>[<code>--if-exists</code>] <code>clear</code> <var>table record column</var>...</dt> | |
280 | <dd> | |
281 | <p> | |
282 | Sets each <var>column</var> in <var>record</var> in <var>table</var> to the empty set | |
283 | or empty map, as appropriate. This command applies only to columns | |
284 | that are allowed to be empty. | |
285 | </p> | |
286 | <p> | |
287 | Without <code>--if-exists</code>, it is an error if <var>record</var> does not | |
288 | exist. With <code>--if-exists</code>, this command does nothing if | |
289 | <var>record</var> does not exist. | |
290 | </p> | |
291 | </dd> | |
292 | ||
293 | <dt>[<code>--id=@</code><var>name</var>] <code>create</code> <var>table column</var>[<code>:</code><var>key</var>]<code>=</code><var>value</var>...</dt> | |
294 | <dd> | |
295 | <p> | |
296 | Creates a new record in <var>table</var> and sets the initial values of | |
297 | each <var>column</var>. Columns not explicitly set will receive their | |
298 | default values. Outputs the UUID of the new row. | |
299 | </p> | |
300 | <p> | |
301 | If <code>@</code><var>name</var> is specified, then the UUID for the new row may be | |
302 | referred to by that name elsewhere in the same <code>\*(PN</code> | |
303 | invocation in contexts where a UUID is expected. Such references may | |
304 | precede or follow the <code>create</code> command. | |
305 | </p> | |
306 | <dl> | |
5198d836 | 307 | <dt>Caution (ovs-vsctl as example)</dt> |
7ba0c32f WL |
308 | <dd> |
309 | Records in the Open vSwitch database are significant only when they | |
310 | can be reached directly or indirectly from the <code>Open_vSwitch</code> | |
311 | table. Except for records in the <code>QoS</code> or <code>Queue</code> tables, | |
312 | records that are not reachable from the <code>Open_vSwitch</code> table are | |
313 | automatically deleted from the database. This deletion happens | |
314 | immediately, without waiting for additional <code>ovs-vsctl</code> commands | |
315 | or other database activity. Thus, a <code>create</code> command must | |
316 | generally be accompanied by additional commands <var>within the same</var> | |
317 | <code>ovs-vsctl</code> <var>invocation</var> to add a chain of references to the | |
318 | newly created record from the top-level <code>Open_vSwitch</code> record. | |
319 | The <code>EXAMPLES</code> section gives some examples that show how to do | |
320 | this. | |
321 | </dd> | |
322 | </dl> | |
323 | </dd> | |
324 | ||
325 | <dt>[<code>--if-exists</code>] <code>destroy</code> <var>table record</var>...</dt> | |
326 | <dd> | |
327 | Deletes each specified <var>record</var> from <var>table</var>. Unless | |
328 | <code>--if-exists</code> is specified, each <var>record</var>s must exist. | |
329 | </dd> | |
330 | ||
331 | <dt><code>--all destroy</code> <var>table</var></dt> | |
332 | <dd> | |
333 | <p> | |
334 | Deletes all records from the <var>table</var>. | |
335 | </p> | |
336 | <dl> | |
5198d836 | 337 | <dt>Caution (ovs-vsctl as example)</dt> |
7ba0c32f WL |
338 | <dd> |
339 | The <code>destroy</code> command is only useful for records in the <code>QoS</code> | |
340 | or <code>Queue</code> tables. Records in other tables are automatically | |
341 | deleted from the database when they become unreachable from the | |
342 | <code>Open_vSwitch</code> table. This means that deleting the last reference | |
343 | to a record is sufficient for deleting the record itself. For records | |
344 | in these tables, <code>destroy</code> is silently ignored. See the | |
345 | <code>EXAMPLES</code> section below for more information. | |
346 | </dd> | |
347 | </dl> | |
348 | </dd> | |
349 | ||
350 | <dt><code>wait-until</code> <var>table record</var> [<var>column</var>[<code>:</code><var>key</var>]<code>=</code><var>value</var>]...</dt> | |
351 | <dd> | |
352 | <p> | |
353 | Waits until <var>table</var> contains a record named <var>record</var> whose | |
354 | <var>column</var> equals <var>value</var> or, if <var>key</var> is specified, whose | |
355 | <var>column</var> contains a <var>key</var> with the specified <var>value</var>. Any | |
356 | of the operators <code>!=</code>, <code><</code>, <code>></code>, <code><=</code>, or <code>>=</code> may | |
357 | be substituted for <code>=</code> to test for inequality, less than, greater | |
358 | than, less than or equal to, or greater than or equal to, | |
359 | respectively. (Don't forget to escape <code><</code> or <code>></code> from | |
360 | interpretation by the shell.) | |
361 | </p> | |
362 | <p> | |
363 | If no <var>column</var>[<code>:</code><var>key</var>]<code>=</code><var>value</var> arguments are given, | |
364 | this command waits only until <var>record</var> exists. If more than one | |
365 | such argument is given, the command waits until all of them are | |
366 | satisfied. | |
367 | </p> | |
368 | <dl> | |
5198d836 | 369 | <dt>Caution (ovs-vsctl as example)</dt> |
7ba0c32f WL |
370 | <dd> |
371 | Usually <code>wait-until</code> should be placed at the beginning of a set | |
372 | of <code>ovs-vsctl</code> commands. For example, <code>wait-until bridge br0 | |
373 | -- get bridge br0 datapath_id</code> waits until a bridge named | |
374 | <code>br0</code> is created, then prints its <code>datapath_id</code> column, | |
375 | whereas <code>get bridge br0 datapath_id -- wait-until bridge br0</code> | |
376 | will abort if no bridge named <code>br0</code> exists when <code>ovs-vsctl</code> | |
377 | initially connects to the database. | |
378 | </dd> | |
379 | </dl> | |
380 | <p> | |
381 | Consider specifying <code>--timeout=0</code> along with | |
382 | <code>--wait-until</code>, to prevent <code>ovn-nbctl</code> from terminating | |
383 | after waiting only at most 5 seconds. | |
384 | </p> | |
385 | </dd> | |
386 | ||
387 | <dt><code>comment</code> [<var>arg</var>]...</dt> | |
388 | <dd> | |
389 | <p> | |
390 | This command has no effect on behavior, but any database log record | |
391 | created by the command will include the command and its arguments. | |
392 | </p> | |
393 | </dd> | |
394 | ||
395 | </dl> | |
396 | </p> |