lib/db-ctl-base.xml

   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>&quot;&quot;</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&apos;&apos; 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>= != &lt; &gt; &lt;= &gt;=</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>{&lt;=}</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{&lt;=}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>{&lt;}</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{&lt;}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>{&gt;=} {&gt;}</code></dt>
 142         <dd>
 143           Same as <code>{&lt;=}</code> and <code>{&lt;}</code>, respectively, except that the
 144           relationship is reversed.  For example, <code>flood-vlans{&gt;=}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>= != &lt; &gt; &lt;= &gt;=</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>&lt;</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>
 307         <dt>Caution (ovs-vsctl as exmaple)</dt>
 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>
 337         <dt>Caution (ovs-vsctl as exmaple)</dt>
 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>&lt;</code>, <code>&gt;</code>, <code>&lt;=</code>, or <code>&gt;=</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>&lt;</code> or <code>&gt;</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>
 369         <dt>Caution (ovs-vsctl as exmaple)</dt>
 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>