The document introduces libAttachSQL, a new C connector for MySQL that provides a non-blocking API. It was created by Andrew Hutchings and is designed from the ground up to be lightweight, well documented, and compatible with modern asynchronous programming techniques. LibAttachSQL uses libuv for its event loop and aims to improve upon existing MySQL C connectors by providing a fully asynchronous API without legacy issues.

1. libAttachSQL
The Next-Generation C Connector for MySQL
by Andrew Hutchings (LinuxJedi), HP Advanced Technology Group

2. About LinuxJedi
• Worked for Sun/Oracle, MySQL Support Engineer
• Worked at Rackspace, Drizzle Software Engineer
• Worked at SkySQL, Senior Sustaining Engineer
• Managed two teams, several projects at HP Cloud
• Co-Author of MySQL 5.1 Plugins Development

3. About HP's Advanced Techonology Group
• An Open Source think-tank
• Fosters collaboration throughout HP
and Open Source communities

5. Other MySQL C Connectors
• libmysqlclient (GPLv2/proprietary)
• libdrizzle (3-clause BSD)
• Maria DB Client (LGPLv2.1 (sort-of))

6. None of these have an official fully non-blocking API!

7. Introducing libAttachSQL

8. libAttachSQL 1.0 Features
• Non-blocking API
• Apache 2.0 license
• Very lightweight (1.0.0 shared binary is 501KiB)
• Can use OpenSSL and zlib for encryption and compression
• Server side and (sort-of) local prepared statements
• Good documentation from the start (http://docs.libattatchsql.org/)

9. Compatible With
• Ubuntu 12.04 and up
• RedHat/CentOS 6.x and up
• Windows (via. MinGW cross-compile)
• GCC and CLang

10. Why not libdrizzle?
• libdrizzle 5.1 has a blocking API
• Internal state loop is ugly to deal with
• Networking code was hard to work with

11. Good things about libdrizzle
• Lightweight
• Nice, simple API
• Well tested (Jenkins CI)
• Easy to contribute to
• Liberal license

12. Why libAttachSQL?
• Modern techniques
• All of the good points of libdrizzle, none of the legacy
• Designed from the ground-up for use with MySQL

13. Event loops are web scale!

14. Non-blocking Internals
• Using libuv - a library born out of Node.js
• Uses epoll/poll/kqueue in *nix
• Uses I/O Completion Ports in Windows

16. Very Open Development
• GitHub (with issues & pull requests)
• GitHub Pages + Pelican
• Travis CI
• Waffle.io
• Read The Docs
• Coverity Scan
• IRC

18. Travis Tests
• GCC 32bit & 64bit
• CLang 3.0 32bit & 64bit
• CLang 3.4 64bit
• No OpenSSL & zlib
• Valgrind
• Cppcheck
• CLang Scan-Build
• Documentation (Sphinx nit-pick mode)

19. Software Using libAttachSQL
• Sysbench
• AttachBench

21. Basic Query Example

22. con= attachsql_connect_create("localhost", 3306, "test", "test", "testdb", NULL);
attachsql_query(con, strlen(query), query, 0, NULL, &error);

23. Things to Note
• We haven't actually even connected yet!
• No query/result object

24. while ((ret != ATTACHSQL_RETURN_EOF) && (error == NULL))
{
ret= attachsql_connect_poll(con, &error);
if (ret != ATTACHSQL_RETURN_ROW_READY)
{
continue;
}

25. row= attachsql_query_row_get(con, &error);
columns= attachsql_query_column_count(con);
...
attachsql_query_row_next(con);
}

26. Escaped Queries

27. const char *query= "SELECT * FROM t1 WHERE name = ? AND age > ?";
attachsql_query_parameter_st param[2];
const char *name= "fred";
uint32_t age= 30;
param[0].type= ATTACHSQL_ESCAPE_TYPE_CHAR;
param[0].data= (char*)name;
param[0].length= strlen(name);
param[1].type= ATTACHSQL_ESCAPE_TYPE_INT;
param[1].data= &age;
param[1].is_unsigned= true;
attachsql_query(con, strlen(query), query, 2, param, &error);

28. Prepared Statements

29. const char *query= "SELECT * FROM t1 WHERE name = ? AND age > ?";
attachsql_statement_prepare(con, strlen(query), query, &error);
while((ret != ATTACHSQL_RETURN_EOF) && (error == NULL))
{
ret= attachsql_connect_poll(con, &error);
}

30. const char *name= "fred";
uint32_t age= 30;
attachsql_statement_set_string(con, 0, strlen(name), name, NULL);
attachsql_statement_set_int(con, 1, age, NULL);
attachsql_statement_execute(con, &error);
ret= ATTACHSQL_RETURN_NONE;
while ((ret != ATTACHSQL_RETURN_EOF) && (error == NULL))
{

31. ret= attachsql_connect_poll(con, &error);
if (ret != ATTACHSQL_RETURN_ROW_READY)
{
continue;
}
attachsql_statement_row_get(con, &error);
printf("ID: %d, ", attachsql_statement_get_int(con, 0, &error));
size_t len;
char *name_data= attachsql_statement_get_char(con, 1, &len, &error);
printf("Name: %.*s, ", (int)len, name_data);
printf("Age: %dn", attachsql_statement_get_int(con, 2, &error));
attachsql_statement_row_next(con);
}

32. Connection Groups
• Group many connections into a single event loop
• Many queries can run simultaneously on a single thread
• Uses a callback API when there events to process
• Can't be used for Prepared Statements (yet)

33. Connection Groups Example

34. group= attachsql_group_create(NULL);
con[0]= attachsql_connect_create("localhost", 3306, "test", "test", "testdb", NULL);
attachsql_group_add_connection(group, con[0], &error);
attachsql_connect_set_callback(con[0], callbk, &con_no[0]);

35. attachsql_query(con[0], strlen(query1), query1, 0, NULL, &error);

36. while(done_count < 3)
{
attachsql_group_run(group);
}
attachsql_group_destroy(group);

37. void callbk(attachsql_connect_t *current_con, attachsql_events_t events,
void *context, attachsql_error_t *error)
{
...
switch(events)
{

38. case ATTACHSQL_EVENT_CONNECTED:
printf("Connected event on con %dn", *con_no);
break;

39. case ATTACHSQL_EVENT_ERROR:
printf("Error exists on con %d: %dn", *con_no, attachsql_error_code(error));
attachsql_error_free(error);
break;

40. case ATTACHSQL_EVENT_EOF:
printf("Connection %d finishedn", *con_no);
done_count++;
attachsql_query_close(current_con);
break;

41. case ATTACHSQL_EVENT_ROW_READY:
row= attachsql_query_row_get(current_con, &error);
...
attachsql_query_row_next(current_con);
break;

42. Error Handling

43. attachsql_error_t *error= NULL;
ret= attachsql_connect_poll(con, &error);
if (error != NULL)
{
printf("Error occurred: %s", attachsql_error_message(error));
attachsql_error_free(error);
}

44. Project Status
• 4 months in development (coding started 4th July)
• 3 alpha releases, 2 beta releases, 1 RC release
• First GA (1.0.0) is out now!
• Packages for Ubuntu and RHEL/CentOS

45. Future
• Python wrapper
• Other language wrappers
• Server API?
• Tools built around libAttachSQL

46. Questions?

47. Thank you
libAttachSQL - http://libattachsql.org/
Freenode IRC - #libAttachSQL
GitHub - http://github.com/libattachsql/libattachsql
Email andrew@linuxjedi.co.uk
Twitter @LinuxJedi or @libAttachSQL