quicsql

name	quicsql
description	Use when connecting liteorm to a remote quicSQL server (quicsql.net) instead of a local SQLite file — the sqlite.Open "quicsql://" DSN, sqlite.WrapDB for mTLS/keyring auth, and which SQLite features work over the wire.

Remote SQLite with quicSQL

quicSQL (quicsql.net) is a remote SQLite server. LiteORM reaches it through the ordinary liteorm.org/dialect/sqlite backend — same models, same query/orm API, same normalized errors — by opening a quicsql:// DSN instead of a file path. Local (in-process, via gosqlite.org) and remote share one dialect; only the DSN differs.

Connect

sqlite.Open dispatches by DSN shape: a bare path / :memory: / file: URI is in-process; any other scheme:// DSN is remote. Blank-import the driver once to register the scheme.

import (
    _ "quicsql.net/client/sqldriver" // registers the quicsql:// scheme
    "liteorm.org/dialect/sqlite"
)

db, err := sqlite.Open("quicsql://host:7777/app?transport=h2&token=…")

Then everything is the normal SQLite backend: orm.AutoMigrateAll, orm.Repo, the query builder, transactions (SAVEPOINT-nested Begin), introspection, and migrations run server-side; constraint errors normalize to liteorm.ErrUniqueViolation etc.

mTLS / keyring: WrapDB

A DSN can't carry an mTLS cert or ed25519 keyring. Build the *sql.DB with the quicSQL client and wrap it:

db := sqlite.WrapDB(sql.OpenDB(sqldriver.OpenConnectorClient(qc))) // qc is a *client.Client from quicsql.net/client

sqlite.WrapDB(db *sql.DB, opts ...liteorm.Option) *liteorm.DB is the seam Open uses internally. sqlite.RawDB(sess) returns the underlying *sql.DB of a remote session.

What works over the wire

• search (vector / FTS5 / hybrid) — runs as SQL against vec0/fts5 sidecars on the server (server must have vec0 registered; fts5 is built in).
• changeset (Capture/Apply/Invert/Concat) — SESSION extension, server-side.
• large objects — transfer whole: lob.WriteFrom / ReadAll / Size / Drop.

Pitfalls

• Streaming LOB is local-only. The streaming handle API (lob.Open/Read/Truncate, native io.WriterAt/io.ReaderAt) does not work remotely — over the wire, blobs move whole. Use a local DB (Open/OpenEncrypted/vault) for partial/streaming blob I/O.
• Forgetting the blank import means the quicsql:// scheme isn't registered and Open fails.
• A token needs TLS. The driver fails closed — it refuses a credential over a plaintext/unverified transport (h1, h2c, insecure=1); use transport=h2/h3.
• Vector search needs vec0 registered on the server; you don't register it client-side.

Deeper

• API: https://pkg.go.dev/liteorm.org/dialect/sqlite (Open, WrapDB, RawDB). Guide: docs/guides/quicsql.md.
• Related: the using-liteorm, sqlite-search, large-objects, and changesets skills — all apply over a remote handle.