◐ Shell
clean mode source ↗

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 introduced between formal releases may be changed in any number of ways before their initial formal release, 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, especially new argument combinations and types, while also retaining their old semantics.

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

2025-07-09 (as of 3.51)

  • The sqlite3.oo1.Stmt.parameterCount property is now a property access interceptor function, just like its columnCount counterpart. This is not believed to be a breaking change, as it does not change how the property is used, but it does change the performance characteristics of access to that property. In short: when a loop is involved, it's more performant to cache that property locally, before the loop, rather than to read that property from within the loop.

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.

2022-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