Reflection Pipeline Architecture (Advanced)

This document explains how table reflection is implemented internally in normlite.

Core Insight

Reflection is a process, not a single statement, but the execution pipeline only supports single-command execution. Normlite resolves this by orchestrating reflection at the Engine level.

Main Components

Inspector

User-facing reflection API.

Engine

Owns reflection orchestration via protected APIs such as _reflect_table().

Executable

Represents a single database command (e.g. CreateTable, ReflectTable).

ExecutionContext

Represents exactly one execution: one compiled statement, one cursor, one parameter set.

Pseudo-DDL Primitives

• CreateTable: checks for table existence, then creates the table.

• ReflectTable: checks for table existence, then reflects column metadata

Each primitive executes exactly one command.

Row-Based Reflection

Reflection results are returned as rows, one row per column:

(name, type_engine, column_id, value)

This mirrors SQLAlchemy’s information_schema.columns model.

ReflectedTableInfo

Intermediate structure that holds reflected column metadata and validates special columns.

Key Invariants

1. One executable = one DB command

2. ExecutionContext is single-use

3. Engine owns orchestration

4. DBAPI cursor remains dumb

5. Reflection always returns rows

Maintainers should preserve these invariants.