Reference › Elements

<db>

Database binding element. The compile-time anchor that connects a <schema> to a concrete database under ?{ … }.

Built-in state type Block element SPEC §8 (normative)

What it is

<db> is a state block, not an HTML element. The opener resolves against the unified state-type registry at name resolution: db is a built-in state type, so <db …> opens a first-class context rather than emitting a tag. Its body is ordinary markup context with the database connection in scope throughout — which is what gives every ?{ … } block inside it something concrete to run against.

Attributes

src= — the database file this block binds to.
tables= — which tables the block brings into scope. Required. Omitting it, or giving it an empty value, fires E-PA-005 from the protect analyzer.
protect= — names a protected column, for example protect="password". Optional; drives the protected-origin analysis that keeps a protected value from reaching the client.

Worked example

Compiled against the linked compiler and verified to build with exit 0.

<program db="./app.db" title="Posts">

    <schema>
        posts {
            id:        integer primary key
            title:     text not null
            author_id: integer not null
        }
    </>

    <db src="./app.db" tables="posts">
        ${
            function loadPosts(authorId) {
                return ?{`SELECT title FROM posts WHERE author_id = ${authorId}`}.all()
            }
        }
        <button onclick=loadPosts(1)>Load</button>
    </>

</>

`<db>` vs `<program db=>`

These are two different things, and an app commonly needs both pointing at the same file. <program db="…"> tells the compiler which database <schema> should migrate — it is the migration target. <db src="…"> establishes the SQL context that ?{ … } blocks execute in. A <schema> requires the former; a query requires the latter. Declaring the schema but forgetting db= on <program> leaves the write with no database, and the row is silently dropped.

Placement and server inference

A function whose body contains a ?{ … } query is escalated to the server by placement inference — SQL is one of the escalation triggers. You do not annotate this, and you should not try to. The consequence worth knowing is that such a function is no longer client-side, so it cannot assign to a reactive cell. That is E-RI-002. Return the value and let a client-side caller write the cell.

<schema> — declares the shape scrml migrate creates.
SQL context — what ?{ … } accepts and returns.
E-RI-002 — a server-escalated function assigning a reactive cell.
E-SQL-006 — .prepare() is removed in Bun.SQL.

Specification

Normative text: §4.2 (state-block classification and the deprecated whitespace opener form), §8 (SQL context and the query API), §44.7 (connection resolution), §14.8 (protected origins). Spec lives at compiler/SPEC.md .

← Reference