Registry / database / durable-objects-sql-tag

durable-objects-sql-tag

JSON →
library0.3.0jsnpmunverified

A TypeScript library (v0.3.0) providing a templated SQL tag and database wrapper for Cloudflare Durable Objects SQLite storage. It simplifies parameterized queries with `sql` tagged templates, includes a migration system with schema versioning and automatic column alterations, and offers safe helpers (queryOne, queryMany, run, etc.) that guard against injection and common mistakes. Active development with weekly releases on npm.

npm install durable-objects-sql-tag
INSTALL
IMPORT
SIG · DURABLE-OBJECTS-SQ
D
durable-objects-sql-tag
databasejavascriptv0.3.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

sql
import { sql } from 'durable-objects-sql-tag'
import sql from 'durable-objects-sql-tag'
sql is a named export, not default.
wrapDatabase
import { wrapDatabase } from 'durable-objects-sql-tag'
const { wrapDatabase } = require('durable-objects-sql-tag');
Package is ESM-only; require() will fail.
MigrationVersionDefinition
import type { MigrationVersionDefinition } from 'durable-objects-sql-tag'
import { MigrationVersionDefinition } from 'durable-objects-sql-tag'
It's a TypeScript type, use import type to avoid runtime error.

Complete Durable Object class using wrapDatabase with migrations and basic queries.

import { DurableObject } from 'cloudflare:workers'; import { sql, wrapDatabase, type MigrationVersionDefinition } from 'durable-objects-sql-tag'; const migrations: MigrationVersionDefinition[] = [ { name: 'Create users table', migrate(db) { db.run(sql`CREATE TABLE users (id TEXT PRIMARY KEY, name TEXT NOT NULL, email TEXT NOT NULL UNIQUE) STRICT`); }, }, ]; export class MyDurableObject extends DurableObject { private db; constructor(ctx: DurableObjectState, env: Env) { super(ctx, env); this.db = wrapDatabase(ctx.storage); ctx.blockConcurrencyWhile(() => this.db.migrate(migrations)); } async fetch(request: Request): Promise<Response> { const user = this.db.queryOne<{ id: string; name: string }>(sql`SELECT * FROM users WHERE id = ${'abc'}`); const users = this.db.queryMany<{ id: string; name: string }>(sql`SELECT * FROM users WHERE status = ${'active'}`); this.db.run(sql`INSERT INTO users (id, name, email) VALUES (${'id'}, ${'name'}, ${'email'})`); return new Response('OK'); } }
Debug
Known issues
gotchaqueryOne throws if zero or more than one row is returned; use queryNoneOrOne for optional rows.
fix
Use queryNoneOrOne when expecting 0-1 rows.
affects: >=0.1.0
gotchaqueryNone throws if any rows are returned (e.g., accidentally running SELECT with it).
fix
Use run() for statements that may return rows, or ensure only non-SELECT statements are passed.
affects: >=0.1.0
gotchawrapDatabase expects ctx.storage (DurableObjectStorage), not something else.
fix
Always pass ctx.storage from DurableObject constructor.
affects: >=0.1.0
gotchaMigrations run asynchronously; must be awaited inside blockConcurrencyWhile.
fix
Wrap this.db.migrate(migrations) inside ctx.blockConcurrencyWhile(() => this.db.migrate(migrations)).
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: Cannot use 'require' to import an ES Module
Package is ESM-only; CommonJS require() not supported.
fix
Use import syntax or set your project to ESM.
Error: Migration failed: no such table: ...
Migrations not run or blockConcurrencyWhile not used.
fix
Ensure this.db.migrate(migrations) is called and awaited inside ctx.blockConcurrencyWhile in the constructor.
Error: Expected exactly one row but got 0
Using queryOne on a query that returns zero rows.
fix
Use queryNoneOrOne if the row may not exist, or check data.
Upgrade
Version history
0.3.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
8 hits · last 30 days
node
8
Resources
durable-objects-sql-tag — npm install durable-objects-sql-tag · libregistry