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 ODBC in the SQL world.

The ConnectBlox protocol 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.

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.