The SQL Relay client API's are ultimately based on the C++ API and the Rudiments library. A more portable approach would be to implement the API natively in a language like Java, Python or Perl. A more stripped down and potentially higher performance version of the API could be written in any language.

SQL Relay has always had an open-protocol by virtue of being open-source, but reverse-engineering it from the API code can be a daunting task. If it were documented in plainer terms, it would be "more open".

Born of these motivations, the following pseudocode demonstrates the protocol and its capabilities. This code should provide enough detail about the protocol to enable a developer to write his or her own API.

Note that this specification will likely change a bit as new features are added to SQL Relay.

• Yellow: long - a 32 bit integer
• Red: short - a 16 bit integer
• Green: string - a series of 8 bit chars
• Blue: double - a 32 bit, double precision floating point number

• Connect to the sqlr-listener using an inet or unix datagram socket
• Send:

  length of user name

  user name string

  length of password

  password string

• Receive:

  error status: 1 or 0

  • If error status is 1

    length of the error

    error string

  • If error status is 0

    whether to reconnect to the connection daemon or not

    • If reconnect is 1

      length of the inet port

      unix port string

      inet port

      • Disconnect from listener
    • If reconnect is 0 skip down to Send below.

• Connect to the sqlr-connection-"dbase" using the inet or unix datagram socket that you got from the listener
• Send:

  11 (sending authentication)

  length of user name

  user name string

  length of password

  password string

• Receive:

  error status: 1 or 0

• Loop:
• If sending a query:
• Send:

  0 (sending a query)

  0 (we need a cursor)

• If executing a new query:

  0

  length of the query

  the query string

• If re-binding/re-executing the previously sent query:

  1

The number of input bind variables

• For each input bind variable:

  length of the bind variable name

  the bind variable name string

  • For a string variable:

    1 (indicates that this is a string variable)

    the size of the bind variable value

    the bind variable value

  • For a long variable:

    2 (indicates that this is a long variable)

    the bind variable value

  • For a double variable:

    3 (indicates that this is a long variable)

    the bind variable value

    the bind variable precision

    the bind variable scale

  • For a NULL variable:

    0 (indicates that this is a NULL variable)

The number of output bind variables

• For each output bind variable:

  length of the bind variable name

  the bind variable name string

  the size of the bind variable value

• If you want to get column info:

  1

• If you don't want to get column info:

  0

The number of rows to skip

The number of rows to fetch

Skip to "If fetching rows from a result set: Receive" below...
• If sending a commit:
  • Send:

    9 (sending a commit)

  • Receive:

    1 or 0

• If sending a rollback:
  • Send:

    10 (sending a rollback)

  • Receive:

    1 or 0

• If toggling autocommit:
  • Send:

    11 (autocommit)

    0 to turn off autocommit and 1 to turn on autocommit

  • Receive:

    1 if toggling autocommit succeeded and 0 if it failed

• If sending a ping:
  • Send:

    7 (sending a ping)

  • Receive:

    1 or 0

• If sending a identify:
  • Send:

    8 (sending a identify)

  • Receive:

    length of the id string

    id string

• If fetching rows from a result set:
  • Send:

    1 (fetch rows from a result set)

    the id of the cursor to fetch from

    The number of rows to skip

    The number of rows to fetch

  • Receive:

    error status: 1 or 0

  • If error status is 1

    length of the error

    error string

  • If error status is 0

    cursor id

    whether result set was suspended or not: 1 or 0

    whether the server knows the total number of rows or not: 1 or 0

  • If server knows the total number of rows:

    total number of rows

  whether the server knows the number of affected rows or not: 1 or 0

  • If server knows the number of affected rows:

    number of affected rows

  whether the server is sending column info or not: 1 or 0

  column count

  • If server is sending column info:
    • For each column:

      column name length

      column name

      column type

      column length

  • Loop:

    output bind variable type: 0,1 or 4

    • If type is 0 then the data is null
    • If type is 1

      output bind value length

      output bind value

    • If type is 4 then break out of loop
  • Loop, Receiving:

    field type: 0,1,2,3 or 4

  • If field type is 0 then the data is null
  • If field type is 1 then the data is normal data

    length of the data

    the data

  • If field type is 2 then this is a chunk of long data

    length of the chunk

    the chunk

  • If field type is 3 then this is the end of the long data
  • If field type is 4 (end of result set) then break out of the loop
• If aborting a result set:
  • Send:

    2 (abort a result set)

    the id of the cursor to abort

• If suspending a result set:
  • Send:

    3 (suspend a result set)

    the id of the cursor to suspend

• If resuming a previously suspended result set:
  • Send:

    4 (resume a result set)

    the id of the cursor to resume

    The number of rows to skip

    The number of rows to fetch

    Skip to "If fetching rows from a result set: Receive" above...