<?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>
      The OVSDB protocol specified in RFC 7047 does not provide a way for an
      OVSDB client to find out about some kinds of configuration changes, such
      as about databases added or removed while a client is connected to the
      server, or databases changing between read/write and read-only due to a
      transition between active and backup roles.  This table provides a
      solution: clients can monitor the table's contents to find out about
      important changes.
    </p>

    <p>
      Traditionally, <code>ovsdb-server</code> disconnects all of its clients
      when a significant configuration change occurs, because this prompts a
      well-written client to reassess what is available from the server when it
      reconnects.  Because this table provides an alternative and more
      efficient way to find out about those changes, OVS 2.9 also introduces
      the <code>set_db_change_aware</code> RPC, documented in
      <code>ovsdb-server</code>(7), to allow clients to suppress this
      disconnection behavior.
    </p>

    <p>
      When a database is removed from the server, in addition to
      <code>Database</code> table updates, the server sends
      <code>canceled</code> messages, as described in RFC 7047 section 4.1.4,
      in reply to outstanding transactions for the removed database.  The
      server also cancels any outstanding monitoring initiated by
      <code>monitor</code> or <code>monitor_cond</code> requested on the
      removed database, sending the <code>monitor_canceled</code> RPC described
      in <code>ovsdb-server</code>(7).  Only clients that disable disconnection
      with <code>set_db_change_aware</code> receive these messages.
    </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="model">
      The storage model: <code>standalone</code> for a standalone or
      active-backup database, <code>clustered</code> for a clustered database,
      <code>relay</code> for a relay database.
    </column>

    <column name="schema">
      The database schema, as a JSON string.  In the case of a clustered
      database, this is empty until it finishes joining its cluster.  In the
      case of a relay database, this is empty until it connects to the relay
      source.
    </column>

    <column name="connected">
      True if the database is connected to its storage.  A standalone database
      is always connected.  A clustered database is connected if the server is
      in contact with a majority of its cluster.  A relay database is connected
      if the server is in contact with the relay source, i.e. is connected to
      the server it syncs from.  An unconnected database cannot be modified and
      its data might be unavailable or stale.
    </column>

    <group title="Clustered Databases">
      <p>
        These columns are most interesting and in some cases only relevant for
        clustered databases, that is, those where the <ref column="model"/>
        column is <code>clustered</code>.
      </p>

      <column name="leader">
        True if the database is the leader in its cluster.  For a standalone or
        active-backup database, this is always true.  For a relay database,
        this is always false.
      </column>

      <column name="cid">
        The cluster ID for this database, which is the same for all of the
        servers that host this particular clustered database.  For a
        standalone, active-backup or relay database, this is empty.
      </column>

      <column name="sid">
        The server ID for this database, different for each server that hosts a
        particular clustered database.  A server that hosts more than one
        clustered database will have a different <code>sid</code> in each one.
        For a standalone, active-backup or relay database, this is empty.
      </column>

      <column name="index">
        <p>
          For a clustered database, the index of the log entry currently
          exposed to clients.  For a given server, this increases
          monotonically.  When a client switches from one server to another in
          a cluster, it can ensure that it never sees an older snapshot of data
          by avoiding servers that have <ref column="index"/> less than the
          largest value they have already observed.
        </p>

        <p>
          For a standalone, active-backup or relay database, this is empty.
        </p>
      </column>
    </group>
  </table>
</database>
