# SQLite WebAssembly build

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

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

## Extension

SQLite [amalgamation][2] extensions included:

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

SQLite [contribution extensions][17]:

1. [extension-functions][18] -- 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][3] included:

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

SQLite 3rd party extensions included:

1. [pivot_vtab][5] -- a pivot virtual table
2. `pearson` correlation coefficient function extension from [sqlean][21]
   (which is part of [squib][20])
3. [sqlitelua][22] -- a virtual table `luafunctions` which allows to define custom scalar,
   aggregate and table-valued functions in Lua

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][19].

## Build method

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

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

[1]:  https://github.com/sql-js/sql.js
[2]:  https://sqlite.org/amalgamation.html
[3]:  https://sqlite.org/src/dir?ci=trunk&name=ext/misc
[4]:  https://sqlite.org/fts5.html
[5]:  https://github.com/jakethaw/pivot_vtab
[6]:  https://sqlite.org/series.html
[7]:  https://sqlite.org/src/file/ext/misc/series.c
[8]:  https://sqlite.org/src/file/ext/misc/closure.c
[9]:  https://sqlite.org/src/file/ext/misc/uuid.c
[10]: https://sqlite.org/src/file/ext/misc/regexp.c
[11]: https://charlesleifer.com/blog/querying-tree-structures-in-sqlite-using-python-and-the-transitive-closure-extension/
[12]: https://sqlite.org/forum/forumpost/6ad7d4f4bebe5e06?raw
[13]: https://sqlite.org/src/file/ext/misc/percentile.c
[14]: https://sqlite.org/src/file/ext/misc/decimal.c
[15]: https://sqlite.org/fts3.html
[16]: https://sqlite.org/json1.html
[17]: https://sqlite.org/contrib/
[18]: https://sqlite.org/contrib//download/extension-functions.c?get=25
[19]: https://github.com/lana-k/sqliteviz/blob/master/tests/lib/database/sqliteExtensions.spec.js
[20]: https://github.com/mrwilson/squib/blob/master/pearson.c
[21]: https://github.com/nalgeon/sqlean/blob/incubator/src/pearson.c
[22]: https://github.com/kev82/sqlitelua
