Migrating from Exqlite

SqliteEngine 0.1.0 is a hard identity migration from Exqlite 0.40.0. It does not ship compatibility modules or read old application/build configuration. Plan a full VM restart and database backup, not a hot code upgrade.

Identity replacements

Replace aliases, structs, exception matches, behaviours, callbacks, doctests, and type extensions—not only top-level calls. For example, Exqlite.ProcedureError, Exqlite.Query, Exqlite.Result, and Exqlite.TypeExtension become their SqliteEngine.* equivalents.

Direct DBConnection use continues through SqliteEngine. The upstream Ecto SQLite adapter depends on the predecessor identity and is not supported unless a separate adapter release explicitly targets and tests SqliteEngine.

Telemetry

Detach handlers from the old event names and attach them to:

[
  [:sqlite_engine, :procedures, :operation, :start],
  [:sqlite_engine, :procedures, :operation, :stop]
]

No duplicate old events are emitted. Measurement semantics and payload-redacted metadata are unchanged.

Build and precompile caches

Stop the application and remove predecessor build/cache artifacts before the first new boot:

mix clean
rm -rf _build priv/sqlite3_nif.*
# Remove matching exqlite NIF archives from your configured elixir_make cache.
bin/setup_native_deps.sh
SQLITE_ENGINE_FORCE_BUILD=1 mix compile

Do not rename an old NIF binary. SqliteEngine.Sqlite3.build_info/0 must report :sqlite_engine, sqlite_engine_nif, Bedrock, and the locked Luau commit.

Procedure database migration

Back up each database while no old application process is writing it. For a SQLite CLI backup:

sqlite3 app.db ".backup 'app.before-sqlite-engine.db'"

On first procedure API use, SqliteEngine inspects these complete predecessor objects:

__exqlite_schema_versions
__exqlite_luau_procedures
__exqlite_command_receipts
__exqlite_results

If and only if all four valid predecessor tables exist and none of the four __sqlite_engine_* tables exists, migration runs under BEGIN IMMEDIATE (or a savepoint inside an already owned transaction). It validates schema version, Luau commit, canonical compile-option bytes, and the exact predecessor runtime ABI. It then renames all tables, changes only exqlite-luau-canonical-v1 to sqlite-engine-luau-canonical-v1, checks schema, ABI, and foreign-key integrity, and commits.

Procedure keys/source/metadata, receipt IDs/input hashes/outcomes, result references/payload bytes, retention times, and application tables are not rewritten. Fresh target-only databases and valid already-migrated databases are idempotent.

Partial old or new sets, both complete namespaces, non-table collisions, unsupported schema versions, unknown ABI values, changed compile options, corruption, busy/timeout, and failed integrity checks return a bounded %SqliteEngine.ProcedureError{phase: :migration} and roll back. SqliteEngine never merges or drops an ambiguous namespace.

Rollback

There is no automatic down migration. If deployment must return to Exqlite:

1. stop all SqliteEngine processes;
2. restore the pre-migration database backup;
3. restore the predecessor dependency/configuration and precompile cache;
4. perform a full VM restart;
5. verify application data and procedure receipts before accepting traffic.

Keep the backup until the new application, pooled reopen behavior, receipts, and durable results have been verified in production-shaped staging.

Repository and release links

Source, CI, documentation, precompiled archives, and release links move from the upstream Exqlite repository to https://github.com/mindreframer/sqlite_engine. Confirm that coordinate exists and artifact checksums match the package before release installation; the implementation never falls back to upstream release assets.