Protocol v2

[1st1]

• Drop support for protocols with versions less than 0.13 -- the version that EdgeDB v1.0 was shipped with.
  • We'll continue supporting pre-v1 dumps.
• Remove the notion of "prepared statement name" and "anonymous statements".
  • Currently Prepare and Execute have the name field. This was inherited from the Postgres protocol, however we never actually allowed to create named prepared statements. With our move to making all connections as stateless as possible, it is now clear that we'll never want to support named prepared statements.
  • The OptimisticExecute message doesn't have the name field.
• Remove the DescribeStatement​ message
  • It's way easier to just always return in/out type descriptors in the PrepareComplete message.
  • The DescribeStatement​ message adds a lot of complexity for client implementations only for the sake of saving miniscule network traffic.
  • Moreover, with us getting rid of named and anonymous prepared statements, DescribeStatement in its current design is uninplementable.
  • This is already implemented in the v0.14 of the protocol (currently only used by edgedb-js)
• Remove the Execute message
  • The motivation for the removal is similar to that of removing the Describe message. With no named or anonymous prepared statements the current design or Execute doesn't make any sense.
  • The OptimisticExecute message provides the full functionality of Execute.
• Rename OptimisticExecute to Execute
  • This is purely a documentation issue. The message type will continue to be b'O'.
• Rename Prepare to Parse in docs.
• Change the policy and format for message "headers".
  • Currently the "headers" field is an array of int16 keys pointing to arbitrary byte sequences. The field is used to pass information that's required for OptimisticExecute and other messages to function.
    • The motivation for adding headers in the first place was to simplify the process of extending the protocol with new functionality. The idea was that drivers won't need to change the parsing logic too much. Unfortunately, in practice, this resulted in all headers having arbitrary values encoding and even more complicated messages parsing code.
  • I propose to change how we encode and how we use headers:
    • Headers become an array of UTF-8-encoded string keys and UTF-8 encoded arbitrary JSON values.
    • Headers must only be used for auxiliary information not essential for the given protocol message's functionality. E.g. headers can be used in the future for tracing and debug data.
    • Both the server and the client implementations should work with ignoring headers completely.
  • The information we currently send using headers will be moved to message fields.
• Allow Parse and Execute to accept "scripts" -- strings with multiple EdgeQL commands in them.
  • Parse and Execute will require the expected_cardinality field to be set to NO_RESULT for scripts.
  • Execute would require the "output type desc ID" to be set to NULL codec.
  • Scripts will be able to have arguments in them. Parse and Execute will have to be updated to normalize the arguments and re-pack them into arguments streams that Postgres can work with.
  • Execute will pipeline all queries in one "implicit transaction" in Postgres.
• Remove the ExecuteScript​ message.
  • With Parse and Execute being able to execute scripts there's no need to the ExecuteScript message.
• Make the protocol stateless.
  • Upon establishing the connection, the server will issue a ParameterStatus message containing the full type descriptor of the state. The type descriptor will include the types of all session config values, all globals, and other session state.
    • The type descriptor will be serialized with a new structure called InputShape.
    • InputShape will be conceptually similar to ObjectShapeDescriptor but will allow sparse encoding of data -- e.g. out of 10 described global variables, the client would be able to encode and send just 1 (or none).
  • State will have to be carefully maintained on the client side. The client will be responsible to send serialized state with Parse and Execute messages. The server can return updated state via the ExecuteCompleted message or via ParameterStatus​.
  • State will be added as a new message field to Parse, Execute, and ExecuteComplete.
  • This will allow efficient implementation of client's client.withGlobals() and client.withConfig() APIs. Reusing type-descriptors to encode and decode state values eliminates hardcode and allows to reuse the existing codecs code.
• Future work:
  • Changes in OptimisticExecute:
    • Allow specifying "NULL" type ID for the output_typedesc_id field and "empty tuple" type ID for input_typedesc_id
      • When "NULL" type ID is set for the output type descriptor, OptimisticExecute would return a special message containing the full output type descriptor BEFORE the Data messages.
      • This makes it possible to use OptimisticExecute for queries that don't have arguments without Parse. Queries that have all arguments marked as "optional" should also be executable with no arguments and empty tuple input ID.
    • This is an optimization and thus it can wait until after 2.0.
  • Implement ExecuteMany message
    • This allows repeated execution of a query/script. The arguments would be streamed by the client in separate messages.
    • This, essentially, will be a user-friendly COPY IN alternative.
    • The exact spec is TBD.
• Rejected ideas:
  • Implement multiplexing.
    • The idea, roughly, is to add a "request id" field to most of the protocol messages, including Parse, Execute, Data, etc.
    • The "request id" would be an auto-incremented int64 (clients would be responsible to maintained strictly increasing IDs)
    • This would allow to maintain more than one "virtual" session within one network socket connection.
    • The upside is saving the number of open sockets that clients and servers would have to maintain.
    • The downside is the inevitable complication of client APIs and documentation. One slow "stream" can make the entire client connection "slow", degrading QoS for all concurrent "virtual" session multiplexed by the client. Troubleshooting issues like this can be complicated.
    • The other downside is a requirement to inject request IDs to Data messages sent by Postgres (currently they're just forwarded to the client untouched). While the performance impact will likely be negligible, it will still be there.
    • Even though this is marked as a "currently rejected" idea, we can potentially still implement it, but it is surely out of scope of EdgeDB v2 and likely v3.

[tailhook]

This doesn't discuss Sync and Flush. Do we get rid of Flush?

[tailhook]

Request ids are needed not just for multiplexing. They are useful to get rid of "Sync dance" for multiple-message exchanges (such as Execute->Data->Error)

[tailhook]

I also propose renaming headers to something better. Some options:

1. aux
2. debug
3. metadata
4. extensions
5. annotations

The headers, I think, comes from HTTP where they are real "headers" (i.e. come in front of the request and were meant to describe the following data, neither of this is true for EdgeDB).

This is purely documentational, though.

[tailhook]

The type descriptor will include the types of all session config values, all globals, and other session state.

It's not clear when this descriptor can be updated. For example, when schema is migrated (in a different connection) this descriptor has to be updated.

[fantix]

CommandDataDescription and PrepareComplete are identical (except the mtype) after protocol 0.14 / 1.0, Shall we drop PrepareComplete and always send the CommandDataDescription message in protocol v1.0 for both Parse and (Optimistic)Execute (if mismatch)?

[elprans]

If they're identical, then I don't see a reason to keep both.