Using asynchronous mode

Updated: October 26, 2022

By default, QDB completes execution of SQL statements against a database before returning from qdb_statement(). However, you can connect to QDB using asynchronous mode by setting the QDB_CONN_STMT_ASYNC flag when calling qdb_connect().

In this mode, some errors, such as syntax errors, can be caught before qdb_statement() returns but others, such as database constraint violations, may not be generated until the statement is completed. These “delayed” errors are available only to a subsequent qdb_getresult() call.

The advantage of asynchronous operation is that it allows parallelism between the client application and the database engine, especially in cases where the client will later retrieve the statement result (e.g., SELECT statements). The danger of asynchronous operation is that the client must be aware that the statement may not necessarily have completed or indicated all errors, and must be coded to call qdb_getresult() to retrieve any errors.

The mode you should use depends on what exactly you are doing. If it is primarily SELECT statements, then you can use asynchronous mode and let the database engine run, because you are calling back in anyway for the rows/results. If you are primarily doing database maintenance (i.e., INSERT, UPDATE, and DELETE statements), then you probably want synchronous statement execution so you can use just one API call.