# 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

| Before | After |
| --- | --- |
| `{:exqlite, "~> 0.40"}` | `{:sqlite_engine, "~> 0.1.0"}` |
| `Exqlite` and `Exqlite.*` | `SqliteEngine` and `SqliteEngine.*` |
| `Exqlite.MixProject` | `SqliteEngine.MixProject` |
| `:exqlite` | `:sqlite_engine` |
| `config :exqlite` | `config :sqlite_engine` |
| `EXQLITE_FORCE_BUILD` | `SQLITE_ENGINE_FORCE_BUILD` |
| `EXQLITE_USE_SYSTEM` | `SQLITE_ENGINE_USE_SYSTEM` |
| `EXQLITE_SYSTEM_CFLAGS` | `SQLITE_ENGINE_SYSTEM_CFLAGS` |
| `EXQLITE_SYSTEM_LDFLAGS` | `SQLITE_ENGINE_SYSTEM_LDFLAGS` |
| `EXQLITE_INTEGRATION` | `SQLITE_ENGINE_INTEGRATION` |
| `sqlite3_nif` | `sqlite_engine_nif` |
| `[:exqlite, :procedures, ...]` | `[:sqlite_engine, :procedures, ...]` |

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:

```elixir
[
  [: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:

```bash
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:

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

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

```text
__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.