API reference

db(options) creates a Layeron module that declares an application database.

Import

import { db } from "@layeron/modules"

db(options)

Create a Layeron db module.

db(options: DbModuleOptions): DbModule

Options

Options accepted by db(options).

Field	Type	Description
name	string	Stable logical database name inside the Layeron app.
namespace	string | undefined	Platform namespace for the instance. Defaults to default.
capacity	DbCapacityOptions | undefined	Logical database capacity mode. Omit this field to use fixed capacity with one shard.
sharding	DbShardingOptions | undefined	D1 Plus sharding policy.
realtime	DbRealtimeOptions | undefined	Realtime database event streaming settings.
schema	Record<Layeron.Modules.Db.DbTableDefinition> | undefined	Declarative schema used to generate SQL migrations and typed Table API metadata.
databaseName	string | undefined	Cloudflare D1 database name.
binding	string | undefined	Custom binding name for advanced runtime access.
shared	DbSharedResourceOptions | undefined	Reference an existing Cloudflare D1 database in the same Cloudflare account. The owning project controls schema and migrations.
placement	Layeron.Common.Placement.LayeronPlacement | undefined	Placement overrides for this database product instance.
observability	Layeron.Observability.ObservabilityConfig | undefined	Observability settings for the database module.
sql	string | string[] | DbMigrationInput[] | undefined	One or more SQL migrations. Omit when schema declares the database shape.

database.sql(statement, params)

Create a query object for a SQL statement.

Signature

Create a query object for a SQL statement.

TypeSpec operation: databaseSql.

database.sql(statement: string | DbSqlRequest, params?: unknown[]): DbQuery

SQL request

SQL request object accepted by database.sql().

Field	Type	Description
statement	string	SQL statement.
params	unknown[] | undefined	SQL query parameters.
shard	DbShardHint | undefined	D1 Plus shard routing hint.

Query object

Query object returned by database.sql().

Field	Type	Description
statement	string	SQL statement.
params	unknown[]	SQL query parameters.
shard	DbShardHint | undefined	D1 Plus shard routing hint.

Result

Result returned by database SQL helpers.

Field	Type	Description
results	unknown[]	Rows returned by the SQL statement.
rows	unknown[]	Alias of results for row-oriented helpers.
meta	DbSqlResultMeta	Execution metadata such as changes, duration, shard, and batch count.

Shard hint

D1 Plus shard routing hint.

Field	Type	Description
table	string	Table name.
key	unknown	Shard key value.

Migration input

DbMigrationInput

Named SQL migration.

Field	Type	Description
name	string | undefined	Migration version. Layeron generates a name when omitted.
sql	string	SQL statements for the migration.
destructive	boolean | undefined	Marks the migration as destructive metadata. Apply still requires migration safety approval.

DbCapacityOptions

Logical database capacity settings.

Field	Type	Description
mode	”fixed” | “manual” | “auto”	Capacity mode. fixed uses one shard, manual uses the requested target shard count, and auto declares a future automatic expansion policy while starting from the requested target shard count or one shard.
targetShardCount	int32 | undefined	Target shard count. Valid values are powers of two from 1 to 64.
maxShardCount	int32 | undefined	Maximum shard count for future expansion. Valid values are powers of two from 1 to 64.

DbShardingOptions

D1 Plus sharding policy.

Field	Type	Description
tables	DbShardingTableOptions[]	Tables that can be routed by D1 Plus.

DbShardingTableOptions

D1 Plus table sharding settings.

Field	Type	Description
name	string	Table name.
keyColumn	string	Column used as the shard key.

DbRealtimeOptions

Realtime database event streaming settings.

Field	Type	Description
tables	Record<Layeron.Modules.Db.DbRealtimeTableOptions | boolean>	Tables that emit realtime database events.

DbRealtimeTableOptions

Realtime settings for one database table.

Field	Type	Description
events	”insert” | “update” | “delete”[] | undefined	Events to emit. Defaults to insert, update, and delete.
key	string | undefined	Primary key column included in event identity. Defaults to the schema primary key.
filters	string[] | undefined	Columns clients may use as equality filters in websocket subscriptions.
requiredFilters	string[] | undefined	Filter columns that every private subscription grant must include.
access	”private” | “public” | undefined	Subscription access mode. Private tables require a short-lived grant. Public tables allow direct websocket subscriptions.

TypeSpec symbols

This generated reference covers these TypeSpec symbols.

Kind	Symbol
model	DbModuleOptions
model	DbCapacityOptions
model	DbShardingOptions
model	DbShardingTableOptions
model	DbRealtimeOptions
model	DbRealtimeTableOptions
model	DbTableDefinition
model	DbColumnDefinition
model	DbIndexDefinition
model	DbSharedResourceOptions
model	DbMigrationInput
model	DbModule
model	DbRealtimeApi
model	DbRealtimeAuthorizeInput
model	DbRealtimeGrant
model	DbSqlRequest
model	DbShardHint
model	DbSqlResult
model	DbSqlResultMeta
model	DbQuery
model	DbBatchResult
model	DbBatchOptions
operation	db
operation	databaseSql
operation	databaseStatement
operation	databaseExec
operation	databaseBatch
operation	databaseTransaction
operation	dbQueryAwait
operation	dbQueryAll
operation	dbQueryRun
operation	dbQueryFirst
operation	dbQueryOne
operation	dbQueryMaybeOne
operation	dbQueryAs
operation	dbQueryJson

Runtime helpers

Helper	Description
await database.sql(...)	Executes in automatic query mode.
.all()	Executes and returns all rows.
.run()	Executes a statement intended for writes.
.as(key)	Returns rows wrapped in a named JSON object.
.json(key?, init?)	Returns a JSON Response.