Appendix A. ConnectBlox

ConnectBlox is the name of the protocol used to communicate with a running instance of the LogicBlox database server. It serves a role similar to that of JDBC or ODBC in the SQL world.

The primary ConnectBlox protocol is represented via Google Protocol Buffers, defined via the schemas found in the directory lib/protobuf/blox/connect/ of the LogicBlox distribution. The client sends Request messages and the server responds with Response messages. There is an administrative variant of ConnectBlox that uses the AdminRequest and AdminResponse messages instead. Currently, the two variants are never intermixed on the same connection.

A.1. ConnectBlox TCP Transport

At present, the only transport option for ConnectBlox is TCP over IP. The default port for standard connections is 5518 and the default port for admin connections is 5519.

After a connection with the server has been established, all communications in both directions takes the form of data segments with the following layout:

The id and the payload size are both 32-bit unsigned integers in network byte order (big endian), followed by the actual payload, whose size in bytes matches the payload size sent just before it.

The id field is used to match up responses with requests. The client is allowed to send multiple requests while waiting to receive a response. As different requests may require differing amounts of computation, a request sent later may receive a response before a response is sent for an earlier request. For example, say the client wishes to cancel a long running transaction. It may send the cancel request, and receive a response for it without ever receiving a response to the original request.

It is also possible in some cases to receive a response message with an id that does not directly correspond to the id of a request sent by the client. Currently, the only case where this is valid is if the client sent a prior request that indicates it wishes to have data streamed back to it with a specific response id. The payload of these messages are not required to be represented using Google Protocol Buffers. For example, when streaming predicate data back to the client, the payload will be binary data in BloxFrame format, and the end of stream is signaled with a zero length payload.

The client may keep the TCP connection open to the server for as long as it needs to complete whatever interactions it wishes to perform. When these are complete the client closes the connection. The server will only close the connection if an admin request has been sent informing the server to shut down.