Locates the localize_icu SQLite extension for loading into a connection.

localize_icu is a SQLite loadable extension that registers ICU collations under the same names PostgreSQL uses — de-x-icu, sv-x-icu, de-u-co-phonebk-x-icu — along with ICU-backed two-argument upper/2, lower/2 and title/2 SQL functions. It is what makes Localize.Ecto.SQLite3 work.

Collations are registered on demand: the extension installs a sqlite3_collation_needed handler, so the first statement to name a collation SQLite does not have causes it to be built from the tag by ICU. Every tag ICU understands works, including the -u- tailorings that PostgreSQL needs a CREATE COLLATION for, and no migration is involved.

Building the extension

The extension needs a C compiler and the ICU development libraries, so it is not built unless asked for. Enable it with either:

# config/config.exs — must be config.exs, it is read at compile time
config :localize_sql, :sqlite_icu, true

or the LOCALIZE_SQL_SQLITE_ICU=true environment variable when compiling. On macOS, brew install icu4c; on Debian and Ubuntu, apt-get install libicu-dev.

Loading it

Both Exqlite and Ecto.Adapters.SQLite3 accept a :load_extensions option and apply it to every pooled connection:

# config/runtime.exs
config :my_app, MyApp.Repo,
  load_extensions: Localize.Ecto.SQLite3.Extension.load_extensions()

load_extensions/0 returns an empty list when the extension was not built, so the same configuration is safe in an environment that has not opted in — queries naming an ICU collation will then fail with SQLite's no such collation sequence error rather than at boot.