API

Two libraries let a program use a cluster. They have the same functions, the same rules and the same messages. Both reconnect to another broker when the one they talk to stops, send again only the statements that read, and report with a clear error when a statement that changes data may or may not have been executed.

C library

#include "synsqllib.h"

SYNSQL *s = synsql_init();
synsql_load_conf( s, NULL );                    /* etc/synsql.conf */
if ( synsql_real_connect( s, "user", "password" ) != SYNSQL_OK ) {
  fprintf( stderr, "%s\n", synsql_error( s ) );
  return 1;
}

synsql_query( s, "select source_id, ra from gaia_source limit 3;" );
while ( synsql_fetch_row( s ) == 1 ) {
  for ( int i = 0; i < synsql_num_fields( s ); i++ )
    printf( "%s | ", synsql_field( s, i ) ? synsql_field( s, i ) : "NULL" );
  printf( "\n" );
}
synsql_free_result( s );
synsql_close( s );

• select, execute and alter ... index give rows, read one by one with synsql_fetch_row. A NULL is a null pointer.
• Other statements (describe, show, insert, delete...) put the server's answer in synsql_answer.
• A result that is not read to the end is closed by synsql_free_result.
• Errors: synsql_query returns a code (SYNSQL_E_UNCERTAIN: the statement may or may not have been executed, it was not sent again).

Build it with make -f Makefile.lib in the client directory; it produces libsynsql.so and libsynsql.a.

Python library

import pysynsql

with pysynsql.Connection() as c:
    c.load_conf()
    c.real_connect("user", "password")
    c.query("select source_id, ra from gaia_source limit 3;")
    for row in c.rows():
        print(row)                      # a tuple of text, None for NULL
    c.query("describe gaia_source;")
    print(c.answer)

Errors are exceptions: pysynsql.SynsqlError, with a subclass for each case (UncertainError for a statement that may or may not have been executed). The library needs only the Python standard library (Python 3.8 or later) and runs on Linux and Windows.