ovsdb: Add support for online schema conversion.

With this change, "ovsdb-client convert" can be used to convert a database
from one schema to another without taking the database offline.

This can be useful to minimize downtime for a database during a software
upgrade.

Signed-off-by: Ben Pfaff <blp@ovn.org>
Acked-by: Justin Pettit <jpettit@ovn.org>

2 files changed, 44 insertions, 2 deletions

diff --git a/Documentation/ref/ovsdb-server.7.rst b/Documentation/ref/ovsdb-server.7.rst
index 2ed392fee..22b335bab 100644
--- a/Documentation/ref/ovsdb-server.7.rst
+++ b/Documentation/ref/ovsdb-server.7.rst
@@ -414,6 +414,41 @@ The reply is always the same::
     "error": null
     "id": same "id" as request
 
+4.1.17 Schema Conversion
+------------------------
+
+Open vSwitch 2.9 adds a new JSON-RPC request to convert an online database from
+one schema to another.  The request contains the following members::
+
+    "method": "convert"
+    "params": [<db-name>, <database-schema>]
+    "id": <nonnull-json-value>
+
+Upon receipt, the server converts database <db-name> to schema
+<database-schema>.  The schema's name must be <db-name>.  The conversion is
+atomic, consistent, isolated, and durable.  The data in the database must be
+valid when interpreted under <database-schema>, with only one exception: data
+for tables and columns that do not exist in the new schema are ignored.
+Columns that exist in <database-schema> but not in the database are set to
+their default values.  All of the new schema's constraints apply in full.
+
+If the conversion is successful, the server notifies clients that use the
+``set_db_change_aware`` RPC introduced in Open vSwitch 2.9 and cancels their
+outstanding transactions and monitors.  The server disconnects other clients,
+enabling them to notice the change when they reconnect.  The server sends the
+following reply::
+
+    "result": {}
+    "error": null
+    "id": same "id" as request
+
+If the conversion fails, then the server sends an error reply in the following
+form::
+
+    "result": null
+    "error": [<error>]
+    "id": same "id" as request
+
 5.1 Notation
 ------------
 
diff --git a/Documentation/ref/ovsdb.7.rst b/Documentation/ref/ovsdb.7.rst
index 25a6e5fc3..6adef7382 100644
--- a/Documentation/ref/ovsdb.7.rst
+++ b/Documentation/ref/ovsdb.7.rst
@@ -367,10 +367,17 @@ active-backup database, first stop the database server or servers, then use
 ``ovsdb-tool convert`` to convert it to the new schema, and then restart the
 database server.
 
+OVSDB also supports online database schema conversion.
+To convert a database online, use ``ovsdb-client convert``.
+The conversion is atomic, consistent, isolated, and durable.  ``ovsdb-server``
+disconnects any clients connected when the conversion takes place (except
+clients that use the ``set_db_change_aware`` Open vSwitch extension RPC).  Upon
+reconnection, clients will discover that the schema has changed.
+
 Schema versions and checksums (see Schemas_ above) can give hints about whether
 a database needs to be converted to a new schema.  If there is any question,
-though, the ``needs-conversion`` command on ``ovsdb-tool`` can provide a
-definitive answer.
+though, the ``needs-conversion`` command on ``ovsdb-tool`` and ``ovsdb-client``
+can provide a definitive answer.
 
 Working with Database History
 -----------------------------