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. 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.
  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
 208 .IP "Caution (ovs-vsctl as example)"
 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
 230 .IP "Caution (ovs-vsctl as example)"
 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
 256 .IP "Caution (ovs-vsctl as example)"
 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.