Queries & caching

Reading

Reach the database with the ambient db (the data model explains why it's ambient and off ctx) and query it:

import { db } from "@junejs/db";

export const loader = async () => ({
  users: await db.query("select id, name from users order by id"),
});

The dev default is a plain file at .june/dev.sqlite that survives the dev server's reload-on-save restarts — and the sqlite3 already on your machine opens it directly:

sqlite3 .june/dev.sqlite '.tables'

Migrations — the SQL you read is the SQL that runs

A connected database does not invent tables. Schema lives in versioned SQL you can read and diff:

-- db/migrations/0001_init.sql
create table users (id integer primary key, name text not null);

june dev applies pending migrations on startup — safe, additive ones automatically (create table, add column, a new index). A destructive change (drop, a narrowing alter) halts with the safe prefix already applied and asks first; you run it deliberately with june db migrate --allow-destructive. Add the next change as 0002_*.sql — never edit an applied file. The same ordered ledger runs at deploy against D1, so dev and production converge on one schema.

Caching — auto-tag, auto-invalidate, auto-batch

Reads and writes flow through a small public trace contract, which is all the framework needs to make caching a consequence of the write, not a chore:

import { db } from "@junejs/db";

const listUsers = cache(() => db.table("users").all());   // tagged [table:users]
await invokeAction("createUser", { name: "Ada" });        // writes users →
await listUsers();                                        // cache MISS — fresh

• auto-tag — every cache() entry is tagged by the tables it read.
• auto-invalidate — a write to a table drops exactly those entries. No revalidatePath, no tags to remember, no manual revalidate() — ever.
• auto-batch — N component reads of the same query on one render collapse to a single round trip (measured: 8.8× fewer D1 queries vs naive per-component reads — see Benchmarks).

Stale-cache bugs are the classic failure of hand-wired revalidate() calls, and agents forget them exactly as often as humans do. Making invalidation fall out of the write removes the whole class.

kv and blob

The other resources follow the same ambient shape — memoryKv() / localBlob() in dev, redisKv() / r2() on deploy — reached as ambient kv and blob:

import { kv, blob } from "@junejs/db";

await kv.set("greeting", "hi");
await blob.put("avatar.png", bytes);

Status: Changing — see Stability.