Keys used in requests and responses

General

Streams

General replication

Synchronous replication

All IPROTO_RAFT_* keys are used only in IPROTO_RAFT* requests.

Events and subscriptions

Learn more about events and subscriptions in iproto.

SQL-specific

These keys are used with SQL within SQL-specific requests and responses like IPROTO_EXECUTE and IPROTO_PREPARE.

IPROTO_VERSION

Code: 0x54.

IPROTO_VERSION is an integer number reflecting the version of protocol that the client supports. The latest IPROTO_VERSION is 3.

IPROTO_FEATURES

Code: 0x55.

Available IPROTO_FEATURES are the following:

• IPROTO_FEATURE_STREAMS = 0 – streams support: IPROTO_STREAM_ID in the request header.
• IPROTO_FEATURE_TRANSACTIONS = 1 – transaction support: IPROTO_BEGIN, IPROTO_COMMIT, and IPROTO_ROLLBACK commands (with IPROTO_STREAM_ID in the request header). Learn more about sending transaction commands.
• IPROTO_FEATURE_ERROR_EXTENSION = 2 – MP_ERROR MsgPack extension support. Clients that don’t support this feature receive error responses for IPROTO_EVAL and IPROTO_CALL encoded to string error messages.
• IPROTO_FEATURE_WATCHERS = 3 – remote watchers support: IPROTO_WATCH, IPROTO_UNWATCH, and IPROTO_EVENT commands.

IPROTO_SYNC

Code: 0x01.

This is an unsigned integer that should be incremented so that it is unique in every request. This integer is also returned from box.session.sync().

The IPROTO_SYNC value of a response should be the same as the IPROTO_SYNC value of a request.

IPROTO_SCHEMA_VERSION

Code: 0x05.

Version of the database schema – an unsigned number that goes up when there is a major change in the schema.

In a request header, IPROTO_SCHEMA_VERSION is optional, so the version will not be checked if it is absent.

In a response header, IPROTO_SCHEMA_VERSION is always present, and it is up to the client to check if it has changed.

IPROTO_ITERATOR

Code: 0x14.

Possible values (see iterator_type.h):

IPROTO_STREAM_ID

Code: 0x0a.

Only used in streams. This is an unsigned number that should be unique in every stream.

In requests, IPROTO_STREAM_ID is useful for two things: ensuring that requests within transactions are done in separate groups, and ensuring strictly consistent execution of requests (whether or not they are within transactions).

In responses, IPROTO_STREAM_ID does not appear.

See Binary protocol – streams.

IPROTO_TXN_ISOLATION

IPROTO_TXN_ISOLATION is the transaction isolation level. It can take the following values:

• TXN_ISOLATION_DEFAULT = 0 – use the default level from box.cfg (default value)
• TXN_ISOLATION_READ_COMMITTED = 1 – read changes that are committed but not confirmed yet
• TXN_ISOLATION_READ_CONFIRMED = 2 – read confirmed changes
• TXN_ISOLATION_BEST_EFFORT = 3 – determine isolation level automatically

See Binary protocol – streams to learn more about stream transactions in the binary protocol.

IPROTO_REQUEST_TYPE

Code: 0x00.

The key is used both in requests and responses. It indicates the request or response type and has any request or response name for the value (example: IPROTO_AUTH). See requests and responses for client-server communication, replication, events and subscriptions, streams and interactive transactions.

IPROTO_ERROR

Code: 0x52.

In case of error, the response body contains IPROTO_ERROR and IPROTO_ERROR_24 instead of IPROTO_DATA.

To learn more about error responses, check the section Request and response format.

IPROTO_ERROR_24

Code: 0x31.

IPROTO_ERROR_24 is used in Tarantool versions before 2.4.1. The key contains the error in the string format.

Since Tarantool 2.4.1, Tarantool packs errors as the MP_ERROR MessagePack extension, which includes extra information. Two keys are passed in the error response body: IPROTO_ERROR and IPROTO_ERROR_24.

To learn more about error responses, check the section Request and response format.

IPROTO_TUPLE

Code: 0x21.

Multiple operations make use of this key in different ways:

IPROTO_FLAGS

Code: 0x09.

When it comes to replicating synchronous transactions, the IPROTO_FLAGS key is included in the header. The key contains an MP_UINT value of one or more bits:

• IPROTO_FLAG_COMMIT (0x01) is set if this is the last message for a transaction.
• IPROTO_FLAG_WAIT_SYNC (0x02) is set if this is the last message for a transaction which cannot be completed immediately.
• IPROTO_FLAG_WAIT_ACK (0x04) is set if this is the last message for a synchronous transaction.

Example:

IPROTO_TERM

Code: 0x53.

• The key is used in the IPROTO_RAFT_PROMOTE and IPROTO_RAFT_DEMOTE requests.
• Since version 2.11, the key is included in response to a heartbeat message. The term corresponds to the value of box.info.synchro.queue.term on the sender instance.

Vclock keys

The vclock (vector clock) is a log sequence number map that defines the version of the dataset stored on the node. In fact, it represents the number of logical operations executed on a specific node. A vclock looks like this:

There are five keys that correspond to vector clocks in different contexts of replication. They all have the MP_MAP type:

• IPROTO_VCLOCK (0x26) is passed to a new instance joining the replica set.
• IPROTO_VCLOCK_SYNC (0x5a) is used by replication heartbeats. The master sends its heartbeats, including this monotonically growing key, to a replica. Once the replica receives a heartbeat with a non-zero IPROTO_VCLOCK_SYNC value, it starts responding with the same value in all its acknowledgements. This key was introduced in version 2.11.
• IPROTO_BALLOT_VCLOCK (0x02) is included in the IPROTO_BALLOT message. IPROTO_BALLOT is sent in response to the IPROTO_VOTE request. This key was introduced in Tarantool 2.6.1.
• IPROTO_BALLOT_GC_VCLOCK (0x03) is also included in the IPROTO_BALLOT message. IPROTO_BALLOT is sent in response to the IPROTO_VOTE request. It is the vclock of the oldest WAL entry on the instance. Corresponds to box.info.gc().vclock. This key was introduced in Tarantool 2.6.1.
• IPROTO_RAFT_VCLOCK (0x03) is included in the IPROTO_RAFT message. It is present only on the instances in the “candidate” state (IPROTO_RAFT_STATE == 2).

IPROTO_BALLOT keys

All IPROTO_BALLOT_* keys are only used in the IPROTO_BALLOT requests. There have been the following name changes starting with versions Tarantool 2.7.3, Tarantool 2.8.2, and Tarantool 2.10.0:

• IPROTO_BALLOT_IS_RO_CFG (0x01) was formerly called IPROTO_BALLOT_IS_RO.
• IPROTO_BALLOT_IS_RO (0x04) was formerly called IPROTO_BALLOT_IS_LOADING.

IPROTO_METADATA

Code: 0x32.

Used with SQL within IPROTO_EXECUTE.

The key contains an array of column maps, with each column map containing at least IPROTO_FIELD_NAME (0x00) and MP_STR, and IPROTO_FIELD_TYPE (0x01) and MP_STR.

Additionally, if sql_full_metadata in the _session_settings system space is TRUE, then the array has these additional column maps which correspond to components described in the box.execute() section.

IPROTO_SQL_BIND

Code: 0x41.

Used with SQL within IPROTO_EXECUTE.

IPROTO_SQL_BIND is an array of parameter values to match ? placeholders or :name placeholders. It can contain values of any type, including MP_MAP.

• Values that are not MP_MAP replace the ? placeholders in the request.

• MP_MAP values must have the format {[name] = value}, where name is the named parameter in the request. Here is an example of such a request:

  tarantool> conn:execute('SELECT ?, ?, :name1, ?, :name2, :name1', {1, 2, {[':name1'] = 5}, 'str', {[':name2'] = true}})
  ---
  - metadata:
  - name: COLUMN_1
      type: integer
  - name: COLUMN_2
      type: integer
  - name: COLUMN_3
      type: integer
  - name: COLUMN_4
      type: text
  - name: COLUMN_5
      type: boolean
  - name: COLUMN_6
      type: boolean
  rows:
  - [1, 2, 5, 'str', true, 5]