Prompted by an IRC discussion.
Signed-off-by: Ben Pfaff <b...@ovn.org>
---
ovsdb/ovsdb-tool.1.in | 25 +++++++++++++++++++++++++
vswitchd/vswitch.xml | 11 ++---------
2 files changed, 27 insertions(+), 9 deletions(-)
diff --git a/ovsdb/ovsdb-tool.1.in b/ovsdb/ovsdb-tool.1.in
index a2f1f22..d01531e 100644
--- a/ovsdb/ovsdb-tool.1.in
+++ b/ovsdb/ovsdb-tool.1.in
@@ -62,6 +62,29 @@ specified, the compacted version is written as a new file
named
omitted, then the compacted version of the database replaces \fIdb\fR
in-place.
.
+.SS "Version Management Commands"
+.PP
+An OVSDB schema has a schema version number, and an OVSDB database
+embeds a particular version of an OVSDB schema. These version numbers
+take the form \fIx\fB.\fIy\fB.\fIz\fR, e.g. \fB1.2.3\fR. The OVSDB
+implementation does not enforce a particular version numbering scheme,
+but schemas managed within the Open vSwitch project use the following
+approach. Whenever the database schema is changed in a non-backward
+compatible way (e.g. deleting a column or a table), \fIx\fR is
+incremented (and \fIy\fR and \fIz\fR are reset to 0). When the
+database schema is changed in a backward compatible way (e.g. adding a
+new column), \fIy\fR is incremented (and \fIz\fR is reset to 0). When
+the database schema is changed cosmetically (e.g. reindenting its
+syntax), \fIz\fR is incremented.
+.
+.PP
+Some OVSDB databases and schemas, especially very old ones, do not
+have a version number.
+.
+.PP
+These commands work with different versions of OVSDB schemas and
+databases.
+.
.IP "\fBconvert\fI db schema \fR[\fItarget\fR]"
Reads \fIdb\fR, translating it into to the schema specified in
\fIschema\fR, and writes out the new interpretation. If \fItarget\fR
@@ -106,6 +129,8 @@ If \fIschema\fR or \fIdb\fR was created before schema
checksums were
introduced, then it will not have a checksum and this command
will print a blank line.
.
+.SS "Other Commands"
+.
.IP "\fBquery\fI db transaction\fR"
Opens \fIdb\fR, executes \fItransaction\fR on it, and prints the
results. The \fItransaction\fR must be a JSON array in the format of
diff --git a/vswitchd/vswitch.xml b/vswitchd/vswitch.xml
index b92b7c0..d10fc1d 100644
--- a/vswitchd/vswitch.xml
+++ b/vswitchd/vswitch.xml
@@ -501,15 +501,8 @@
<column name="db_version">
<p>
- The database schema version number in the form
- <code><var>major</var>.<var>minor</var>.<var>tweak</var></code>,
- e.g. <code>1.2.3</code>. Whenever the database schema is changed in
- a non-backward compatible way (e.g. deleting a column or a table),
- <var>major</var> is incremented. When the database schema is changed
- in a backward compatible way (e.g. adding a new column),
- <var>minor</var> is incremented. When the database schema is changed
- cosmetically (e.g. reindenting its syntax), <var>tweak</var> is
- incremented.
+ The database schema version number, e.g. <code>1.2.3</code>. See
+ ovsdb-tool(1) for an explanation of the numbering scheme.
</p>
<p>
--
2.10.2
_______________________________________________
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev
