ovsdb-server: Add support for a built-in _Server database.

The _Server database is valuable primarily because it provides database
clients a way to find out the details of changes to databases, schemas,
etc. in a granular, natural way.  Until now, the only way that the server
could notify clients about these kinds of changes was to close the session;
when the client reconnects, it is expected to reassess the server's state.
One way to provide this kind of granular information would be to add
specific JSON-RPC requests to obtain notifications for different kinds of
changes, but since ovsdb-server already provides granular and flexible
notification support for databases, using a database for the purpose is
convenient and avoids duplicating functionality.

Initially this database only reports databases' names and schemas, but
when clustering support is added in a later commit it will also report
important aspects of clustering and cluster status.  Thus, this database
also reduces the need to add JSON-RPC calls to retrieve information about
new features.

Signed-off-by: Ben Pfaff <blp@ovn.org>

1 files changed, 31 insertions, 0 deletions

diff --git a/ovsdb/_server.xml b/ovsdb/_server.xml
new file mode 100644
index 000000000..a55beb9bd
--- /dev/null
+++ b/ovsdb/_server.xml
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="utf-8"?>
+<database name="ovsdb-server" title="ovsdb-server _Server schema">
+  <p>
+    Every <code>ovsdb-server</code> (version 2.9 or later) always hosts an
+    instance of this schema, which holds information on the status and
+    configuration of the server itself.  This database is read-only.  This
+    manpage describes the schema for this database.
+  </p>
+
+  <table name="Database" title="Databases.">
+    <p>
+      This table describes the databases hosted by the database server, with
+      one row per database.  As its database configuration and status changes,
+      the server automatically and immediately updates the table to match.
+    </p>
+    <p>
+      Clients can use the <code>_uuid</code> column in this table as a
+      generation number.  The server generates a fresh <code>_uuid</code> every
+      time it adds a database, so that removing and then re-adding a database
+      to the server causes its row <code>_uuid</code> to change.
+    </p>
+
+    <column name="name">
+      The database's name, as specified in its schema.
+    </column>
+
+    <column name="schema">
+      The database schema, as a JSON string.
+    </column>
+  </table>
+</database>