Migrate to HeliosDB

SQLite → HeliosDB Nano

Nano is not a SQLite build. It is an independent engine with a SQLite-dialect compatibility layer, and it does not open .sqlite files directly. Plan an export and reload, not a file swap, and budget for application changes — this is not a drop-in.

The workflow

1. Export schema and data from the SQLite file.
2. Adapt the schema to static column types (see below), then create it on a fresh Nano data directory.
3. Load the data.
4. Verify before trusting it — compare row counts per table, and checksum the columns you actually care about.
5. Re-run your application's queries and transactions against Nano, and keep the SQLite file until they pass.

Adaptations you will actually have to make

• Type affinity. Nano is statically typed; SQLite's affinity rules are dynamic and will happily store a string in an INTEGER column. Inserts that SQLite accepted can error on Nano. Find these before the load, not after cutover.
• INSERT OR REPLACE is not the same statement. Nano accepts the syntax and rewrites it to an in-place upsert (ON CONFLICT DO UPDATE, setting the columns you listed). SQLite's REPLACE deletes the conflicting row and inserts a new one — columns you did not list revert to their defaults, the rowid changes, and delete triggers fire. If your code leans on that behaviour, rewrite it explicitly. The rewrite also needs a parenthesised column list; without one the statement stays a plain INSERT and a duplicate key raises a uniqueness error.
• Extensions, custom collations and user-defined functions do not carry over. Anything built on a loadable SQLite extension needs a different plan.

Nano embedded → Nano server

Same engine, same data directory, different access path. This is a stop-then-start handoff, not a live cutover and not a mode you run both halves of at once — two processes opening the same embedded data directory is a locking hazard, not a hybrid deployment.

1. Stop the embedded process cleanly. Nothing else should hold the data directory open.
2. Keep the Nano version identical across the switch. Do not combine a mode change with a version bump — upgrades have their own release notes and their own failure modes, and debugging both at once is how a switchover turns into an outage.
3. Start the server against the same data directory and configure a real authentication method. The database is a network surface now; it needs to be treated as one.
4. Change the application code. Embedded calls become a PostgreSQL or MySQL client connection. This is real client work, not a connection-string edit.
5. Validate the new path end to end — connect, read, write, transact — before you decommission the embedded one.

Nano → Lite or Full

Lite and Full are separate products with their own storage and deployment models. Your client code is largely portable, because the wire surface is shared — but a shared protocol says nothing about a shared on-disk format, and we do not publish an automated import path from a Nano store into either tier.

If you are sizing this move, talk to us and we will scope it against what your deployment actually looks like rather than guessing at it here.