sqliteviz/lib/sql-js/README.md

SQLite WebAssembly build

This directory contains Docker-based build script, make.sh, that builds a custom version of sql.js. It allows sqliteviz to have more recent version of SQLite build with a number of useful extensions.

Makefile from sql.js is rewritten as more comprehensible configure.py and build.py Python scripts that run in emscripten/emsdk Docker container.

Extension

SQLite amalgamation extensions included:

1. FTS5 -- virtual table module that provides full-text search functionality
2. FTS3/FTS4 -- older virtual table modules for full-text search
3. JSON1 -- scalar, aggregate and table-valued functions for managing JSON data

SQLite contribution extensions:

1. extension-functions -- mathematical and string extension functions for SQL queries.

   Math: acos, asin, atan, atn2, atan2, acosh, asinh, atanh, difference, degrees, radians, cos, sin, tan, cot, cosh, sinh, tanh, coth, exp, log, log10, power, sign, sqrt, square, ceil, floor, pi.

   String: replicate, charindex, leftstr, rightstr, ltrim, rtrim, trim, replace, reverse, proper, padl, padr, padc, strfilter.

   Aggregate: stdev, variance, mode, median, lower_quartile, upper_quartile.

SQLite miscellaneous extensions included:

1. generate_series table-valued series function (series.c)
2. transitive_closure virtual table for Querying Tree Structures in SQLite (closure.c)
3. uuid, uuid_str and uuid_blob RFC-4122 UUID functions (uuid.c)
4. regexp (hence REGEXP operator) and regexpi functions (regexp.c)
5. percentile function (percentile.c)
6. decimal, decimal_cmp, decimal_add, decimal_sub and decimal_mul functions (decimal.c)

SQLite 3rd party extensions included:

1. pivot_vtab -- a pivot virtual table

To ease the step to have working clone locally, the build is committed into the repository.

Examples of queries involving these extensions can be found in the test suite in sqliteExtensions.spec.js.

Build method

Basically it's extended amalgamation and SQLITE_EXTRA_INIT concisely described in this message from SQLite Forum:

Simply append it to the end of the amalgamation file. The real problem is how you get the init function called. The easiest way (to me at any rate) is to append a function (after the extensions you want to add are all appended) that adds the init function for each extension to the auto extension list for new connections, and set the pre-processor symbol SQLITE_EXTRA_INIT to the name of this function. [...]

An example SQLITE_EXTRA_INIT function looks like this:

int core_init(const char* dummy)
{
   int nErr = 0;

   nErr += sqlite3_auto_extension((void*)sqlite3_autobusy_init);
   nErr += sqlite3_auto_extension((void*)sqlite3_ipaddress_init);

   return nErr ? SQLITE_ERROR : SQLITE_OK;
}

so you would then define SQLITE_EXTRA_INIT=core_init when compiling the amalgamation code and the extensions would thereafter be automatically initialized on each connection.