lib/db-ctl-base.man

   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.