- Messages
- ErrorResponse
- LogMessage
- ReadyForCommand
- RestoreReady
- CommandComplete
- Dump
- CommandDataDescription
- StateDataDescription
- Sync
- Restore
- RestoreBlock
- RestoreEof
- Execute
- Parse
- Data
- Dump Header
- Dump Block
- ServerKeyData
- ParameterStatus
- ClientHandshake
- ServerHandshake
- AuthenticationOK
- AuthenticationSASL
- AuthenticationSASLContinue
- AuthenticationSASLFinal
- AuthenticationSASLInitialResponse
- AuthenticationSASLResponse
- Terminate
Messages
Server Messages | |
Authentication is successful. | |
SASL authentication is required. | |
SASL authentication challenge. | |
SASL authentication final message. | |
Successful completion of a command. | |
Description of command data input and output. | |
Description of state data. | |
Command result data element. | |
Initial message of the database backup protocol | |
Single chunk of database backup data | |
Server error. | |
Server log message. | |
Server parameter value. | |
Server is ready for a command. | |
Successful response to the Restore message | |
Initial server connection handshake. | |
Opaque token identifying the server connection. | |
Client Messages | |
SASL authentication initial response. | |
SASL authentication response. | |
Initial client connection handshake. | |
Initiate database backup | |
Parse EdgeQL command(s). | |
Parse and/or execute a query. | |
Initiate database restore | |
Next block of database dump | |
End of database dump | |
Provide an explicit synchronization point. | |
Terminate the connection. |
ErrorResponse
Sent by: server.
Format:
struct ErrorResponse {
// Message type ('E').
uint8 mtype = 0x45;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// Message severity.
uint8<ErrorSeverity> severity;
// Message code.
uint32 error_code;
// Error message.
string message;
// Error attributes.
uint16 num_attributes;
KeyValue attributes[num_attributes];
};
enum ErrorSeverity {
ERROR = 0x78;
FATAL = 0xc8;
PANIC = 0xff;
};
See the list of error codes for all possible error codes.
Known headers:
0x0001
HINT
:str
– error hint.0x0002
DETAILS
:str
– error details.0x0101
SERVER_TRACEBACK
:str
– error traceback from server (is only sent in dev mode).0xFFF1
POSITION_START
– byte offset of the start of the error span.0xFFF2
POSITION_END
– byte offset of the end of the error span.0xFFF3
LINE_START
– one-based line number of the start of the error span.0xFFF4
COLUMN_START
– one-based column number of the start of the error span.0xFFF5
UTF16_COLUMN_START
– zero-based column number in UTF-16 encoding of the start of the error span.0xFFF6
LINE_END
– one-based line number of the start of the error span.0xFFF7
COLUMN_END
– one-based column number of the start of the error span.0xFFF8
UTF16_COLUMN_END
– zero-based column number in UTF-16 encoding of the end of the error span.0xFFF9
CHARACTER_START
– zero-based offset of the error span in terms of Unicode code points.0xFFFA
CHARACTER_END
– zero-based offset of the end of the error span.
Notes:
Error span is the range of characters (or equivalent bytes) of the original query that compiler points to as the source of the error.
COLUMN_*
is defined in terms of width of characters defined by Unicode Standard Annex #11, in other words, the column number in the text if rendered with monospace font, e.g. in a terminal.UTF16_COLUMN_*
is defined as number of UTF-16 code units (i.e. two byte-pairs) that precede target character on the same line.*_END
points to a next character after the last character of the error span.
LogMessage
Sent by: server.
Format:
struct LogMessage {
// Message type ('L').
uint8 mtype = 0x4c;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// Message severity.
uint8<MessageSeverity> severity;
// Message code.
uint32 code;
// Message text.
string text;
// Message annotations.
uint16 num_annotations;
Annotation annotations[num_annotations];
};
enum MessageSeverity {
DEBUG = 0x14;
INFO = 0x28;
NOTICE = 0x3c;
WARNING = 0x50;
};
See the list of error codes for all possible log message codes.
ReadyForCommand
Sent by: server.
Format:
struct ReadyForCommand {
// Message type ('Z').
uint8 mtype = 0x5a;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// A set of annotations.
uint16 num_annotations;
Annotation annotations[num_annotations];
// Transaction state.
uint8<TransactionState> transaction_state;
};
enum TransactionState {
NOT_IN_TRANSACTION = 0x49;
IN_TRANSACTION = 0x54;
IN_FAILED_TRANSACTION = 0x45;
};
RestoreReady
Sent by: server.
Initial Restore message accepted, ready to receive data. See Restore Database Flow.
Format:
struct RestoreReady {
// Message type ('+').
uint8 mtype = 0x2b;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// A set of annotations.
uint16 num_annotations;
Annotation annotations[num_annotations];
// Number of parallel jobs for restore,
// currently always "1"
uint16 jobs;
};
CommandComplete
Sent by: server.
Format:
struct CommandComplete {
// Message type ('C').
uint8 mtype = 0x43;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// A set of annotations.
uint16 num_annotations;
Annotation annotations[num_annotations];
// A bit mask of allowed capabilities.
uint64<Capability> capabilities;
// Command status.
string status;
// State data descriptor ID.
uuid state_typedesc_id;
// Encoded state data.
bytes state_data;
};
Dump
Sent by: client.
Initiates a database backup. See Dump Database Flow.
Format:
struct Dump {
// Message type ('>').
uint8 mtype = 0x3e;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// A set of annotations.
uint16 num_annotations;
Annotation annotations[num_annotations];
};
CommandDataDescription
Sent by: server.
Format:
struct CommandDataDescription {
// Message type ('T').
uint8 mtype = 0x54;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// A set of annotations.
uint16 num_annotations;
Annotation annotations[num_annotations];
// A bit mask of allowed capabilities.
uint64<Capability> capabilities;
// Actual result cardinality.
uint8<Cardinality> result_cardinality;
// Argument data descriptor ID.
uuid input_typedesc_id;
// Argument data descriptor.
bytes input_typedesc;
// Output data descriptor ID.
uuid output_typedesc_id;
// Output data descriptor.
bytes output_typedesc;
};
enum Cardinality {
NO_RESULT = 0x6e;
AT_MOST_ONE = 0x6f;
ONE = 0x41;
MANY = 0x6d;
AT_LEAST_ONE = 0x4d;
};
The format of the input_typedesc and output_typedesc fields is described in the Type descriptors section.
StateDataDescription
Sent by: server.
Format:
struct StateDataDescription {
// Message type ('s').
uint8 mtype = 0x73;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// Updated state data descriptor ID.
uuid typedesc_id;
// State data descriptor.
bytes typedesc;
};
The format of the typedesc fields is described in the Type descriptors section.
Sync
Sent by: client.
Format:
struct Sync {
// Message type ('S').
uint8 mtype = 0x53;
// Length of message contents in bytes,
// including self.
uint32 message_length;
};
Restore
Sent by: client.
Initiate restore to the current database. See Restore Database Flow.
Format:
struct Restore {
// Message type ('<').
uint8 mtype = 0x3c;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// A set of key-value pairs.
uint16 num_attributes;
KeyValue attributes[num_attributes];
// Number of parallel jobs for restore
// (only "1" is supported)
uint16 jobs;
// Original DumpHeader packet data
// excluding mtype and message_length
bytes header_data;
};
RestoreBlock
Sent by: client.
Send dump file data block. See Restore Database Flow.
Format:
struct RestoreBlock {
// Message type ('=').
uint8 mtype = 0x3d;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// Original DumpBlock packet data excluding
// mtype and message_length
bytes block_data;
};
RestoreEof
Sent by: client.
Notify server that dump is fully uploaded. See Restore Database Flow.
Format:
struct RestoreEof {
// Message type ('.').
uint8 mtype = 0x2e;
// Length of message contents in bytes,
// including self.
uint32 message_length;
};
Execute
Sent by: client.
Format:
struct Execute {
// Message type ('O').
uint8 mtype = 0x4f;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// A set of annotations.
uint16 num_annotations;
Annotation annotations[num_annotations];
// A bit mask of allowed capabilities.
uint64<Capability> allowed_capabilities;
// A bit mask of query options.
uint64<CompilationFlag> compilation_flags;
// Implicit LIMIT clause on returned sets.
uint64 implicit_limit;
// Data output format.
uint8<OutputFormat> output_format;
// Expected result cardinality.
uint8<Cardinality> expected_cardinality;
// Command text.
string command_text;
// State data descriptor ID.
uuid state_typedesc_id;
// Encoded state data.
bytes state_data;
// Argument data descriptor ID.
uuid input_typedesc_id;
// Output data descriptor ID.
uuid output_typedesc_id;
// Encoded argument data.
bytes arguments;
};
enum OutputFormat {
BINARY = 0x62;
JSON = 0x6a;
JSON_ELEMENTS = 0x4a;
NONE = 0x6e;
};
Use:
BINARY
to return data encoded in binary.JSON
to return data as single row and single field that contains the resultset as a single JSON array”.JSON_ELEMENTS
to return a single JSON string per top-level set element. This can be used to iterate over a large result set efficiently.NONE
to prevent the server from returning data, even if the EdgeQL command does.
The data in arguments must be encoded as a tuple value described by a type descriptor identified by input_typedesc_id.
enum Cardinality {
NO_RESULT = 0x6e;
AT_MOST_ONE = 0x6f;
ONE = 0x41;
MANY = 0x6d;
AT_LEAST_ONE = 0x4d;
};
Parse
Sent by: client.
struct Parse {
// Message type ('P').
uint8 mtype = 0x50;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// A set of annotations.
uint16 num_annotations;
Annotation annotations[num_annotations];
// A bit mask of allowed capabilities.
uint64<Capability> allowed_capabilities;
// A bit mask of query options.
uint64<CompilationFlag> compilation_flags;
// Implicit LIMIT clause on returned sets.
uint64 implicit_limit;
// Data output format.
uint8<OutputFormat> output_format;
// Expected result cardinality.
uint8<Cardinality> expected_cardinality;
// Command text.
string command_text;
// State data descriptor ID.
uuid state_typedesc_id;
// Encoded state data.
bytes state_data;
};
enum Capability {
MODIFICATIONS = 0x1;
SESSION_CONFIG = 0x2;
TRANSACTION = 0x4;
DDL = 0x8;
PERSISTENT_CONFIG = 0x10;
ALL = 0xffffffffffffffff;
};
See RFC1004 for more information on capability flags.
enum CompilationFlag {
INJECT_OUTPUT_TYPE_IDS = 0x1;
INJECT_OUTPUT_TYPE_NAMES = 0x2;
INJECT_OUTPUT_OBJECT_IDS = 0x4;
};
Use:
0x0000_0000_0000_0001
(INJECT_OUTPUT_TYPE_IDS
) – if set, all returned objects have a__tid__
property set to their type ID (equivalent to having an implicit__tid__ := .__type__.id
computed property.)0x0000_0000_0000_0002
(INJECT_OUTPUT_TYPE_NAMES
) – if set all returned objects have a__tname__
property set to their type name (equivalent to having an implicit__tname__ := .__type__.name
computed property.) Note that specifying this flag might slow down queries.0x0000_0000_0000_0004
(INJECT_OUTPUT_OBJECT_IDS
) – if set all returned objects have anid
property set to their identifier, even if not specified explicitly in the output shape.
enum OutputFormat {
BINARY = 0x62;
JSON = 0x6a;
JSON_ELEMENTS = 0x4a;
NONE = 0x6e;
};
Use:
BINARY
to return data encoded in binary.JSON
to return data as single row and single field that contains the resultset as a single JSON array”.JSON_ELEMENTS
to return a single JSON string per top-level set element. This can be used to iterate over a large result set efficiently.NONE
to prevent the server from returning data, even if the EdgeQL statement does.
enum Cardinality {
NO_RESULT = 0x6e;
AT_MOST_ONE = 0x6f;
ONE = 0x41;
MANY = 0x6d;
AT_LEAST_ONE = 0x4d;
};
Data
Sent by: server.
Format:
struct Data {
// Message type ('D').
uint8 mtype = 0x44;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// Encoded output data array. The array is
// currently always of size 1.
uint16 num_data;
DataElement data[num_data];
};
struct DataElement {
// Encoded output data.
uint32 num_data;
uint8 data[num_data];
};
The exact encoding of DataElement.data
is defined by the query output type descriptor.
Wire formats for the standard scalar types and collections are documented in Data wire formats.
Dump Header
Sent by: server.
Initial message of database backup protocol. See Dump Database Flow.
Format:
struct DumpHeader {
// Message type ('@').
uint8 mtype = 0x40;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// A set of key-value pairs.
uint16 num_attributes;
KeyValue attributes[num_attributes];
// Major version of EdgeDB.
uint16 major_ver;
// Minor version of EdgeDB.
uint16 minor_ver;
// Schema.
string schema_ddl;
// Type identifiers.
uint32 num_types;
DumpTypeInfo types[num_types];
// Object descriptors.
uint32 num_descriptors;
DumpObjectDesc descriptors[num_descriptors];
};
struct DumpTypeInfo {
string type_name;
string type_class;
uuid type_id;
};
struct DumpObjectDesc {
uuid object_id;
bytes description;
uint16 num_dependencies;
uuid dependencies[num_dependencies];
};
Known headers:
101
BLOCK_TYPE
– block type, always “I”102
SERVER_TIME
– server time when dump is started as a floating point unix timestamp stringified103
SERVER_VERSION
– full version of server as string
Dump Block
Sent by: server.
The actual protocol data in the backup protocol. See Dump Database Flow.
Format:
struct DumpBlock {
// Message type ('=').
uint8 mtype = 0x3d;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// A set of key-value pairs.
uint16 num_attributes;
KeyValue attributes[num_attributes];
};
Known headers:
101
BLOCK_TYPE
– block type, always “D”110
BLOCK_ID
– block identifier (16 bytes of UUID)111
BLOCK_NUM
– integer block index stringified112
BLOCK_DATA
– the actual block data
ServerKeyData
Sent by: server.
Format:
struct ServerKeyData {
// Message type ('K').
uint8 mtype = 0x4b;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// Key data.
uint8 data[32];
};
ParameterStatus
Sent by: server.
Format:
struct ParameterStatus {
// Message type ('S').
uint8 mtype = 0x53;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// Parameter name.
bytes name;
// Parameter value.
bytes value;
};
Known statuses:
suggested_pool_concurrency
– suggested default size for clients connection pools. Serialized as UTF-8 encoded string.system_config
– a set of instance-level configuration settings exposed to clients on connection. Serialized as:
```
struct ParameterStatus_SystemConfig {
// Type descriptor prefixed with type
// descriptor uuid.
uint32 num_typedesc;
uint8 typedesc[num_typedesc];
// Configuration settings data.
DataElement data[1];
};
```
Where `DataElement` is defined in the same way as for the [Data](#ref-protocol-msg-data) message:
```
struct DataElement {
// Encoded output data.
uint32 num_data;
uint8 data[num_data];
};
```
ClientHandshake
Sent by: client.
Format:
struct ClientHandshake {
// Message type ('V').
uint8 mtype = 0x56;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// Requested protocol major version.
uint16 major_ver;
// Requested protocol minor version.
uint16 minor_ver;
// Connection parameters.
uint16 num_params;
ConnectionParam params[num_params];
// Requested protocol extensions.
uint16 num_extensions;
ProtocolExtension extensions[num_extensions];
};
struct ConnectionParam {
string name;
string value;
};
struct ProtocolExtension {
// Extension name.
string name;
// A set of extension annotaions.
uint16 num_annotations;
Annotation annotations[num_annotations];
};
The ClientHandshake
message is the first message sent by the client upon connecting to the server. It is the first phase of protocol negotiation, where the client sends the requested protocol version and extensions. Currently, the only defined major_ver
is 1
, and minor_ver
is 0
. No protocol extensions are currently defined. The server always responds with the ServerHandshake.
ServerHandshake
Sent by: server.
Format:
struct ServerHandshake {
// Message type ('v').
uint8 mtype = 0x76;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// maximum supported or client-requested
// protocol major version, whichever is
// greater.
uint16 major_ver;
// maximum supported or client-requested
// protocol minor version, whichever is
// greater.
uint16 minor_ver;
// Supported protocol extensions.
uint16 num_extensions;
ProtocolExtension extensions[num_extensions];
};
struct ProtocolExtension {
// Extension name.
string name;
// A set of extension annotaions.
uint16 num_annotations;
Annotation annotations[num_annotations];
};
The ServerHandshake
message is a direct response to the ClientHandshake message and is sent by the server in the case where the server does not support the protocol version or protocol extensions requested by the client. It contains the maximum protocol version supported by the server, considering the version requested by the client. It also contains the intersection of the client-requested and server-supported protocol extensions. Any requested extensions not listed in the Server Handshake
message are considered unsupported.
AuthenticationOK
Sent by: server.
Format:
struct AuthenticationOK {
// Message type ('R').
uint8 mtype = 0x52;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// Specifies that this message contains a
// successful authentication indicator.
uint32 auth_status;
};
The AuthenticationOK
message is sent by the server once it considers the authentication to be successful.
AuthenticationSASL
Sent by: server.
Format:
struct AuthenticationRequiredSASLMessage {
// Message type ('R').
uint8 mtype = 0x52;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// Specifies that this message contains a
// SASL authentication request.
uint32 auth_status = 0xa;
// A list of supported SASL authentication
// methods.
uint32 num_methods;
string methods[num_methods];
};
The AuthenticationSASL
message is sent by the server if it determines that a SASL-based authentication method is required in order to connect using the connection parameters specified in the ClientHandshake. The message contains a list of authentication methods supported by the server in the order preferred by the server.
At the moment, the only SASL authentication method supported by EdgeDB is SCRAM-SHA-256
(RFC 7677).
The client must select an appropriate authentication method from the list returned by the server and send an AuthenticationSASLInitialResponse. One or more server-challenge and client-response message follow. Each server-challenge is sent in an AuthenticationSASLContinue, followed by a response from the client in an AuthenticationSASLResponse message. The particulars of the messages are mechanism specific. Finally, when the authentication exchange is completed successfully, the server sends an AuthenticationSASLFinal, followed immediately by an AuthenticationOK.
AuthenticationSASLContinue
Sent by: server.
Format:
struct AuthenticationSASLContinue {
// Message type ('R').
uint8 mtype = 0x52;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// Specifies that this message contains a
// SASL challenge.
uint32 auth_status = 0xb;
// Mechanism-specific SASL data.
bytes sasl_data;
};
AuthenticationSASLFinal
Sent by: server.
Format:
struct AuthenticationSASLFinal {
// Message type ('R').
uint8 mtype = 0x52;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// Specifies that SASL authentication has
// completed.
uint32 auth_status = 0xc;
bytes sasl_data;
};
AuthenticationSASLInitialResponse
Sent by: client.
Format:
struct AuthenticationSASLInitialResponse {
// Message type ('p').
uint8 mtype = 0x70;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// Name of the SASL authentication
// mechanism that the client selected.
string method;
// Mechanism-specific "Initial Response"
// data.
bytes sasl_data;
};
AuthenticationSASLResponse
Sent by: client.
Format:
struct AuthenticationSASLResponse {
// Message type ('r').
uint8 mtype = 0x72;
// Length of message contents in bytes,
// including self.
uint32 message_length;
// Mechanism-specific response data.
bytes sasl_data;
};
Terminate
Sent by: client.
Format:
struct Terminate {
// Message type ('X').
uint8 mtype = 0x58;
// Length of message contents in bytes,
// including self.
uint32 message_length;
};