SQLite Runtime Guide

SqliteReflector is the runtime entry point for SQLite projects.

Typical Workflow

1. Define entities with entity(...) and column.*(...) helpers.
2. Construct a reflector with a database filename.
3. Call reflect(...) to create or synchronize tables.
4. Use fluent builders such as select, insertInto, update, and deleteFrom.

What SQLite Runtime Covers

• table creation
• additive schema changes
• controlled rebuilds when destructive changes are needed
• dependency-aware destructive orchestration for dependent views and external triggers
• schema preview and audit history features
• transactions, triggers, and views
• entity-aware query helpers

Destructive Dependency Orchestration

SQLite can now detect dependent views and external triggers before a destructive table rebuild.

By default, reflect(...) blocks that rebuild and exposes the dependency list through planReflect(...).

Enable runtime orchestration explicitly when you want SQLQueryHelperjs to drop and recreate those dependent objects around the rebuild:

const db = new SqliteReflector({
	filename: "app.db",
	approvedDestructiveTableChanges: ["orders"],
	changeTicketId: "CHG-2042",
	orchestrateDestructiveDependencies: true,
});
Copy

This SQLite support is intentionally narrower than PostgreSQL. It focuses on objects discoverable from sqlite_master, not routines, procedures, materialized views, or a deeper engine-specific dependency graph.

Approved Column Renames

When a column rename is intentional and you need to preserve existing data, approve it explicitly instead of letting the runtime treat it as a drop-plus-add change.

const db = new SqliteReflector({
	filename: "app.db",
	approvedColumnRenames: [
		{ table: "orders", from: "customer_name", to: "display_name" },
	],
	approvedDestructiveTableChanges: ["orders"],
	changeTicketId: "CHG-2043",
});
Copy

approvedCaseOnlyColumnRenames still works for pure casing changes, but approvedColumnRenames is the general mechanism for arbitrary rename mappings such as name -> display_name.

Good Entry Points To Search

• SqliteReflector
• SqliteQueryBuilder
• SqliteInsertBuilder
• SqliteUpdateBuilder
• SqliteDeleteBuilder
• inspectSqliteSchema
• generateSqliteSchemaOutput

When To Use The Inspector API

Use the inspector functions when the database already exists and you need to generate model classes or inspect the current structure before adopting code-first reflection.

Inspector Fidelity Notes

The SQLite inspector now preserves advanced SQLite index features that previously degraded during generation.

• expression indexes are emitted through index([], { expressions: [...] })
• partial indexes are emitted through index([], { where: "..." })
• combined expression-plus-filter indexes are preserved in generated entity metadata and can be recreated through reflect(...)

This matters for legacy databases that rely on filtered uniqueness or computed index keys such as COALESCE(...).

If you re-inspect an older generated file and see a bare index([]) for an advanced SQLite index, regenerate it with a version that includes this fix.

When To Use Runtime Reflection

Use runtime reflection when the application owns the schema lifecycle and you want schema changes applied as part of application startup or controlled operational flows.

Compatibility Contract

Use DATABASE_ENGINE.md as the stricter compatibility contract when you need to know whether a capability is Full, Partial, Emulated, or Not available across engines.