ovsdb/SPECS

   1          ===================================================
   2           Open vSwitch Configuration Database Specification
   3          ===================================================
   4
   5 Basic Notation
   6 --------------
   7
   8 The descriptions below use the following shorthand notations for JSON
   9 values.  Additional notation is presented later.
  10
  11 <string>
  12
  13     A JSON string.
  14
  15 <id>
  16
  17     A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*.
  18
  19     <id>s that begin with _ are reserved to the implementation and may
  20     not be used by the user.
  21
  22 <boolean>
  23
  24     A JSON true or false value.
  25
  26 <number>
  27
  28     A JSON number.
  29
  30 <integer>
  31
  32     A JSON number with an integer value, within a certain range
  33     (currently -2**63...+2**63-1).
  34
  35 <value>
  36
  37     Any JSON value.
  38
  39 Schema Format
  40 -------------
  41
  42 An Open vSwitch configuration database consists of a set of tables,
  43 each of which has a number of columns and zero or more rows.  A schema
  44 is represented by <database-schema>, as described below.
  45
  46 <database-schema>
  47
  48     A JSON object with the following members:
  49
  50         "name": <id>                            required
  51         "comment": <string>                     optional
  52         "tables": {<id>: <table-schema>, ...}   required
  53
  54     The "name" identifies the database as a whole.  The "comment"
  55     optionally provides more information about the database.  The
  56     value of "tables" is a JSON object whose names are table names and
  57     whose values are <table-schema>s.
  58
  59 <table-schema>
  60
  61     A JSON object with the following members:
  62
  63         "comment": <string>                       optional
  64         "columns": {<id>: <column-schema>, ...}   required
  65
  66     The "comment" optionally provides information about this table for
  67     a human reader.  The value of "columns" is a JSON object whose
  68     names are column names and whose values are <column-schema>s.
  69
  70     Every table has the following columns whose definitions are not
  71     included in the schema:
  72
  73         "_uuid": This column, which contains exactly one UUID value,
  74         is initialized to a random value by the database engine when
  75         it creates a row.  It is read-only, and its value never
  76         changes during the lifetime of a row.
  77
  78         "_version": Like "_uuid", this column contains exactly one
  79         UUID value, initialized to a random value by the database
  80         engine when it creates a row, and it is read-only.  However,
  81         its value changes to a new random value whenever any other
  82         field in the row changes.  Furthermore, its value is
  83         ephemeral: when the database is closed and reopened, or when
  84         the database process is stopped and then started again, each
  85         "_version" also changes to a new random value.
  86
  87 <column-schema>
  88
  89     A JSON object with the following members:
  90
  91         "comment": <string>                       optional
  92         "type": <type>                            required
  93         "ephemeral": <boolean>                    optional
  94
  95     The "comment" optionally provides information about this column
  96     for a human reader.  The "type" specifies the type of data stored
  97     in this column.  If "ephemeral" is specified as true, then this
  98     column's values are not guaranteed to be durable; they may be lost
  99     when the database restarts.
 100
 101 <type>
 102
 103     The type of a database column.  Either an <atomic-type> or a JSON
 104     object that describes the type of a database column, with the
 105     following members:
 106
 107         "key": <atomic-type>               required
 108         "value": <atomic-type>             optional
 109         "min": <integer>                   optional
 110         "max": <integer> or "unlimited"    optional
 111
 112     If "min" or "max" is not specified, each defaults to 1.  If "max"
 113     is specified as "unlimited", then there is no specified maximum
 114     number of elements, although the implementation will enforce some
 115     limit.  After considering defaults, "min" must be at least 0,
 116     "max" must be at least 1, and "max" must be greater than or equal
 117     to "min".
 118
 119     If "min" and "max" are both 1 and "value" is not specified, the
 120     type is the scalar type specified by "key".
 121
 122     If "min" is not 1 or "max" is not 1, or both, and "value" is not
 123     specified, the type is a set of scalar type "key".
 124
 125     If "value" is specified, the type is a map from type "key" to type
 126     "value".
 127
 128 <atomic-type>
 129
 130     One of the strings "integer", "real", "boolean", "string", or
 131     "uuid", representing the specified scalar type.
 132
 133 Wire Protocol
 134 -------------
 135
 136 The database wire protocol is implemented in JSON-RPC 1.0.  It
 137 consists of the following JSON-RPC methods:
 138
 139 get_schema
 140 ..........
 141
 142 Request object members:
 143
 144     "method": "get_schema"            required
 145     "params": []                      required
 146     "id": any JSON value except null  required
 147
 148 Response object members:
 149
 150     "result": <database-schema>
 151     "error": null
 152     "id": same "id" as request
 153
 154 This operation retrieves a <database-schema> that describes the
 155 hosted database.
 156
 157 transact
 158 ........
 159
 160 Request object members:
 161
 162     "method": "transact"              required
 163     "params": [<operation>*]          required
 164     "id": any JSON value except null  required
 165
 166 Response object members:
 167
 168     "result": [<object>*]
 169     "error": null
 170     "id": same "id" as request
 171
 172 The "params" array for this method consists of zero or more JSON
 173 objects, each of which represents a single database operation.  The
 174 "Operations" section below describes the valid operations.
 175
 176 The value of "id" must be unique among all in-flight transactions
 177 within the current JSON-RPC session.  Otherwise, the server may return
 178 a JSON-RPC error.
 179
 180 The database server executes each of the specified operations in the
 181 specified order, except that if an operation fails, then the remaining
 182 operations are not executed.
 183
 184 The set of operations is executed as a single atomic, consistent,
 185 isolated transaction.  The transaction is committed only if every
 186 operation succeeds.  Durability of the commit is not guaranteed unless
 187 the "commit" operation, with "durable" set to true, is included in the
 188 operation set (see below).
 189
 190 Regardless of whether errors occur, the response is always a JSON-RPC
 191 response with null "error" and a "result" member that is an array with
 192 the same number of elements as "params".  Each element of the "result"
 193 array corresponds to the same element of the "params" array.  The
 194 "result" array elements may be interpreted as follows:
 195
 196     - A JSON object that does not contain an "error" member indicates
 197       that the operation completed successfully.  The specific members
 198       of the object are specified below in the descriptions of
 199       individual operations.  Some operations do not produce any
 200       results, in which case the object will have no members.
 201
 202     - A JSON object that contains an "error" member indicates that the
 203       operation completed with an error.  The value of the "error"
 204       member is a short string, specified in this document, that
 205       broadly indicates the class of the error.  Besides the ones
 206       listed for a specific operation, any operation may result in one
 207       the following "error"s:
 208
 209       "error": "resources exhausted"
 210
 211           The operation or the transaction requires more resources
 212           (memory, disk, CPU, etc.) than are currently available to
 213           the database server.
 214
 215       "error": "syntax error"
 216
 217           The operation is not specified correctly: a required request
 218           object member is missing, an unknown or unsupported request
 219           object member is present, the operation attempts to act on a
 220           table that does not exist, the operation modifies a
 221           read-only table column, etc.
 222
 223       Database implementations may use "error" strings not specified
 224       in this document to indicate errors that do not fit into any of
 225       the specified categories.
 226
 227       Optionally, the object may include a "details" member, whose
 228       value is a string that describes the error in more detail for
 229       the benefit of a human user or administrator.  The object may
 230       also have other members that describe the error in more detail.
 231       This document does not specify the names or values of these
 232       members.
 233
 234     - A JSON null value indicates that the operation was not attempted
 235       because a prior operation failed.
 236
 237 In general, "result" contains some number of successful results,
 238 possibly followed by an error, in turn followed by enough JSON null
 239 values to match the number of elements in "params".  There is one
 240 exception: if all of the operations succeed, but the results cannot be
 241 committed (e.g. due to I/O errors), then "result" will have one more
 242 element than "params", with the additional element describing the
 243 error.
 244
 245 If "params" contains one or more "wait" operations, then the
 246 transaction may take an arbitrary amount of time to complete.  The
 247 database implementation must be capable of accepting, executing, and
 248 replying to other transactions and other JSON-RPC requests while a
 249 transaction or transactions containing "wait" operations are
 250 outstanding on the same or different JSON-RPC sessions.
 251
 252 The section "Notation for the Wire Protocol" below describes
 253 additional notation for use with the wire protocol.  After that, the
 254 "Operations" section describes each operation.
 255
 256 cancel
 257 ......
 258
 259 Request object members:
 260
 261     "method": "cancel"                              required
 262     "params": [the "id" for an outstanding request] required
 263     "id": null                                      required
 264
 265 Response object members:
 266
 267     <no response>
 268
 269 This JSON-RPC notification instructs the database server to
 270 immediately complete or cancel the "transact" request whose "id" is
 271 the same as the notification's "params" value.
 272
 273 If the "transact" request can be completed immediately, then the
 274 server sends a response in the form described for "transact", above.
 275 Otherwise, the server sends a JSON-RPC error response of the following
 276 form:
 277
 278     "result": null
 279     "error": "canceled"
 280     "id": the request "id" member
 281
 282 The "cancel" notification itself has no reply.
 283
 284 monitor
 285 .......
 286
 287 Request object members:
 288
 289     "method": "monitor"                        required
 290     "params": [<value>, <monitor-requests>]    required
 291     "id": any JSON value except null           required
 292
 293 <monitor-requests> is an object that maps from a table name to a
 294 <monitor-request>.
 295
 296 Each <monitor-request> is an object with the following members:
 297
 298     "columns": [<column>*]            optional
 299     "select": <monitor-select>        optional
 300
 301 <monitor-select> is an object with the following members:
 302
 303     "initial": <boolean>              optional
 304     "insert": <boolean>               optional
 305     "delete": <boolean>               optional
 306     "modify": <boolean>               optional
 307
 308 Response object members:
 309
 310     "result": <table-updates>
 311     "error": null
 312     "id": same "id" as request
 313
 314 This JSON-RPC request enables a client to replicate tables or subsets
 315 of tables.  Each <monitor-request> specifies a table to be replicated.
 316 The JSON-RPC response to the "monitor" includes the initial contents
 317 of each table.  Afterward, when changes to those tables are committed,
 318 the changes are automatically sent to the client using the "update"
 319 monitor notification.  This monitoring persists until the JSON-RPC
 320 session terminates or until the client sends a "monitor_cancel"
 321 JSON-RPC request.
 322
 323 Each <monitor-request> describes how to monitor a table:
 324
 325     The circumstances in which an "update" notification is sent for a
 326     row within the table are determined by <monitor-select>:
 327
 328         If "initial" is omitted or true, every row in the table is
 329         sent as part of the reply to the "monitor" request.
 330
 331         If "insert" is omitted or true, "update" notifications are
 332         sent for rows newly inserted into the table.
 333
 334         If "delete" is omitted or true, "update" notifications are
 335         sent for rows deleted from the table.
 336
 337         If "modify" is omitted or true, "update" notifications are
 338         sent whenever when a row in the table is modified.
 339
 340     The "columns" member specifies the columns whose values are
 341     monitored.  If "columns" is omitted, all columns in the table,
 342     except for "_uuid", are monitored.
 343
 344 The "result" in the JSON-RPC response to the "monitor" request is a
 345 <table-updates> object (see below) that contains the contents of the
 346 tables for which "initial" rows are selected.  If no tables' initial
 347 contents are requested, then "result" is an empty object.
 348
 349 update
 350 ......
 351
 352 Notification object members:
 353
 354     "method": "update"
 355     "params": [<value>, <table-updates>]
 356     "id": null
 357
 358 The <value> in "params" is the same as the value passed as the <value>
 359 in "params" for the "monitor" request.
 360
 361 <table-updates> is an object that maps from a table name to a
 362 <table-update>.
 363
 364 A <table-update> is an object that maps from the row's UUID (as a
 365 36-byte string) to a <row-update> object.
 366
 367 A <row-update> is an object with the following members:
 368
 369     "old": <row>         present for "delete" and "modify" updates
 370     "new": <row>         present for "initial", "insert", and "modify" updates
 371
 372 This JSON-RPC notification is sent from the server to the client to
 373 tell it about changes to a monitored table (or the initial state of a
 374 modified table).  Each table in which one or more rows has changed (or
 375 whose initial view is being presented) is represented in "updates".
 376 Each row that has changed (or whose initial view is being presented)
 377 is represented in its <table-update> as a member with its name taken
 378 from the row's _uuid member.  The corresponding value is a
 379 <row-update>:
 380
 381     The "old" member is present for "delete" and "modify" updates.
 382     For "delete" updates, each monitored column is included.  For
 383     "modify" updates, the prior value of each monitored column whose
 384     value has changed is included (monitored columns that have not
 385     changed are represented in "new").
 386
 387     The "new" member is present for "initial", "insert", and "modify"
 388     updates.  For "initial" and "insert" updates, each monitored
 389     column is included.  For "modify" updates, the new value of each
 390     monitored column is included.
 391
 392 monitor_cancel
 393 ..............
 394
 395 Request object members:
 396
 397     "method": "monitor_cancel"                              required
 398     "params": [<value>]                                     required
 399     "id": any JSON value except null                        required
 400
 401 Response object members:
 402
 403     "result": {}
 404     "error": null
 405     "id": the request "id" member
 406
 407 Cancels the ongoing table monitor request, identified by the <value>
 408 in "params" matching the <value> in "params" for an ongoing "monitor"
 409 request.  No more "update" messages will be sent for this table
 410 monitor.
 411
 412 echo
 413 ....
 414
 415 Request object members:
 416
 417     "method": "echo"                                required
 418     "params": JSON array with any contents          required
 419     "id": <value>                                   required
 420
 421 Response object members:
 422
 423     "result": same as "params"
 424     "error": null
 425     "id": the request "id" member
 426
 427 Both the JSON-RPC client and the server must implement this request.
 428
 429 This JSON-RPC request and response can be used to implement connection
 430 keepalives, by allowing the server to check that the client is still
 431 there or vice versa.
 432
 433
 434 Notation for the Wire Protocol
 435 ------------------------------
 436
 437 <table>
 438
 439     An <id> that names a table.
 440
 441 <column>
 442
 443     An <id> that names a table column.
 444
 445 <row>
 446
 447     A JSON object that describes a table row or a subset of a table
 448     row.  Each member is the name of a table column paired with the
 449     <value> of that column.
 450
 451 <value>
 452
 453     A JSON value that represents the value of a column in a table row,
 454     one of <atom>, a <set>, or a <map>.
 455
 456 <atom>
 457
 458     A JSON value that represents a scalar value for a column, one of
 459     <string>, <number>, <boolean>, <uuid>, <named-uuid>.
 460
 461 <set>
 462
 463     A 2-element JSON array that represents a database set value.  The
 464     first element of the array must be the string "set" and the second
 465     element must be an array of zero or more <atom>s giving the values
 466     in the set.  All of the <atom>s must have the same type.
 467
 468 <map>
 469
 470     A 2-element JSON array that represents a database map value.  The
 471     first element of the array must be the string "map" and the second
 472     element must be an array of zero or more <pair>s giving the values
 473     in the map.  All of the <pair>s must have the same key and value
 474     types.
 475
 476     (JSON objects are not used to represent <map> because JSON only
 477     allows string names in an object.)
 478
 479 <pair>
 480
 481     A 2-element JSON array that represents a pair within a database
 482     map.  The first element is an <atom> that represents the key, the
 483     second element is an <atom> that represents the value.
 484
 485 <uuid>
 486
 487     A 2-element JSON array that represents a UUID.  The first element
 488     of the array must be the string "uuid" and the second element must
 489     be a 36-character string giving the UUID in the format described
 490     by RFC 4122.  For example, the following <uuid> represents the
 491     UUID 550e8400-e29b-41d4-a716-446655440000:
 492
 493         ["uuid", "550e8400-e29b-41d4-a716-446655440000"]
 494
 495 <named-uuid>
 496
 497     A 2-element JSON array that represents the UUID of a row inserted
 498     in a previous "insert" operation within the same transaction.  The
 499     first element of the array must be the string "named-uuid" and the
 500     second element must be the string specified on this "insert"
 501     operation's "uuid-name" or on a preceding "insert" within the same
 502     transaction.  For example, if this or a previous "insert"
 503     operation specified a "uuid-name" of "myrow", the following
 504     <named-uuid> represents the UUID created by that operation:
 505
 506         ["named-uuid", "myrow"]
 507
 508     A <named-uuid> may be used anywhere a <uuid> is valid.
 509
 510 <condition>
 511
 512     A 3-element JSON array of the form [<column>, <function>,
 513     <value>] that represents a test on a column value.
 514
 515     Except as otherwise specified below, <value> must have the same
 516     type as <column>.
 517
 518     The meaning depends on the type of <column>:
 519
 520         integer
 521         real
 522
 523             <function> must be "<", "<=", "==", "!=", ">=", ">",
 524             "includes", or "excludes".
 525
 526             The test is true if the column's value satisfies the
 527             relation <function> <value>, e.g. if the column has value
 528             1 and <value> is 2, the test is true if <function> is "<",
 529             "<=" or "!=", but not otherwise.
 530
 531             "includes" is equivalent to "=="; "excludes" is equivalent
 532             to "!=".
 533
 534         boolean
 535         string
 536         uuid
 537
 538             <function> must be "!=", "==", "includes", or "excludes".
 539
 540             If <function> is "==" or "includes", the test is true if
 541             the column's value equals <value>.  If <function> is "!="
 542             or "excludes", the test is inverted.
 543
 544         set
 545         map
 546
 547             <function> must be "!=", "==", "includes", or "excludes".
 548
 549             If <function> is "==", the test is true if the column's
 550             value contains exactly the same values (for sets) or pairs
 551             (for maps).  If <function> is "!=", the test is inverted.
 552
 553             If <function> is "includes", the test is true if the
 554             column's value contains all of the values (for sets) or
 555             pairs (for maps) in <value>.  The column's value may also
 556             contain other values or pairs.
 557
 558             If <function> is "excludes", the test is true if the
 559             column's value does not contain any of the values (for
 560             sets) or pairs (for maps) in <value>.  The column's value
 561             may contain other values or pairs not in <value>.
 562
 563             If <function> is "includes" or "excludes", then the
 564             required type of <value> is slightly relaxed, in that it
 565             may have fewer than the minimum number of elements
 566             specified by the column's type.  If <function> is
 567             "excludes", then the required type is additionally relaxed
 568             in that <value> may have more than the maximum number of
 569             elements specified by the column's type.
 570
 571 <function>
 572
 573     One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".
 574
 575 Operations
 576 ----------
 577
 578 Each of the available operations is described below.
 579
 580 insert
 581 ......
 582
 583 Request object members:
 584
 585     "op": "insert"          required
 586     "table": <table>        required
 587     "row": <row>            required
 588     "uuid-name": <string>   optional
 589
 590 Result object members:
 591
 592     "uuid": <uuid>
 593
 594 Semantics:
 595
 596     Inserts "row" into "table".  If "row" does not specify values
 597     for all the columns in "table", those columns receive default
 598     values.
 599
 600     The new row receives a new, randomly generated UUID, which is
 601     returned as the "uuid" member of the result.  If "uuid-name" is
 602     supplied, then the UUID is made available under that name to this
 603     operation and later operations within the same transaction.
 604
 605 select
 606 ......
 607
 608 Request object members:
 609
 610     "op": "select"                required
 611     "table": <table>              required
 612     "where": [<condition>*]       required
 613     "columns": [<column>*]        optional
 614
 615 Result object members:
 616
 617     "rows": [<row>*]
 618
 619 Semantics:
 620
 621     Searches "table" for rows that match all the conditions specified
 622     in "where".  If "where" is an empty array, every row in "table" is
 623     selected.
 624
 625     The "rows" member of the result is an array of objects.  Each
 626     object corresponds to a matching row, with each column
 627     specified in "columns" as a member, the column's name as the
 628     member name and its value as the member value.  If "columns"
 629     is not specified, all the table's columns are included.  If
 630     two rows of the result have the same values for all included
 631     columns, only one copy of that row is included in "rows".
 632     Specifying "_uuid" within "columns" will avoid dropping
 633     duplicates, since every row has a unique UUID.
 634
 635     The ordering of rows within "rows" is unspecified.
 636
 637 update
 638 ......
 639
 640 Request object members:
 641
 642     "op": "update"                required
 643     "table": <table>              required
 644     "where": [<condition>*]       required
 645     "row": <row>                  required
 646
 647 Result object members:
 648
 649     "count": <integer>
 650
 651 Semantics:
 652
 653     Updates rows in a table.
 654
 655     Searches "table" for rows that match all the conditions
 656     specified in "where".  For each matching row, changes the
 657     value of each column specified in "row" to the value for that
 658     column specified in "row".
 659
 660     The "_uuid" and "_version" columns of a table may not be directly
 661     updated with this operation.  Columns designated read-only in the
 662     schema also may not be updated.
 663
 664     The "count" member of the result specifies the number of rows
 665     that matched.
 666
 667 delete
 668 ......
 669
 670 Request object members:
 671
 672     "op": "delete"                required
 673     "table": <table>              required
 674     "where": [<condition>*]       required
 675
 676 Result object members:
 677
 678     "count": <integer>
 679
 680 Semantics:
 681
 682     Deletes all the rows from "table" that match all the conditions
 683     specified in "where".
 684
 685     The "count" member of the result specifies the number of deleted
 686     rows.
 687
 688 wait
 689 ....
 690
 691 Request object members:
 692
 693     "op": "wait"                        required
 694     "timeout": <integer>                optional
 695     "table": <table>                    required
 696     "where": [<condition>*]             required
 697     "columns": [<column>*]              required
 698     "until": "==" or "!="               required
 699     "rows": [<row>*]                    required
 700
 701 Result object members:
 702
 703     none
 704
 705 Semantics:
 706
 707     Waits until a condition becomes true.
 708
 709     If "until" is "==", checks whether the query on "table" specified
 710     by "where" and "columns", which is evaluated in the same way as
 711     specified for "select", returns the result set specified by
 712     "rows".  If it does, then the operation completes successfully.
 713     Otherwise, the entire transaction rolls back.  It is automatically
 714     restarted later, after a change in the database makes it possible
 715     for the operation to succeed.  The client will not receive a
 716     response until the operation permanently succeeds or fails.
 717
 718     If "until" is "!=", the sense of the test is negated.  That is, as
 719     long as the query on "table" specified by "where" and "columns"
 720     returns "rows", the transaction will be rolled back and restarted
 721     later.
 722
 723     If "timeout" is specified, then the transaction aborts after the
 724     specified number of milliseconds.  The transaction is guaranteed
 725     to be attempted at least once before it aborts.  A "timeout" of 0
 726     will abort the transaction on the first mismatch.
 727
 728 Errors:
 729
 730     "error": "not supported"
 731
 732         One or more of the columns in this table do not support
 733         triggers.  This error will not occur if "timeout" is 0.
 734
 735     "error": "timed out"
 736
 737         The "timeout" was reached before the transaction was able to
 738         complete.
 739
 740 commit
 741 ......
 742
 743 Request object members:
 744
 745     "op": "commit"                      required
 746     "durable": <boolean>                required
 747
 748 Result object members:
 749
 750     none
 751
 752 Semantics:
 753
 754     If "durable" is specified as true, then the transaction, if it
 755     commits, will be stored durably (to disk) before the reply is sent
 756     to the client.
 757
 758 Errors:
 759
 760     "error": "not supported"
 761
 762         When "durable" is true, this database implementation does not
 763         support durable commits.
 764
 765 abort
 766 .....
 767
 768 Request object members:
 769
 770     "op": "abort"                      required
 771
 772 Result object members:
 773
 774     (never succeeds)
 775
 776 Semantics:
 777
 778     Aborts the transaction with an error.  This may be useful for
 779     testing.
 780
 781 Errors:
 782
 783     "error": "aborted"
 784
 785         This operation always fails with this error.