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 "tables" is a JSON object whose
  68     names are table 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 a "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 a previous "insert"
 501     operation's "uuid-name".  For example, if a previous "insert"
 502     operation specified a "uuid-name" of "myrow", the following
 503     <named-uuid> represents the UUID created by that operation:
 504
 505         ["named-uuid", "myrow"]
 506
 507 <condition>
 508
 509     A 3-element JSON array of the form [<column>, <function>,
 510     <value>] that represents a test on a column value.
 511
 512     Except as otherwise specified below, <value> must have the same
 513     type as <column>.
 514
 515     The meaning depends on the type of <column>:
 516
 517         integer
 518         real
 519
 520             <function> must be "<", "<=", "==", "!=", ">=", ">",
 521             "includes", or "excludes".
 522
 523             The test is true if the column's value satisfies the
 524             relation <function> <value>, e.g. if the column has value
 525             1 and <value> is 2, the test is true if <function> is "<",
 526             "<=" or "!=", but not otherwise.
 527
 528             "includes" is equivalent to "=="; "excludes" is equivalent
 529             to "!=".
 530
 531         boolean
 532         string
 533         uuid
 534
 535             <function> must be "!=", "==", "includes", or "excludes".
 536
 537             If <function> is "==" or "includes", the test is true if
 538             the column's value equals <value>.  If <function> is "!="
 539             or "excludes", the test is inverted.
 540
 541         set
 542         map
 543
 544             <function> must be "!=", "==", "includes", or "excludes".
 545
 546             If <function> is "==", the test is true if the column's
 547             value contains exactly the same values (for sets) or pairs
 548             (for maps).  If <function> is "!=", the test is inverted.
 549
 550             If <function> is "includes", the test is true if the
 551             column's value contains all of the values (for sets) or
 552             pairs (for maps) in <value>.  The column's value may also
 553             contain other values or pairs.
 554
 555             If <function> is "excludes", the test is true if the
 556             column's value does not contain any of the values (for
 557             sets) or pairs (for maps) in <value>.  The column's value
 558             may contain other values or pairs not in <value>.
 559
 560             If <function> is "includes" or "excludes", then the
 561             required type of <value> is slightly relaxed, in that it
 562             may have fewer than the minimum number of elements
 563             specified by the column's type.  If <function> is
 564             "excludes", then the required type is additionally relaxed
 565             in that <value> may have more than the maximum number of
 566             elements specified by the column's type.
 567
 568 <function>
 569
 570     One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".
 571
 572 Operations
 573 ----------
 574
 575 Each of the available operations is described below.
 576
 577 insert
 578 ......
 579
 580 Request object members:
 581
 582     "op": "insert"          required
 583     "table": <table>        required
 584     "row": <row>            required
 585     "uuid-name": <string>   optional
 586
 587 Result object members:
 588
 589     "uuid": <uuid>
 590
 591 Semantics:
 592
 593     Inserts "row" into "table".  If "row" does not specify values
 594     for all the columns in "table", those columns receive default
 595     values.
 596
 597     The new row receives a new, randomly generated UUID, which is
 598     returned as the "_uuid" member of the result.  If "uuid-name"
 599     is supplied, then the UUID is made available under that name
 600     to later operations within the same transaction.
 601
 602 select
 603 ......
 604
 605 Request object members:
 606
 607     "op": "select"                required
 608     "table": <table>              required
 609     "where": [<condition>*]       required
 610     "columns": [<column>*]        optional
 611
 612 Result object members:
 613
 614     "rows": [<row>*]
 615
 616 Semantics:
 617
 618     Searches "table" for rows that match all the conditions specified
 619     in "where".  If "where" is an empty array, every row in "table" is
 620     selected.
 621
 622     The "rows" member of the result is an array of objects.  Each
 623     object corresponds to a matching row, with each column
 624     specified in "columns" as a member, the column's name as the
 625     member name and its value as the member value.  If "columns"
 626     is not specified, all the table's columns are included.  If
 627     two rows of the result have the same values for all included
 628     columns, only one copy of that row is included in "rows".
 629     Specifying "_uuid" within "columns" will avoid dropping
 630     duplicates, since every row has a unique UUID.
 631
 632     The ordering of rows within "rows" is unspecified.
 633
 634 update
 635 ......
 636
 637 Request object members:
 638
 639     "op": "update"                required
 640     "table": <table>              required
 641     "where": [<condition>*]       required
 642     "row": <row>                  required
 643
 644 Result object members:
 645
 646     "count": <integer>
 647
 648 Semantics:
 649
 650     Updates rows in a table.
 651
 652     Searches "table" for rows that match all the conditions
 653     specified in "where".  For each matching row, changes the
 654     value of each column specified in "row" to the value for that
 655     column specified in "row".
 656
 657     The "_uuid" and "_version" columns of a table may not be updated.
 658     Columns designated read-only in the schema also may not be
 659     updated.
 660
 661     The "count" member of the result specifies the number of rows
 662     that matched.
 663
 664 delete
 665 ......
 666
 667 Request object members:
 668
 669     "op": "delete"                required
 670     "table": <table>              required
 671     "where": [<condition>*]       required
 672
 673 Result object members:
 674
 675     "count": <integer>
 676
 677 Semantics:
 678
 679     Deletes all the rows from "table" that match all the conditions
 680     specified in "where".
 681
 682     The "count" member of the result specifies the number of deleted
 683     rows.
 684
 685 wait
 686 ....
 687
 688 Request object members:
 689
 690     "op": "wait"                        required
 691     "timeout": <integer>                optional
 692     "table": <table>                    required
 693     "where": [<condition>*]             required
 694     "columns": [<column>*]              required
 695     "until": "==" or "!="               required
 696     "rows": [<row>*]                    required
 697
 698 Result object members:
 699
 700     none
 701
 702 Semantics:
 703
 704     Waits until a condition becomes true.
 705
 706     If "until" is "==", checks whether the query on "table" specified
 707     by "where" and "columns", which is evaluated in the same way as
 708     specified for "select", returns the result set specified by
 709     "rows".  If it does, then the operation completes successfully.
 710     Otherwise, the entire transaction rolls back.  It is automatically
 711     restarted later, after a change in the database makes it possible
 712     for the operation to succeed.  The client will not receive a
 713     response until the operation permanently succeeds or fails.
 714
 715     If "until" is "!=", the sense of the test is negated.  That is, as
 716     long as the query on "table" specified by "where" and "columns"
 717     returns "rows", the transaction will be rolled back and restarted
 718     later.
 719
 720     If "timeout" is specified, then the transaction aborts after the
 721     specified number of milliseconds.  The transaction is guaranteed
 722     to be attempted at least once before it aborts.  A "timeout" of 0
 723     will abort the transaction on the first mismatch.
 724
 725 Errors:
 726
 727     "error": "not supported"
 728
 729         One or more of the columns in this table do not support
 730         triggers.  This error will not occur if "timeout" is 0.
 731
 732     "error": "timed out"
 733
 734         The "timeout" was reached before the transaction was able to
 735         complete.
 736
 737 commit
 738 ......
 739
 740 Request object members:
 741
 742     "op": "commit"                      required
 743     "durable": <boolean>                required
 744
 745 Result object members:
 746
 747     none
 748
 749 Semantics:
 750
 751     If "durable" is specified as true, then the transaction, if it
 752     commits, will be stored durably (to disk) before the reply is sent
 753     to the client.
 754
 755 Errors:
 756
 757     "error": "not supported"
 758
 759         When "durable" is true, this database implementation does not
 760         support durable commits.
 761
 762 abort
 763 .....
 764
 765 Request object members:
 766
 767     "op": "abort"                      required
 768
 769 Result object members:
 770
 771     (never succeeds)
 772
 773 Semantics:
 774
 775     Aborts the transaction with an error.  This may be useful for
 776     testing.
 777
 778 Errors:
 779
 780     "error": "aborted"
 781
 782         This operation always fails with this error.