edgeway 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7271c053efc7a3ce130edd6347262ddc8166650a6bc70cc172c30befe3c5372
-  data.tar.gz: d0b25d4d34619575a7933aad50bed1c4885da6d8078bfa2308e0c8004da6ab8a
+  metadata.gz: 9800b1c381a9b0eabd63071ed84bec91abb5ac85e972695bd552a5ba67aca46c
+  data.tar.gz: b04ff64800edf5baa49a556309691839d155fbfce3246210e49f775431afd0ee
 SHA512:
-  metadata.gz: 7859d0d22cb99f390c079bdd265567da3cba5c10f0a417a185f62551f322b118972107be922a79960c95b39b0be718a0999acb2130ddccf51fa38ede989ee391
-  data.tar.gz: 8da347d44a4e0debb86aa4b0aa3a247fdca6063da45315b3bfddc28ac112a966c1ef2dd2020165f7ba98c1f5e789a8929424eef9a1d0c37efb607a70305d15db
+  metadata.gz: 131183da9841be36432cbe37a23dd905e167411311c70dbaee9a2fb87c65c2ab6f156dcc732b0fa17b8ae47ef167e58c57c685953309aa83dec138887f746950
+  data.tar.gz: 948c56cb42f175a146051d571d5927f44232c04857535c5d887eb5fd60a69514ecc22ad8e1b3a182a88f8835b180804c17670e23a9fbb7bb6a1aa2b0e947a460

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## Unreleased
+
+## v0.2.0
+
+### Added
+
+- Views: ERB templates in `app/views`. `<%= %>` escapes unless the value is `raw(text)` / `text.html_safe`, and `render html:` escapes anything but a `SafeHTML`. An action that renders nothing renders its template when there is one (else 204 as before), and `render` raises `Edgeway::MissingTemplate` when its template is missing ([#1](https://github.com/y-yagi/edgeway/pull/1)).
+- `edgeway generate scaffold`: a model, its migration, a JSON API controller and their tests, and `r.resources` added to `config/routes.rb`.
+  `generate model` and `scaffold` stop if the table's create migration exists ([#2](https://github.com/y-yagi/edgeway/pull/2)).
+- Apps made by `edgeway new` get `bin/test`, a GitHub Actions workflow and a `.ruby-version`.
+- D1:
+  - `NotNullViolation`, `InvalidForeignKey` and `CheckViolation` (500), and `DatabaseUnavailable` (503 with `Retry-After: 1`) for D1's transient errors ([#4](https://github.com/y-yagi/edgeway/pull/4)).
+  - Raw SQL (`find_by_sql`, `Edgeway::Model.select_all`, `Edgeway::Model.execute`), and `where` with Arrays (`IN`), Ranges and SQL fragments.
+    More than 100 bound parameters in a statement raises `ArgumentError` (`limit` and `offset` don't count) ([#5](https://github.com/y-yagi/edgeway/pull/5)).
+  - `Edgeway::Model.query_stats` and a `db=… rows_read=… rows_written=… db_ms=…` log line per request ([#6](https://github.com/y-yagi/edgeway/pull/6)).
+  - `:binary` and `:bigint` attribute types; a rowid beyond 32 bits works. `Edgeway::Model.blob` binds a BLOB in raw SQL,
+    and `Edgeway::Model.cast(:bigint, value)` reads a large integer from a raw row ([#7](https://github.com/y-yagi/edgeway/pull/7)).
+  - Several databases: `databases:` in `config/database.yml` and `self.database = :name`; `database:` for `select_all`/`execute`,
+    `query_stats(:name)`, and `db(:name)` in tests ([#9](https://github.com/y-yagi/edgeway/pull/9)).
+  - Read replication through the Sessions API: `sessions: true`, with the bookmark in an `X-D1-Bookmark` header
+    (added to `Vary` and, with CORS, to the allowed and exposed headers); only `GET`/`HEAD` start from it, other methods always start `first-primary` ([#10](https://github.com/y-yagi/edgeway/pull/10)).
+  - `Edgeway::Model.exec` for D1's `exec()` ([#11](https://github.com/y-yagi/edgeway/pull/11)).
+
+### Changed
+
+- `edgeway build` passes Spinel's `--incremental`; `--release` builds as one unit, and the generated `bin/deploy` and CI use it ([#8](https://github.com/y-yagi/edgeway/pull/8)).
+- The Spinel that Edgeway and the `mise.toml` of `edgeway new` pin is `ec0ad13e4` (was `530ba2b17`) ([#3](https://github.com/y-yagi/edgeway/pull/3), [#8](https://github.com/y-yagi/edgeway/pull/8)).
+- A Time in a query is bound as ISO 8601 UTC with milliseconds (`2026-10-28T05:00:00.000Z`), as timestamps are stored ([#5](https://github.com/y-yagi/edgeway/pull/5)).
+
+## 0.1.0
+
+- First release.

data/README.md

@@ -39,12 +39,20 @@ end
 ## Contents
 
 - [Models](#models)
+  - [Attribute types](#attribute-types)
   - [Strong parameters](#strong-parameters)
   - [Uniqueness](#uniqueness)
+  - [Database errors](#database-errors)
   - [Ordering and deleting](#ordering-and-deleting)
+  - [Queries](#queries)
+  - [Query stats](#query-stats)
   - [Batch](#batch)
   - [Associations](#associations)
   - [Eager loading](#eager-loading)
+  - [Multiple databases](#multiple-databases)
+  - [Read replication (Sessions)](#read-replication-sessions)
+  - [D1 API coverage](#d1-api-coverage)
+- [Views](#views)
 - [Usage](#usage)
   - [Generators](#generators)
   - [Building](#building)
@@ -59,6 +67,45 @@ end
 
 ## Models
 
+### Attribute types
+
+| Type | Ruby value | SQLite column | In JSON |
+| --- | --- | --- | --- |
+| `:string`, `:text` | String | TEXT | string |
+| `:integer` | Integer (32 bits) | INTEGER | number |
+| `:float` | Float | REAL | number |
+| `:boolean` | `true`/`false` | INTEGER (1/0) | `true`/`false` |
+| `:datetime` | String, ISO 8601 UTC | TEXT | string |
+| `:binary` | binary String (`.b`) | BLOB | base64 string |
+| `:bigint` | decimal String (`"3000000000"`) | INTEGER | string |
+
+- Integers are 32 bits in a wasm build. A `:integer` value beyond -2147483648..2147483647 casts to `nil`; use `:bigint` for those columns.
+  Assigning one is refused by validation ("is out of range"). A row that already holds one (a foreign key to a bigint parent
+  declared as `:integer`) loads as `nil`, and saving it fails the same way instead of writing `NULL` over it.
+- A `:bigint` holds its value as a String of an optional `-` and digits, without leading zeros (`"-0"` is `"0"`);
+  anything else, or a value beyond 64 bits, casts to `nil` ("is invalid"). It is bound as text and SQLite's INTEGER affinity
+  stores it as an integer, so `where`, `order` and comparisons work on the number.
+  It renders in JSON as a String, which JavaScript clients read exactly.
+  D1 hands rows over as JavaScript numbers, so a value beyond 2^53 (9007199254740991) has already lost precision before Ruby sees it.
+  Keep such values below 2^53, or store them as `:string`.
+- Pass bigint values as Strings: `Todo.find("3000000000")`, `where(id: "3000000000")`, `create!(owner_id: "5000000000")`,
+  `Model.execute("... WHERE id = ?", ["3000000000"])`. A Hash holding an Integer literal beyond 32 bits raises `RangeError` in a wasm build
+  (a Spinel limitation), so do not write them as Integers.
+- `attribute :id, :bigint` makes the primary key a bigint: `find`, `where(id: ...)`, `update`, `destroy` and an insert
+  (`RETURNING id`) work past 2^31, and `id` is a String. A foreign key to it is `attribute :owner_id, :bigint`
+  (declare it before `belongs_to` and it keeps its type).
+- Rows from raw SQL (`Model.select_all`) hold what the database gave: in a wasm build an INTEGER beyond 32 bits is a Bignum,
+  and `render json:` of it raises. Select it as text (`SELECT CAST(id AS TEXT) AS id ...`) or pass it through `Edgeway::Model.cast(:bigint, value)`.
+- A `:binary` attribute holds a binary String. Assigned from Ruby, a String keeps its bytes (`Document.new(body: bytes)`), and so does a `{"$blob" => base64}` Hash.
+  It is bound as a BLOB (`where(body: bytes)` too), and renders in JSON as a base64 String.
+  In a request body the value is that base64 String, so a GET then PATCH round trip is stable: params assigned through `permit` are decoded,
+  and invalid base64 fails validation ("is invalid"). `{"$blob": ...}` objects are not supported in a request body (nested objects are dropped).
+  `presence` counts a binary String blank only when empty, and `length` counts bytes.
+  A BLOB crosses between wasm and JS as `{"$blob": "<base64>"}`: binds and rows cross as JSON text, which can't hold arbitrary bytes.
+  In raw SQL (`Model.select_all`, `Model.execute`, `where("...", value)`) bind a BLOB with `Edgeway::Model.blob(bytes)`,
+  and a BLOB column comes back as `{"$blob" => base64}`.
+- `Model.execute` answers `"last_insert_id"` as an Integer, or as a decimal String when the rowid is beyond 32 bits.
+
 ### Strong parameters
 
 Params must go through `permit` before a model takes them.
@@ -92,6 +139,22 @@ Project.where(owner_id: uid).find_or_create_by(name: "default")
   the database's message (table and columns) goes only to the log.
 - A controller can `rescue_from Edgeway::RecordNotUnique` to answer otherwise.
 
+### Database errors
+
+All are `Edgeway::DatabaseError`; the database's message goes only to the log.
+
+- `NotNullViolation`, `InvalidForeignKey` and `CheckViolation` (a constraint the app broke):
+  answered 500 `{"error":"internal error"}`, like any other `DatabaseError`.
+- `DatabaseUnavailable` (D1 lost its connection, was reset or is overloaded):
+  answered 503 `{"error":"database unavailable"}` with `Retry-After: 1`.
+- A controller can `rescue_from` any of them to answer otherwise.
+  `rescue_from Edgeway::DatabaseError` also catches `DatabaseUnavailable` and `RecordNotUnique`,
+  so it replaces their default 503 and 409.
+- D1 retries read-only queries itself. Edgeway never retries a query, a write or a batch.
+- A write that got a 503 may still have been applied:
+  only an idempotent request (a GET, or a write the app made idempotent) is safe to retry.
+- Timeouts and CPU or memory limits stay a plain `DatabaseError` (500).
+
 ### Ordering and deleting
 
 ```ruby
@@ -115,6 +178,60 @@ class Todo < ApplicationModel
 end
 ```
 
+### Queries
+
+```ruby
+Todo.where(id: [1, 2])                    # id IN (?, ?)
+Todo.where(position: 1..5)                # position >= ? AND position <= ?
+Todo.where(position: (3..))               # position >= ?
+Todo.where("title LIKE ?", "%x%")         # (title LIKE ?)
+Todo.where("done = 1")
+
+Todo.find_by_sql("SELECT * FROM todos WHERE done = ?", [true])   # records
+Edgeway::Model.select_all("SELECT COUNT(*) AS n FROM todos", [])  # row Hashes
+Edgeway::Model.execute("DELETE FROM todos WHERE done = ?", [true]) # {"changes" => n, "last_insert_id" => id}
+Edgeway::Model.exec("DELETE FROM tags\nDELETE FROM todos")        # nil
+```
+
+- `where(column: value)` is `=`, `IS NULL` for `nil`. Every form chains, and works with `order`, `limit`, `count`, `delete_all`, `eager_load` and `todo.comments.where(...)`.
+- An Array is `IN`; each value is cast by the column type. An empty Array matches nothing (`1 = 0`).
+  A `nil` in an Array also matches `NULL`: `(position IN (?) OR position IS NULL)`.
+- A Range is `>=` and `<=` (`<` for `1...5`); an endless or beginless Range has one side.
+  Spinel can't build a Range of Times: use ISO 8601 Strings (`"2026-10-28"..."2026-10-29"`) or a fragment.
+- A String is a raw SQL fragment, in parentheses and ANDed with the rest; its binds follow it.
+  It is raw SQL: put user input in the binds, never interpolate it.
+  Its binds are not cast by column type: only booleans (1/0) and Times (ISO 8601) are converted.
+  An Array bind raises `ArgumentError` (not expanded): use `where(column: [...])`.
+- `build`/`create`/`find_or_create_by` on a relation copy only the plain equality conditions.
+- `find_by_sql` makes records of the rows, so select the model's columns (`SELECT *` or each of them): a missing one is `nil`.
+- `Model.select_all` and `Model.execute` take `?` placeholders. Booleans are bound as 1/0, and a Time as ISO 8601 UTC (`2026-10-28T05:00:00.000Z`, as timestamps are stored), also in `where` values.
+  `execute` is a write, so inside `Model.batch` it is queued (and answers 0 counts).
+- `Model.exec` is D1's `exec()`: one or more statements with no binds, and it answers `nil`. Meant for one-off maintenance, as D1 says.
+  A statement must fit on one line (D1 splits the text at newlines); `a; b` on one line also works. Empty SQL raises `ArgumentError`.
+  When a statement fails, none of them stay applied (seen on local D1; the SQLite adapter in tests does the same).
+  D1's error message names the first line, not the one that failed.
+  It can't run inside `Model.batch` (`ArgumentError`), and fails on a database with `sessions: true` (`DatabaseError`): a D1 session has no `exec()`.
+- D1 allows 100 bound parameters per statement: more raises `ArgumentError`, in every adapter (`limit` and `offset` are literals, not binds).
+  `where(id: ids)` with over 100 ids needs chunking.
+
+### Query stats
+
+`Edgeway::Model.query_stats` (it raises `ConfigurationError` without a connection) is what D1 reported for the queries of the current request
+(a wasm instance serves one request, so it starts at zero):
+
+- `queries`: the number of successful D1 calls (a `Model.batch` is one). A failed call and its time are not counted.
+- `rows_read`, `rows_written`: the sums of D1's `meta`, capped at 2147483647 (32-bit; the log line shows a capped count with a trailing `+`).
+- `duration_ms` (Float): the sum of D1's `meta.duration`.
+- `served_by_region` and `served_by_primary`: from the last call (`""` and `true` when D1 doesn't say, as in `wrangler dev`).
+
+When a request ran any query, `Edgeway::Server` logs one line after it, also for a request that raised and was rescued:
+
+```
+[edgeway] db=3 rows_read=12 rows_written=1 db_ms=2.46
+```
+
+The Memory and SQLite adapters report zeros and log nothing.
+
 ### Batch
 
 `Edgeway::Model.batch` makes several writes atomic.
@@ -179,6 +296,116 @@ Todo.eager_load(:comments, :tags)   # several at once, still one query
 - Only `to_a` and what is built on it (`each`, `map`, `size`) read the loaded records;
   `comments.where(...)`, `count` and `first` query as usual.
 
+### Multiple databases
+
+A model uses the primary database unless it names another, declared in `config/database.yml` (see "Configuration"):
+
+```ruby
+class Event < ApplicationModel
+  self.database = :analytics   # inherited by subclasses
+  attribute :name, :string
+end
+
+Event.create!(name: "signup")
+Edgeway::Model.select_all("SELECT COUNT(*) AS n FROM events", [], database: :analytics)
+Edgeway::Model.execute("DELETE FROM events", [], database: :analytics)
+```
+
+- Every query and write of a model goes to its database, including `find_by_sql`.
+  `Model.select_all` and `Model.execute` use the primary unless given `database:`.
+- Associations between models on different databases work as separate queries.
+  A `has_many` with `dependent:` to a model on another database raises `ArgumentError` on `destroy`, before any query: it can't be atomic.
+  `eager_load` across databases raises `ArgumentError`: a `JOIN` can't cross them.
+- A `Model.batch` belongs to the database of its first write; a write for another one raises `ArgumentError`
+  (D1 batches are per database). Use one `batch` per database.
+- `Edgeway::Model.query_stats(:analytics)` is that database's stats. The request log has one line per database that ran queries,
+  and the extra ones start with `database=analytics`.
+
+### Read replication (Sessions)
+
+With D1 read replication enabled for a database (dashboard, or `PUT` its settings), reads can be served by a replica near the user.
+A replica may lag, so D1's Sessions API keeps a request sequentially consistent through a bookmark. Opt in per database in `config/database.yml`:
+
+```yaml
+production:
+  adapter: d1
+  binding: DB
+  sessions: true
+  databases:
+    analytics:
+      binding: ANALYTICS
+      sessions: true
+```
+
+`sessions:` must be `true` or `false` (anything else fails the build), and does nothing with the `memory` adapter.
+Every query and `Model.batch` of such a database then goes through `env.DB.withSession(...)`, created on first use and kept for the request.
+
+- A `GET` or `HEAD` starts from the bookmark the client sent, else `first-unconstrained`, so it may read a replica. Other methods always start `first-primary` and ignore the sent bookmark.
+- The response has `X-D1-Bookmark: DB=<bookmark>, ANALYTICS=<bookmark>`: a `BINDING=bookmark` pair for each session the request used (also with one database).
+- A client that sends that header back as it is on its next request starts that session from the bookmark and so reads its own writes (`GET` and `HEAD` only). On a `GET` or `HEAD`, a binding that is not in the header starts `first-unconstrained`. A bookmark is D1's and opaque; one that does not look like it (not lowercase hex and `-`, or over 128 characters) is ignored, and not echoed.
+- A database the request did not use keeps the bookmark the client sent for it in the response (on any method), so the client just stores the latest header value whole and sends it back.
+- Responses of an app with sessions get `Vary: X-D1-Bookmark`.
+- With CORS on, `X-D1-Bookmark` is exposed to the page and allowed in preflights (no need to add it to `CORS_HEADERS` or `CORS_EXPOSE_HEADERS`).
+- `Edgeway::Model.query_stats(:analytics)` has `served_by_primary` and `served_by_region` of the last query, to see which one answered (`true` and `""` in `wrangler dev`, which has no replicas).
+
+### D1 API coverage
+
+| D1 Worker API | In Edgeway |
+| --- | --- |
+| `prepare().bind().all()` | every query, `find_by_sql`, `Model.select_all`, and inserts (`INSERT ... RETURNING id`) |
+| `prepare().bind().run()` | updates and deletes, `Model.execute` |
+| `batch()` | `Model.batch` (and `destroy` with dependents) |
+| `exec()` | `Model.exec` |
+| `withSession()`, `getBookmark()` | `sessions: true` ([Read replication](#read-replication-sessions)) |
+| `result.meta` | `Model.query_stats` and the `db=…` log line |
+| `first()`, `raw()` | not used: `find_by`/`first` send `LIMIT 1` through `all()`, which also keeps `meta`; `raw()` made the JSON smaller but rebuilding the rows in Ruby cost as much as it saved |
+| `dump()` | not supported (alpha databases only) |
+
+Time Travel, export/import and migrations are `wrangler d1` commands, outside the Worker API.
+
+## Views
+
+```ruby
+# app/controllers/todos_controller.rb
+class TodosController < ApplicationController
+  def index
+    @todos = Todo.order(:id).limit(50)
+    # renders app/views/todos/index.html.erb
+  end
+end
+```
+
+```erb
+<%# app/views/todos/index.html.erb %>
+<ul>
+<% @todos.each do |t| -%>
+  <li><%= t.title %></li>
+<% end -%>
+</ul>
+```
+
+Spinel has no `eval`, so `edgeway build` (and `edgeway test`) compile `app/views/**/*.html.erb` into Ruby
+(`build/views.rb`, `tmp/views.rb`): each template becomes a method of its controller,
+so it sees the action's `@variables`, `params` and the controller's methods.
+
+- `<%= expr %>` is HTML-escaped (`Edgeway::View.escape`) unless the value is `raw(text)` or `text.html_safe`
+  (an `Edgeway::View::SafeHTML`); `<%== expr %>` is never escaped.
+  Safety is not kept across string operations (`"<b>".html_safe + x` is not defined): build the HTML in a template,
+  or escape the pieces with `Edgeway::View.escape` and mark the result.
+  `<% code %>`, `<%# comment %>`, `<%%` (a literal `<%`) and `-%>` (drops the newline after the tag) work as in ERB.
+- The public methods of `Edgeway::Controller::Base` (`render`, `head`, `params`, `raw`, ...) are not actions; a route to one is a 404.
+- An action that renders nothing renders its template, or answers 204 when it has none.
+- `render :name` / `render "name"` renders another template of the controller, `render html: value` a string (HTML-escaped; a `SafeHTML` is output as is);
+  both take `status:` and `layout: false`.
+  A name with no template raises `Edgeway::MissingTemplate` (a 500).
+- `app/views/layouts/application.html.erb` wraps every HTML response, at `<%= yield %>`. `edgeway new` writes one.
+- HTML responses are `Content-Type: text/html; charset=utf-8` with `X-Content-Type-Options: nosniff`.
+- A template's directory names its controller (`app/views/admin/posts/` is `Admin::PostsController`);
+  one without a controller is a build error, and so is a syntax error in a template,
+  which Spinel reports in the generated file (its `# app/views/...:LINE` comments point back).
+
+Not supported yet: partials (`render partial:`), layouts other than `application`, and templates other than `.html.erb`.
+
 ## Usage
 
 ```sh
@@ -190,15 +417,18 @@ edgeway new myapp
 cd myapp && bin/setup
 
 # the app's tests, natively (needs libsqlite3-dev, see "Testing an app")
-bundle exec edgeway test
+bundle exec edgeway test        # or bin/test [FILE...] in a generated app
 
-# edgeway build: writes build/app.wasm and build/edgeway/ (the JS)
+# edgeway build: writes build/app.wasm and build/edgeway/ (the JS).
+# A development build: Spinel's --incremental caches the generated C in units,
+# so a rebuild recompiles only what changed (no inlining across units)
 bin/build
 
 pnpm exec wrangler dev
 edgeway routes
 
-# bin/build, remote D1 migrations, then pnpm exec wrangler deploy
+# bin/build --release (one unit, without --incremental), remote D1 migrations,
+# then pnpm exec wrangler deploy
 bin/deploy
 ```
 
@@ -213,6 +443,7 @@ Before `bin/deploy`:
 `bin/setup` prints these steps when they are missing.
 
 - A generated app's Gemfile takes `edgeway` and `spinel_test-unit` from RubyGems.
+- A generated app's `.github/workflows/ci.yml` installs libsqlite3-dev, Ruby (from `.ruby-version`, which `edgeway new` writes with the Ruby that ran it), and mise's tools, then runs `bin/test` and `bin/build --release`.
 - An app uses [pnpm](https://pnpm.io/) for wrangler (`package.json`, `bin/setup`, `mise.toml`);
   `edgeway new` names it in one place (`Edgeway::CLI::PackageManager`).
 - `SPINEL=/path/to/spinel bin/build` uses a Spinel other than the one on `PATH`.
@@ -228,13 +459,19 @@ edgeway generate model Todo title:string done:boolean
 
 # app/controllers/todos_controller.rb, test/controllers/todos_test.rb
 edgeway generate controller Todos index show
+
+# the model's files, a JSON API controller (index, show, create, update, destroy) and its test
+edgeway generate scaffold Todo title:string done:boolean
 ```
 
 - Field types are `string` (the default), `text`, `integer`, `float`, `boolean` and `datetime`.
 - A model gets `timestamps` and an `id`, `created_at` and `updated_at` column.
 - The migration is numbered one above the highest in `db/migrations`.
 - Each action of a controller is a stub that renders `{}`.
-- `config/routes.rb` is not changed: the command prints the route to add (`r.resources :todos`).
+- `config/routes.rb` is not changed by `model` and `controller`: the command prints the route to add (`r.resources :todos`).
+- `model` and `scaffold` stop if a `db/migrations/*_create_todos.sql` already exists (a rerun would add a second table).
+- `scaffold` singularizes its name (`scaffold Todos` is `Todo`), checks that none of its files exist before it writes one, and adds `r.resources :todos` as the last line of the `routes.draw` block, so that it does not shadow an earlier `/todos/search`. It leaves a route that is already there alone, and prints the route and the reason instead if there is no `routes.draw do |r|` block with a closing `end`.
+- The scaffold's controller permits the given fields (`params.require(:todo).permit(...)`), and with no fields it takes no params.
 
 ### Building
 
@@ -254,7 +491,7 @@ Edgeway needs a Spinel newer than the 2026.09.12 release
 (that release refuses `send` with a computed name, which `Callbacks#run_before_actions` uses).
 
 - `mise.toml` (Edgeway's own and the one `edgeway new` writes) pins a commit of [matz/spinel](https://github.com/matz/spinel),
-  `530ba2b17`, which mise-spinel builds from source.
+  `ec0ad13e4`, which mise-spinel builds from source.
   A commit rather than `master`, so that an install is the Spinel that was tested.
 - The WASI SDK (`wasi-sdk-34`) is installed first,
   because mise-spinel builds Spinel's wasm32-wasi runtime only when it finds one.
@@ -269,8 +506,14 @@ Edgeway needs a Spinel newer than the 2026.09.12 release
   and only `Authorization: Bearer` is read (see [Authentication](#authentication)).
 - Tests run natively, not in wasm: D1 and JSPI (`Edgeway::Cloudflare::JWTVerifier`) are not covered by them,
   and the production wasm never loads the SQLite adapter (see [Testing an app](#testing-an-app)).
-- Not verified on a production Cloudflare deploy yet: CPU and wall time on a cold start and on a JWKS cache miss.
-  Everything was checked under `wrangler dev`.
+- Not verified on a production Cloudflare deploy yet: CPU and wall time on a cold start and on a JWKS cache miss,
+  and read replication with real replicas (local D1 has none, and D1 itself accepts any bookmark there). Everything was checked under `wrangler dev`.
+- Integers are 32 bits in a wasm build: use `:bigint` for larger ones and pass them as Strings,
+  and keep them below 2^53, as D1 hands rows over as JavaScript numbers (see [Attribute types](#attribute-types)).
+- A `Model.batch` runs on one database: there is no transaction across databases ([Multiple databases](#multiple-databases)).
+- `Model.exec` does not work on a database with `sessions: true`: a D1 session has no `exec()` ([Queries](#queries)).
+- Spinel can't build a Range of Times: use ISO 8601 Strings or a SQL fragment in `where` ([Queries](#queries)).
+- `first()` and `raw()` are not used and `dump()` is not supported; Time Travel and export/import are `wrangler d1` commands ([D1 API coverage](#d1-api-coverage)).
 
 ## Configuration
 
@@ -281,6 +524,22 @@ Two files configure the database, each for its own side:
 - `wrangler.toml` is Cloudflare's: which D1 database the binding is (`database_name`, `database_id`),
   the migrations, and the Worker. `binding` in it must match `binding` in `config/database.yml`.
 
+Another database goes under `databases:` of an environment, with its own binding in `wrangler.toml`:
+
+```yaml
+production:
+  adapter: d1
+  binding: DB
+  databases:
+    analytics:
+      binding: ANALYTICS
+```
+
+Its migrations are in `db/analytics/migrations` (`migrations_dir` of its `[[d1_databases]]`; apply them per database).
+A name is lowercase letters, digits and `_`, and not `primary`; `binding:` is required.
+The extra databases use the environment's adapter.
+`sessions: true` next to `binding:` (in the environment for the primary, in the entry for another) turns on D1 Sessions for it; see "Read replication (Sessions)".
+
 `database_id` is not a secret: it only names the database, and using it takes an API token of the account,
 so it is committed with `wrangler.toml` as Cloudflare's own examples do.
 Secrets the app needs go in Worker secrets (`pnpm exec wrangler secret put NAME`),
@@ -363,9 +622,9 @@ Settings are Worker variables in `wrangler.toml`:
 | Variable | |
 |---|---|
 | `CORS_ORIGINS` | allowed origins, comma-separated, compared as exact strings with the request's `Origin` (`https://app.example, http://localhost:3000`; no trailing slash). `*` allows any origin. Unset or empty means CORS is off: nothing is added and `OPTIONS` goes to the app. The origin `null` (sandboxed iframes, `file:` pages) is never allowed, even with `*` |
-| `CORS_HEADERS` | request headers a preflight allows (default `Authorization, Content-Type`). Listed one by one, as `*` does not cover `Authorization` |
+| `CORS_HEADERS` | request headers a preflight allows (default `Authorization, Content-Type`). Listed one by one, as `*` does not cover `Authorization`. `X-D1-Bookmark` is added when a database has `sessions: true` |
 | `CORS_MAX_AGE` | seconds a browser may cache a preflight (default `600`). Not a non-negative integer: every request is answered 500, as with a bad JWT setting |
-| `CORS_EXPOSE_HEADERS` | response headers the page may read (`Access-Control-Expose-Headers`, e.g. `X-Total-Count`); none by default |
+| `CORS_EXPOSE_HEADERS` | response headers the page may read (`Access-Control-Expose-Headers`, e.g. `X-Total-Count`); none by default, except `X-D1-Bookmark` when a database has `sessions: true` (it is also merged into the app's own `Access-Control-Expose-Headers`) |
 
 - A preflight from an allowed origin is answered 204 with `Access-Control-Allow-Origin` (the request's origin),
   `Access-Control-Allow-Methods` (`GET, HEAD, POST, PUT, PATCH, DELETE`), `Access-Control-Allow-Headers` and `Access-Control-Max-Age`.
@@ -380,6 +639,7 @@ Serving the frontend from the same origin as the API avoids CORS altogether.
 
 ```sh
 bundle exec edgeway test [ARGS]   # ARGS go to spinel_test-unit
+bin/test [FILE...]                # in a generated app: the same, all of test/ without FILE
 ```
 
 `edgeway test` is the only supported way to run an app's tests.
@@ -399,6 +659,7 @@ bundle exec edgeway test [ARGS]   # ARGS go to spinel_test-unit
 
 Each test runs against a real in-memory SQLite database (`Edgeway::DB::SQLiteAdapter`, through Spinel's FFI)
 with `db/migrations/*.sql` applied in file name order, so requests really write and read rows.
+Each database under `databases:` (in any environment) gets its own, with `db/NAME/migrations`; `db(:analytics)` answers it, and `db` the primary.
 
 ### SQLite
 

data/js/cloudflare-d1-sessions.js

@@ -0,0 +1,68 @@
+// X-D1-Bookmark is "BINDING=bookmark, ..."; clients resend it whole.
+import { addVary } from "./headers.js";
+
+export const BOOKMARK_HEADER = "X-D1-Bookmark";
+
+const isRead = (request) => request?.method === "GET" || request?.method === "HEAD";
+
+// A bookmark is opaque and D1's: one that does not look like D1's is dropped,
+// as D1 itself would keep a high-sorting garbage value as the latest bookmark.
+const BINDING_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const BOOKMARK = /^[0-9a-f-]{1,128}$/;
+
+export function parseBookmarks(value) {
+  const bookmarks = {};
+  for (const pair of (value ?? "").split(",")) {
+    const separator = pair.indexOf("=");
+    const name = pair.slice(0, separator).trim();
+    const bookmark = pair.slice(separator + 1).trim();
+    if (separator > 0 && BINDING_NAME.test(name) && BOOKMARK.test(bookmark)) bookmarks[name] = bookmark;
+  }
+  return bookmarks;
+}
+
+export class D1Sessions {
+  constructor(env, request, names = []) {
+    this.env = env;
+    this.names = new Set(names);
+    this.readRequest = isRead(request);
+    this.bookmarks = parseBookmarks(request?.headers.get(BOOKMARK_HEADER));
+    this.sessions = new Map();
+  }
+
+  uses(name) {
+    return this.names.has(name);
+  }
+
+  database(name) {
+    const binding = this.env[name];
+    if (!binding || !this.names.has(name)) return binding;
+    if (!this.sessions.has(name)) this.sessions.set(name, this.start(binding, name));
+    return this.sessions.get(name);
+  }
+
+  start(binding, name) {
+    return binding.withSession(this.startPoint(name));
+  }
+
+  startPoint(name) {
+    if (!this.readRequest) return "first-primary";
+    return this.bookmarks[name] ?? "first-unconstrained";
+  }
+
+  header() {
+    const pairs = [];
+    for (const name of this.names) {
+      const bookmark = this.sessions.get(name)?.getBookmark() ?? this.bookmarks[name];
+      if (bookmark) pairs.push(`${name}=${bookmark}`);
+    }
+    return pairs.join(", ");
+  }
+
+  annotate(response) {
+    const value = this.header();
+    if (value) response.headers.set(BOOKMARK_HEADER, value);
+    if (this.names.size > 0) addVary(response.headers, BOOKMARK_HEADER);
+    return response;
+  }
+}