Overview

Layeron Database (db) gives your backend app a named logical SQL store backed by Cloudflare D1 resources in your Cloudflare account.

You declare the database once in application code. Layeron provisions the underlying D1 resources in your Cloudflare account, applies migrations, and keeps route code on one consistent Database API whether the store has one D1 shard or many.

With Database, you can:

• Start with a single D1 shard for small and medium workloads.
• Use typed Table API helpers for CRUD workflows.
• Keep raw SQL through database.sql(...), database.statement(...), and database.exec(...).
• Execute atomic batches and transaction-style statement groups.
• Declare schema in code and generate SQL migrations from that schema.
• Stream table changes to WebSocket clients with realtime database.
• Scale a logical database across multiple D1 databases with D1 Plus.
• Declare shard keys for tables that need horizontal partitioning.
• Apply append-only schema migrations through Layeron’s deploy and dev flows.

Common Workflows

Database is designed around the workflows application developers repeat every day:

• Model tables with schema for generated SQL and typed rows.
• Use database.table("posts") for common create, read, update, delete, count, and existence checks.
• Use raw SQL for joins, custom SQLite expressions, reporting queries, and direct D1-compatible statements.
• Group related writes with database.batch(...) or database.transaction(...).
• Keep multiple logical stores distinct with stable platform identity.
• Choose a capacity mode once, then keep the route-level Database API stable as the store grows.

Core Concepts

Database has four central concepts:

• Database instance: A logical SQL store declared with db({ name }).
• Schema: A typed table declaration used for generated migrations and Table API row types.
• Migration: Append-only SQL that evolves the physical database layout.
• Shard policy: A table and key-column declaration used when a logical store expands across multiple D1 databases.

Capacity Model

Most apps start with a fixed one-shard database. When a workload needs a larger layout, the same logical store can use manual capacity and a sharding policy.

Mode	Use When	Shards
fixed	You want exactly one D1 database.	1
manual	You know the target shard count.	1, 2, 4, 8, 16, 32, or 64
auto	You want to declare future automatic expansion limits.	Starts from targetShardCount or 1

Auto capacity does not automatically expand shards yet. Automatic expansion is currently under development and testing, and is intended for the Layeron Control Plane rather than local direct deployments.

D1 Plus handles multi-shard placement behind the Database API. For a one-shard database, the same API stays available with a minimal single-D1 setup.

Next Steps

• Get started: Define a database, read and write rows, run SQL, group writes, choose capacity, and evolve schema.
• Core concepts: Understand instances, schema, raw SQL, migrations, capacity, and sharding policy.
• Schema: Declare typed tables, columns, indexes, and generated migrations.
• Table API: Use typed CRUD helpers, filters, pagination, counts, and transaction helpers.
• Raw SQL: Run direct SQLite/D1-compatible statements with params and result helpers.
• Batch and transactions: Group statements and handle per-shard execution.
• Migrations: Evolve schemas with schema-generated SQL, versioned migrations, and safety checks.
• Realtime database: Stream schema table changes over WebSockets.
• Capacity and sharding: Choose fixed, manual, or auto capacity.
• D1 Plus: Understand the sharded database layer behind higher-capacity logical stores.
• API reference: Review db(...), runtime helpers, migration input, capacity, and realtime options.