SQLite4  Porting SQLite3 to SQLite4

The following are notes on how to port an application from using SQLite3 to use SQLite4:

• Global change "sqlite3" to "sqlite4"

• Global change "SQLITE_" to "SQLITE4_"

• Add the sqlite4_env* parameter (probably NULL) as the first argument to the following interfaces:

  • sqlite4_open()
  • sqlite4_malloc()
  • sqlite4_realloc()
  • sqlite4_free()
  • sqlite4_mprintf()
  • sqlite4_vmprintf()
  • sqlite4_log()
  • sqlite4_randomness()

• Convert uses of sqlite3_prepare_v2() to sqlite4_prepare().

• Convert all uses of sqlite4_open_v2() to sqlite4_open() (with corresponding parameter changes.)

• Check all uses of sqlite4_snprintf() and sqlite4_vnsprintf() for the new function signature:

  • The order of the first two arguments is reversed
  • Both routines return the length of the result string.

UTF-16 Functions

Many SQLite3 APIs come in two flavours - UTF-8 and UTF-16. For example, sqlite3_complete() and sqlite3_complete16(). In most cases, the only difference between the two versions is that one interprets or returns text encoded using UTF-8, and the other using native byte-order UTF-16. For SQLite4, all UTF-16 APIs have been removed except the following:

• sqlite4_column_text16()
• sqlite4_value_text16()
• sqlite4_bind_text16()
• sqlite4_result_text16()
• sqlite4_result_error16()

In place of the removed APIs, SQLite4 offers an API - sqlite4_translate() - to translate from UTF-16 to UTF-8 and vice-versa. For example, to obtain the current error message formated using UTF-16 (available in SQLite3 by calling sqlite3_errmsg16()), the following:

  u16 *pError;                    /* Pointer to translated error message */
  sqlite4_buffer buf;             /* Buffer to manage memory used for pError */

  /* Initialize a buffer object. Then populate it with the UTF-16 translation
  ** of the UTF-8 error message returned by sqlite4_errmsg().  */
  sqlite4_buffer_init(&buf, 0);
  pError = sqlite4_translate(
      &buf, sqlite4_errmsg(db), -1, SQLITE4_TRANSLATE_UTF8_UTF16
  );

  if( pError==0 ){
    /* An out-of-memory error has occurred */
  }else{
    /* pError now points to a buffer containing the current error message
    ** encoded using native byte-order UTF-16. Do something with it! */
  }

  /* Free the contents of the buffer (and hence pError) */
  sqlite4_buffer_clear(&buf);

CHECK Constraint Evaluation

In SQLite4, CHECK constraints are evaluated after affinities are applied to new column values. In SQLite3, the CHECK constraints are evaluated before affinities are applied.