Client-Breaking API Changes

This page briefly covers any API changes which have the potential to break client-side code.

The SQLite JavaScript APIs strive to uphold the same strong backwards-compatibility guarantees as the C API, with the exception that the earliest releases of the JS APIs were explicitly "beta"/"tech preview" releases which were subject to change.

APIs introduces between formal releases may be changed in any number of ways, but once an API is published via a formal release, every effort will be made to retain it, with the rare exception of APIs which eventually turn out to be seriously flawed (a notable example being sqlite3_js_vfs_create_file()). It is, however, not uncommon for JS APIs to take on new semantics, e.g. new argument combinations and types, while also retaining their own semantics.

The list of known breaking changes follows, newest first...

2022-12-25

• The signature of JS functions passed to sqlite3_exec() was simplified to remove the arguments which are extraneous for JS. The "full" form can be used from JS by manually installing a callback and passing its pointer, instead of the function object, to sqlite3_exec().

2022-12-14

• oo1.DB.exec()'s rowMode option previously accepted a column name reference in the forms "$X", "@X", or ":X". The latter two have been removed because they are superfluous and having unnecessary variety seems likely to cause confusion.

2012-12-09

• Renamed several oft-used methods of the sqlite3.wasm namespace, but retained the older names as aliases:

  • setMemValue() → poke()
  • setPtrValue() → pokePtr()
  • getMemValue() → peek()
  • getPtrValue() → peekPtr()
    The names peek and poke are explained in detail on Wikipedia. peekPtr() and pokePtr() are simply convenience forms with one fewer argument.

• The return semantics of wasm.poke() and wasm.pokePtr() have changed. They now return this instead of returning the function itself. They also now accept an array of addresses, but that is not a potentially breaking change.

2022-12-06

• sqlite3.wasm.cstringToJs() was renamed to cstrToJs() for consistency.

2022-11-30

• sqlite3.wasm.alloc() now proxies sqlite3_malloc() (formerly malloc()) and sqlite3.wasm.dealloc() now proxies sqlite3_free() (formerly free()). It is not expected that any clients are affected by this unless, perhaps, they link sqlite3.wasm into a larger application. This change eliminates some client-side inconsistencies in how JS-side WASM memory has to be managed, most notably via sqlite3_deserialize() and parts of the virtual table interface.

2022-11-29

• sqlite3.opfs.OpfsDb renamed to sqlite3.oo1.OpfsDb, for consistency with other oo1.DB subclasses. The older name will be usable for a brief period but will be removed by the 3.41 release. (Update: removed 2022-12-06.)