From f6a2e156196f76b7e8d9b20f125c2ddd63c41d5e Mon Sep 17 00:00:00 2001 From: Alex Wang Date: Thu, 11 Jun 2015 17:08:52 -0700 Subject: [PATCH] db-ctl-base: Librarize database command manual. This commit extracts the database command manual and puts it into db-ctl-base.man. Signed-off-by: Alex Wang Acked-by: Ben Pfaff --- lib/automake.mk | 1 + lib/db-ctl-base.man | 267 +++++++++++++++++++++++++++++++++++++++ manpages.mk | 2 + utilities/ovs-vsctl.8.in | 259 +------------------------------------ 4 files changed, 271 insertions(+), 258 deletions(-) create mode 100644 lib/db-ctl-base.man diff --git a/lib/automake.mk b/lib/automake.mk index 69d2deb8bb1..a22f5f37a0e 100644 --- a/lib/automake.mk +++ b/lib/automake.mk @@ -413,6 +413,7 @@ MAN_FRAGMENTS += \ lib/coverage-unixctl.man \ lib/daemon.man \ lib/daemon-syn.man \ + lib/db-ctl-base.man \ lib/dpctl.man \ lib/memory-unixctl.man \ lib/ofp-version.man \ diff --git a/lib/db-ctl-base.man b/lib/db-ctl-base.man new file mode 100644 index 00000000000..7b30501c597 --- /dev/null +++ b/lib/db-ctl-base.man @@ -0,0 +1,267 @@ +.ST "Database Values" +.PP +Each column in the database accepts a fixed type of data. The +currently defined basic types, and their representations, are: +.IP "integer" +A decimal integer in the range \-2**63 to 2**63\-1, inclusive. +.IP "real" +A floating-point number. +.IP "Boolean" +True or false, written \fBtrue\fR or \fBfalse\fR, respectively. +.IP "string" +An arbitrary Unicode string, except that null bytes are not allowed. +Quotes are optional for most strings that begin with an English letter +or underscore and consist only of letters, underscores, hyphens, and +periods. However, \fBtrue\fR and \fBfalse\fR and strings that match +the syntax of UUIDs (see below) must be enclosed in double quotes to +distinguish them from other basic types. When double quotes are used, +the syntax is that of strings in JSON, e.g. backslashes may be used to +escape special characters. The empty string must be represented as a +pair of double quotes (\fB""\fR). +.IP "UUID" +Either a universally unique identifier in the style of RFC 4122, +e.g. \fBf81d4fae\-7dec\-11d0\-a765\-00a0c91e6bf6\fR, or an \fB@\fIname\fR +defined by a \fBget\fR or \fBcreate\fR command within the same \fB\*(PN\fR +invocation. +.PP +Multiple values in a single column may be separated by spaces or a +single comma. When multiple values are present, duplicates are not +allowed, and order is not important. Conversely, some database +columns can have an empty set of values, represented as \fB[]\fR, and +square brackets may optionally enclose other non-empty sets or single +values as well. +.PP +A few database columns are ``maps'' of key-value pairs, where the key +and the value are each some fixed database type. These are specified +in the form \fIkey\fB=\fIvalue\fR, where \fIkey\fR and \fIvalue\fR +follow the syntax for the column's key type and value type, +respectively. When multiple pairs are present (separated by spaces or +a comma), duplicate keys are not allowed, and again the order is not +important. Duplicate values are allowed. An empty map is represented +as \fB{}\fR. Curly braces may optionally enclose non-empty maps as +well (but use quotes to prevent the shell from expanding +\fBother-config={0=x,1=y}\fR into \fBother-config=0=x +other-config=1=y\fR, which may not have the desired effect). +. +.ST "Database Command Syntax" +. +.IP "[\fB\-\-if\-exists\fR] [\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBlist \fItable \fR[\fIrecord\fR]..." +Lists the data in each specified \fIrecord\fR. If no +records are specified, lists all the records in \fItable\fR. +.IP +If \fB\-\-columns\fR is specified, only the requested columns are +listed, in the specified order. Otherwise, all columns are listed, in +alphabetical order by column name. +.IP +Without \fB\-\-if-exists\fR, it is an error if any specified +\fIrecord\fR does not exist. With \fB\-\-if-exists\fR, the command +ignores any \fIrecord\fR that does not exist, without producing any +output. +. +.IP "[\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBfind \fItable \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..." +Lists the data in each record in \fItable\fR whose \fIcolumn\fR equals +\fIvalue\fR or, if \fIkey\fR is specified, whose \fIcolumn\fR contains +a \fIkey\fR with the specified \fIvalue\fR. The following operators +may be used where \fB=\fR is written in the syntax summary: +.RS +.IP "\fB= != < > <= >=\fR" +Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] equals, does not +equal, is less than, is greater than, is less than or equal to, or is +greater than or equal to \fIvalue\fR, respectively. +.IP +Consider \fIcolumn\fR[\fB:\fIkey\fR] and \fIvalue\fR as sets of +elements. Identical sets are considered equal. Otherwise, if the +sets have different numbers of elements, then the set with more +elements is considered to be larger. Otherwise, consider a element +from each set pairwise, in increasing order within each set. The +first pair that differs determines the result. (For a column that +contains key-value pairs, first all the keys are compared, and values +are considered only if the two sets contain identical keys.) +.IP "\fB{=} {!=}\fR" +Test for set equality or inequality, respectively. +.IP "\fB{<=}\fR" +Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] is a subset of +\fIvalue\fR. For example, \fBflood-vlans{<=}1,2\fR selects records in +which the \fBflood-vlans\fR column is the empty set or contains 1 or 2 +or both. +.IP "\fB{<}\fR" +Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] is a proper +subset of \fIvalue\fR. For example, \fBflood-vlans{<}1,2\fR selects +records in which the \fBflood-vlans\fR column is the empty set or +contains 1 or 2 but not both. +.IP "\fB{>=} {>}\fR" +Same as \fB{<=}\fR and \fB{<}\fR, respectively, except that the +relationship is reversed. For example, \fBflood-vlans{>=}1,2\fR +selects records in which the \fBflood-vlans\fR column contains both 1 +and 2. +.RE +.IP +For arithmetic operators (\fB= != < > <= >=\fR), when \fIkey\fR is +specified but a particular record's \fIcolumn\fR does not contain +\fIkey\fR, the record is always omitted from the results. Thus, the +condition \fBother-config:mtu!=1500\fR matches records that have a +\fBmtu\fR key whose value is not 1500, but not those that lack an +\fBmtu\fR key. +.IP +For the set operators, when \fIkey\fR is specified but a particular +record's \fIcolumn\fR does not contain \fIkey\fR, the comparison is +done against an empty set. Thus, the condition +\fBother-config:mtu{!=}1500\fR matches records that have a \fBmtu\fR +key whose value is not 1500 and those that lack an \fBmtu\fR key. +.IP +Don't forget to escape \fB<\fR or \fB>\fR from interpretation by the +shell. +.IP +If \fB\-\-columns\fR is specified, only the requested columns are +listed, in the specified order. Otherwise all columns are listed, in +alphabetical order by column name. +.IP +The UUIDs shown for rows created in the same \fB\*(PN\fR +invocation will be wrong. +. +.IP "[\fB\-\-if\-exists\fR] [\fB\-\-id=@\fIname\fR] \fBget \fItable record \fR[\fIcolumn\fR[\fB:\fIkey\fR]]..." +Prints the value of each specified \fIcolumn\fR in the given +\fIrecord\fR in \fItable\fR. For map columns, a \fIkey\fR may +optionally be specified, in which case the value associated with +\fIkey\fR in the column is printed, instead of the entire map. +.IP +Without \fB\-\-if\-exists\fR, it is an error if \fIrecord\fR does not +exist or \fIkey\fR is specified, if \fIkey\fR does not exist in +\fIrecord\fR. With \fB\-\-if\-exists\fR, a missing \fIrecord\fR +yields no output and a missing \fIkey\fR prints a blank line. +.IP +If \fB@\fIname\fR is specified, then the UUID for \fIrecord\fR may be +referred to by that name later in the same \fB\*(PN\fR +invocation in contexts where a UUID is expected. +.IP +Both \fB\-\-id\fR and the \fIcolumn\fR arguments are optional, but +usually at least one or the other should be specified. If both are +omitted, then \fBget\fR has no effect except to verify that +\fIrecord\fR exists in \fItable\fR. +.IP +\fB\-\-id\fR and \fB\-\-if\-exists\fR cannot be used together. +. +.IP "[\fB\-\-if\-exists\fR] \fBset \fItable record column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..." +Sets the value of each specified \fIcolumn\fR in the given +\fIrecord\fR in \fItable\fR to \fIvalue\fR. For map columns, a +\fIkey\fR may optionally be specified, in which case the value +associated with \fIkey\fR in that column is changed (or added, if none +exists), instead of the entire map. +.IP +Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not +exist. With \fB\-\-if-exists\fR, this command does nothing if +\fIrecord\fR does not exist. +. +.IP "[\fB\-\-if\-exists\fR] \fBadd \fItable record column \fR[\fIkey\fB=\fR]\fIvalue\fR..." +Adds the specified value or key-value pair to \fIcolumn\fR in +\fIrecord\fR in \fItable\fR. If \fIcolumn\fR is a map, then \fIkey\fR +is required, otherwise it is prohibited. If \fIkey\fR already exists +in a map column, then the current \fIvalue\fR is not replaced (use the +\fBset\fR command to replace an existing value). +.IP +Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not +exist. With \fB\-\-if-exists\fR, this command does nothing if +\fIrecord\fR does not exist. +. +.IP "[\fB\-\-if\-exists\fR] \fBremove \fItable record column \fR\fIvalue\fR..." +.IQ "[\fB\-\-if\-exists\fR] \fBremove \fItable record column \fR\fIkey\fR..." +.IQ "[\fB\-\-if\-exists\fR] \fBremove \fItable record column \fR\fIkey\fB=\fR\fIvalue\fR..." +Removes the specified values or key-value pairs from \fIcolumn\fR in +\fIrecord\fR in \fItable\fR. The first form applies to columns that +are not maps: each specified \fIvalue\fR is removed from the column. +The second and third forms apply to map columns: if only a \fIkey\fR +is specified, then any key-value pair with the given \fIkey\fR is +removed, regardless of its value; if a \fIvalue\fR is given then a +pair is removed only if both key and value match. +.IP +It is not an error if the column does not contain the specified key or +value or pair. +.IP +Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not +exist. With \fB\-\-if-exists\fR, this command does nothing if +\fIrecord\fR does not exist. +. +.IP "[\fB\-\-if\-exists\fR] \fBclear\fR \fItable record column\fR..." +Sets each \fIcolumn\fR in \fIrecord\fR in \fItable\fR to the empty set +or empty map, as appropriate. This command applies only to columns +that are allowed to be empty. +.IP +Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not +exist. With \fB\-\-if-exists\fR, this command does nothing if +\fIrecord\fR does not exist. +. +.IP "[\fB\-\-id=@\fIname\fR] \fBcreate\fR \fItable column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..." +Creates a new record in \fItable\fR and sets the initial values of +each \fIcolumn\fR. Columns not explicitly set will receive their +default values. Outputs the UUID of the new row. +.IP +If \fB@\fIname\fR is specified, then the UUID for the new row may be +referred to by that name elsewhere in the same \fB\*(PN\fR +invocation in contexts where a UUID is expected. Such references may +precede or follow the \fBcreate\fR command. +. +.RS +.IP "Caution (ovs-vsctl as exmaple)" +Records in the Open vSwitch database are significant only when they +can be reached directly or indirectly from the \fBOpen_vSwitch\fR +table. Except for records in the \fBQoS\fR or \fBQueue\fR tables, +records that are not reachable from the \fBOpen_vSwitch\fR table are +automatically deleted from the database. This deletion happens +immediately, without waiting for additional \fBovs\-vsctl\fR commands +or other database activity. Thus, a \fBcreate\fR command must +generally be accompanied by additional commands \fIwithin the same +\fBovs\-vsctl\fI invocation\fR to add a chain of references to the +newly created record from the top-level \fBOpen_vSwitch\fR record. +The \fBEXAMPLES\fR section gives some examples that show how to do +this. +.RE +. +.IP "\fR[\fB\-\-if\-exists\fR] \fBdestroy \fItable record\fR..." +Deletes each specified \fIrecord\fR from \fItable\fR. Unless +\fB\-\-if\-exists\fR is specified, each \fIrecord\fRs must exist. +.IP "\fB\-\-all destroy \fItable\fR" +Deletes all records from the \fItable\fR. +. +.RS +.IP "Caution (ovs-vsctl as exmaple)" +The \fBdestroy\fR command is only useful for records in the \fBQoS\fR +or \fBQueue\fR tables. Records in other tables are automatically +deleted from the database when they become unreachable from the +\fBOpen_vSwitch\fR table. This means that deleting the last reference +to a record is sufficient for deleting the record itself. For records +in these tables, \fBdestroy\fR is silently ignored. See the +\fBEXAMPLES\fR section below for more information. +.RE +. +.IP "\fBwait\-until \fItable record \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..." +Waits until \fItable\fR contains a record named \fIrecord\fR whose +\fIcolumn\fR equals \fIvalue\fR or, if \fIkey\fR is specified, whose +\fIcolumn\fR contains a \fIkey\fR with the specified \fIvalue\fR. Any +of the operators \fB!=\fR, \fB<\fR, \fB>\fR, \fB<=\fR, or \fB>=\fR may +be substituted for \fB=\fR to test for inequality, less than, greater +than, less than or equal to, or greater than or equal to, +respectively. (Don't forget to escape \fB<\fR or \fB>\fR from +interpretation by the shell.) +.IP +If no \fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR arguments are given, +this command waits only until \fIrecord\fR exists. If more than one +such argument is given, the command waits until all of them are +satisfied. +. +.RS +.IP "Caution (ovs-vsctl as exmaple)" +Usually \fBwait\-until\fR should be placed at the beginning of a set +of \fBovs\-vsctl\fR commands. For example, \fBwait\-until bridge br0 +\-\- get bridge br0 datapath_id\fR waits until a bridge named +\fBbr0\fR is created, then prints its \fBdatapath_id\fR column, +whereas \fBget bridge br0 datapath_id \-\- wait\-until bridge br0\fR +will abort if no bridge named \fBbr0\fR exists when \fBovs\-vsctl\fR +initially connects to the database. +.RE +.IP +Consider specifying \fB\-\-timeout=0\fR along with +\fB\-\-wait\-until\fR, to prevent \fB\*(PN\fR from terminating +after waiting only at most 5 seconds. +.IP "\fBcomment \fR[\fIarg\fR]..." +This command has no effect on behavior, but any database log record +created by the command will include the command and its arguments. diff --git a/manpages.mk b/manpages.mk index 4a76cf16a26..4cc3bf28b90 100644 --- a/manpages.mk +++ b/manpages.mk @@ -213,6 +213,7 @@ utilities/ovs-vlan-bugs.man: utilities/ovs-vsctl.8: \ utilities/ovs-vsctl.8.in \ lib/common.man \ + lib/db-ctl-base.man \ lib/ssl-bootstrap.man \ lib/ssl-peer-ca-cert.man \ lib/ssl.man \ @@ -226,6 +227,7 @@ utilities/ovs-vsctl.8: \ ovsdb/remote-passive.man utilities/ovs-vsctl.8.in: lib/common.man: +lib/db-ctl-base.man: lib/ssl-bootstrap.man: lib/ssl-peer-ca-cert.man: lib/ssl.man: diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in index 785857d95d4..972fc263754 100644 --- a/utilities/ovs-vsctl.8.in +++ b/utilities/ovs-vsctl.8.in @@ -565,264 +565,7 @@ and \fB\-\-\fR and \fB_\fR are treated interchangeably. Unique abbreviations are acceptable, e.g. \fBnet\fR or \fBn\fR is sufficient to identify the \fBNetFlow\fR table. . -.ST "Database Values" -.PP -Each column in the database accepts a fixed type of data. The -currently defined basic types, and their representations, are: -.IP "integer" -A decimal integer in the range \-2**63 to 2**63\-1, inclusive. -.IP "real" -A floating-point number. -.IP "Boolean" -True or false, written \fBtrue\fR or \fBfalse\fR, respectively. -.IP "string" -An arbitrary Unicode string, except that null bytes are not allowed. -Quotes are optional for most strings that begin with an English letter -or underscore and consist only of letters, underscores, hyphens, and -periods. However, \fBtrue\fR and \fBfalse\fR and strings that match -the syntax of UUIDs (see below) must be enclosed in double quotes to -distinguish them from other basic types. When double quotes are used, -the syntax is that of strings in JSON, e.g. backslashes may be used to -escape special characters. The empty string must be represented as a -pair of double quotes (\fB""\fR). -.IP "UUID" -Either a universally unique identifier in the style of RFC 4122, -e.g. \fBf81d4fae\-7dec\-11d0\-a765\-00a0c91e6bf6\fR, or an \fB@\fIname\fR -defined by a \fBget\fR or \fBcreate\fR command within the same \fBovs\-vsctl\fR -invocation. -.PP -Multiple values in a single column may be separated by spaces or a -single comma. When multiple values are present, duplicates are not -allowed, and order is not important. Conversely, some database -columns can have an empty set of values, represented as \fB[]\fR, and -square brackets may optionally enclose other non-empty sets or single -values as well. -.PP -A few database columns are ``maps'' of key-value pairs, where the key -and the value are each some fixed database type. These are specified -in the form \fIkey\fB=\fIvalue\fR, where \fIkey\fR and \fIvalue\fR -follow the syntax for the column's key type and value type, -respectively. When multiple pairs are present (separated by spaces or -a comma), duplicate keys are not allowed, and again the order is not -important. Duplicate values are allowed. An empty map is represented -as \fB{}\fR. Curly braces may optionally enclose non-empty maps as -well (but use quotes to prevent the shell from expanding -\fBother-config={0=x,1=y}\fR into \fBother-config=0=x -other-config=1=y\fR, which may not have the desired effect). -. -.ST "Database Command Syntax" -. -.IP "[\fB\-\-if\-exists\fR] [\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBlist \fItable \fR[\fIrecord\fR]..." -Lists the data in each specified \fIrecord\fR. If no -records are specified, lists all the records in \fItable\fR. -.IP -If \fB\-\-columns\fR is specified, only the requested columns are -listed, in the specified order. Otherwise, all columns are listed, in -alphabetical order by column name. -.IP -Without \fB\-\-if-exists\fR, it is an error if any specified -\fIrecord\fR does not exist. With \fB\-\-if-exists\fR, the command -ignores any \fIrecord\fR that does not exist, without producing any -output. -. -.IP "[\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBfind \fItable \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..." -Lists the data in each record in \fItable\fR whose \fIcolumn\fR equals -\fIvalue\fR or, if \fIkey\fR is specified, whose \fIcolumn\fR contains -a \fIkey\fR with the specified \fIvalue\fR. The following operators -may be used where \fB=\fR is written in the syntax summary: -.RS -.IP "\fB= != < > <= >=\fR" -Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] equals, does not -equal, is less than, is greater than, is less than or equal to, or is -greater than or equal to \fIvalue\fR, respectively. -.IP -Consider \fIcolumn\fR[\fB:\fIkey\fR] and \fIvalue\fR as sets of -elements. Identical sets are considered equal. Otherwise, if the -sets have different numbers of elements, then the set with more -elements is considered to be larger. Otherwise, consider a element -from each set pairwise, in increasing order within each set. The -first pair that differs determines the result. (For a column that -contains key-value pairs, first all the keys are compared, and values -are considered only if the two sets contain identical keys.) -.IP "\fB{=} {!=}\fR" -Test for set equality or inequality, respectively. -.IP "\fB{<=}\fR" -Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] is a subset of -\fIvalue\fR. For example, \fBflood-vlans{<=}1,2\fR selects records in -which the \fBflood-vlans\fR column is the empty set or contains 1 or 2 -or both. -.IP "\fB{<}\fR" -Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] is a proper -subset of \fIvalue\fR. For example, \fBflood-vlans{<}1,2\fR selects -records in which the \fBflood-vlans\fR column is the empty set or -contains 1 or 2 but not both. -.IP "\fB{>=} {>}\fR" -Same as \fB{<=}\fR and \fB{<}\fR, respectively, except that the -relationship is reversed. For example, \fBflood-vlans{>=}1,2\fR -selects records in which the \fBflood-vlans\fR column contains both 1 -and 2. -.RE -.IP -For arithmetic operators (\fB= != < > <= >=\fR), when \fIkey\fR is -specified but a particular record's \fIcolumn\fR does not contain -\fIkey\fR, the record is always omitted from the results. Thus, the -condition \fBother-config:mtu!=1500\fR matches records that have a -\fBmtu\fR key whose value is not 1500, but not those that lack an -\fBmtu\fR key. -.IP -For the set operators, when \fIkey\fR is specified but a particular -record's \fIcolumn\fR does not contain \fIkey\fR, the comparison is -done against an empty set. Thus, the condition -\fBother-config:mtu{!=}1500\fR matches records that have a \fBmtu\fR -key whose value is not 1500 and those that lack an \fBmtu\fR key. -.IP -Don't forget to escape \fB<\fR or \fB>\fR from interpretation by the -shell. -.IP -If \fB\-\-columns\fR is specified, only the requested columns are -listed, in the specified order. Otherwise all columns are listed, in -alphabetical order by column name. -.IP -The UUIDs shown for rows created in the same \fBovs\-vsctl\fR -invocation will be wrong. -. -.IP "[\fB\-\-if\-exists\fR] [\fB\-\-id=@\fIname\fR] \fBget \fItable record \fR[\fIcolumn\fR[\fB:\fIkey\fR]]..." -Prints the value of each specified \fIcolumn\fR in the given -\fIrecord\fR in \fItable\fR. For map columns, a \fIkey\fR may -optionally be specified, in which case the value associated with -\fIkey\fR in the column is printed, instead of the entire map. -.IP -Without \fB\-\-if\-exists\fR, it is an error if \fIrecord\fR does not -exist or \fIkey\fR is specified, if \fIkey\fR does not exist in -\fIrecord\fR. With \fB\-\-if\-exists\fR, a missing \fIrecord\fR -yields no output and a missing \fIkey\fR prints a blank line. -.IP -If \fB@\fIname\fR is specified, then the UUID for \fIrecord\fR may be -referred to by that name later in the same \fBovs\-vsctl\fR -invocation in contexts where a UUID is expected. -.IP -Both \fB\-\-id\fR and the \fIcolumn\fR arguments are optional, but -usually at least one or the other should be specified. If both are -omitted, then \fBget\fR has no effect except to verify that -\fIrecord\fR exists in \fItable\fR. -.IP -\fB\-\-id\fR and \fB\-\-if\-exists\fR cannot be used together. -. -.IP "[\fB\-\-if\-exists\fR] \fBset \fItable record column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..." -Sets the value of each specified \fIcolumn\fR in the given -\fIrecord\fR in \fItable\fR to \fIvalue\fR. For map columns, a -\fIkey\fR may optionally be specified, in which case the value -associated with \fIkey\fR in that column is changed (or added, if none -exists), instead of the entire map. -.IP -Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not -exist. With \fB\-\-if-exists\fR, this command does nothing if -\fIrecord\fR does not exist. -. -.IP "[\fB\-\-if\-exists\fR] \fBadd \fItable record column \fR[\fIkey\fB=\fR]\fIvalue\fR..." -Adds the specified value or key-value pair to \fIcolumn\fR in -\fIrecord\fR in \fItable\fR. If \fIcolumn\fR is a map, then \fIkey\fR -is required, otherwise it is prohibited. If \fIkey\fR already exists -in a map column, then the current \fIvalue\fR is not replaced (use the -\fBset\fR command to replace an existing value). -.IP -Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not -exist. With \fB\-\-if-exists\fR, this command does nothing if -\fIrecord\fR does not exist. -. -.IP "[\fB\-\-if\-exists\fR] \fBremove \fItable record column \fR\fIvalue\fR..." -.IQ "[\fB\-\-if\-exists\fR] \fBremove \fItable record column \fR\fIkey\fR..." -.IQ "[\fB\-\-if\-exists\fR] \fBremove \fItable record column \fR\fIkey\fB=\fR\fIvalue\fR..." -Removes the specified values or key-value pairs from \fIcolumn\fR in -\fIrecord\fR in \fItable\fR. The first form applies to columns that -are not maps: each specified \fIvalue\fR is removed from the column. -The second and third forms apply to map columns: if only a \fIkey\fR -is specified, then any key-value pair with the given \fIkey\fR is -removed, regardless of its value; if a \fIvalue\fR is given then a -pair is removed only if both key and value match. -.IP -It is not an error if the column does not contain the specified key or -value or pair. -.IP -Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not -exist. With \fB\-\-if-exists\fR, this command does nothing if -\fIrecord\fR does not exist. -. -.IP "[\fB\-\-if\-exists\fR] \fBclear\fR \fItable record column\fR..." -Sets each \fIcolumn\fR in \fIrecord\fR in \fItable\fR to the empty set -or empty map, as appropriate. This command applies only to columns -that are allowed to be empty. -.IP -Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not -exist. With \fB\-\-if-exists\fR, this command does nothing if -\fIrecord\fR does not exist. -. -.IP "[\fB\-\-id=@\fIname\fR] \fBcreate\fR \fItable column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..." -Creates a new record in \fItable\fR and sets the initial values of -each \fIcolumn\fR. Columns not explicitly set will receive their -default values. Outputs the UUID of the new row. -.IP -If \fB@\fIname\fR is specified, then the UUID for the new row may be -referred to by that name elsewhere in the same \fBovs\-vsctl\fR -invocation in contexts where a UUID is expected. Such references may -precede or follow the \fBcreate\fR command. -.IP -Records in the Open vSwitch database are significant only when they -can be reached directly or indirectly from the \fBOpen_vSwitch\fR -table. Except for records in the \fBQoS\fR or \fBQueue\fR tables, -records that are not reachable from the \fBOpen_vSwitch\fR table are -automatically deleted from the database. This deletion happens -immediately, without waiting for additional \fBovs\-vsctl\fR commands -or other database activity. Thus, a \fBcreate\fR command must -generally be accompanied by additional commands \fIwithin the same -\fBovs\-vsctl\fI invocation\fR to add a chain of references to the -newly created record from the top-level \fBOpen_vSwitch\fR record. -The \fBEXAMPLES\fR section gives some examples that show how to do -this. -. -.IP "\fR[\fB\-\-if\-exists\fR] \fBdestroy \fItable record\fR..." -Deletes each specified \fIrecord\fR from \fItable\fR. Unless -\fB\-\-if\-exists\fR is specified, each \fIrecord\fRs must exist. -.IP "\fB\-\-all destroy \fItable\fR" -Deletes all records from the \fItable\fR. -.IP -The \fBdestroy\fR command is only useful for records in the \fBQoS\fR -or \fBQueue\fR tables. Records in other tables are automatically -deleted from the database when they become unreachable from the -\fBOpen_vSwitch\fR table. This means that deleting the last reference -to a record is sufficient for deleting the record itself. For records -in these tables, \fBdestroy\fR is silently ignored. See the -\fBEXAMPLES\fR section below for more information. -. -.IP "\fBwait\-until \fItable record \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..." -Waits until \fItable\fR contains a record named \fIrecord\fR whose -\fIcolumn\fR equals \fIvalue\fR or, if \fIkey\fR is specified, whose -\fIcolumn\fR contains a \fIkey\fR with the specified \fIvalue\fR. Any -of the operators \fB!=\fR, \fB<\fR, \fB>\fR, \fB<=\fR, or \fB>=\fR may -be substituted for \fB=\fR to test for inequality, less than, greater -than, less than or equal to, or greater than or equal to, -respectively. (Don't forget to escape \fB<\fR or \fB>\fR from -interpretation by the shell.) -.IP -If no \fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR arguments are given, -this command waits only until \fIrecord\fR exists. If more than one -such argument is given, the command waits until all of them are -satisfied. -.IP -Usually \fBwait\-until\fR should be placed at the beginning of a set -of \fBovs\-vsctl\fR commands. For example, \fBwait\-until bridge br0 -\-\- get bridge br0 datapath_id\fR waits until a bridge named -\fBbr0\fR is created, then prints its \fBdatapath_id\fR column, -whereas \fBget bridge br0 datapath_id \-\- wait\-until bridge br0\fR -will abort if no bridge named \fBbr0\fR exists when \fBovs\-vsctl\fR -initially connects to the database. -.IP -Consider specifying \fB\-\-timeout=0\fR along with -\fB\-\-wait\-until\fR, to prevent \fBovs\-vsctl\fR from terminating -after waiting only at most 5 seconds. -.IP "\fBcomment \fR[\fIarg\fR]..." -This command has no effect on behavior, but any database log record -created by the command will include the command and its arguments. +.so lib/db-ctl-base.man .SH "EXAMPLES" Create a new bridge named br0 and add port eth0 to it: .IP