Skip to content

Inspecting and migrating stored actors

Three commands read and upgrade the actors that an akterd host stores:

  • akter actors directory lists stored actors by key prefix.
  • akter studio serves a live inspector and a read-only SQL endpoint for one actor or view.
  • akter migrate --sweep upgrades every sleeping actor to the newest schema version.

Each command calls the host control API of the host that --url names. Without --url, each command calls http://127.0.0.1:<PORT>, the address of the akter dev host. PORT defaults to 4000.

The commands need a host that serves the control operations⁠

The commands call five host control operations: actors, inspect, sql, sweep, and sweep-status. The akterd that akter dev starts does not serve them yet. The in-memory host does not serve them yet either.

A host that does not serve an operation answers HTTP 404 with no body. The command then exits with code 1 and names the missing operation:

Text
akterd at http://127.0.0.1:4000 answered HTTP 404 with no body, so this host does not serve the actors operation.

The Actor Directory records every stored actor⁠

A host that serves the actors operation keeps one directory entry for each actor that it stores. An entry holds the actor’s address, its parent, its stored state tag, its schema version, and whether it sleeps.

The schema version is the build generation that last migrated the actor’s tables and state. Build vN is generation N. A sleeping actor has no turn in flight, and no worker or cache holds it.

The directory sorts keys by their UTF-8 bytes. A key prefix therefore selects one contiguous range of keys. When child keys start with their parent’s key, such as ws_acme:ord_1, one prefix scan lists every child of that parent.

List stored actors by key prefix⁠

  1. Set HOST_URL to the URL of a host that serves the control operations.

  2. List the Order actors whose keys start with ws_acme:

    Terminal
    bunx akter actors directory --url "$HOST_URL" --actor Order --prefix ws_acme
  3. To read the next page, pass the key that the last line names:

    Terminal
    bunx akter actors directory --url "$HOST_URL" --actor Order --prefix ws_acme --after ws_acme:ord_10

The first command prints a table like this one:

Text
KEY             STATE  VERSION  PARENT             SLEEPING
ws_acme:ord_1   Open   v3       Workspace/ws_acme  yes
ws_acme:ord_10  -      v3       Workspace/ws_acme  no

More keys match. For the next page, pass --after ws_acme:ord_10

Directory flags and output⁠

FlagDefaultDescription
--actorRequiredThe actor’s name in the app, such as Order.
--prefixEvery keyLists only keys that start with this text.
--limit50Lists at most this many entries, from 1 to 1000.
--afterNoneStarts after this key.
--jsonOffPrints each entry as one JSON line. The key for the next page goes to stderr as next: <key>.
--urlhttp://127.0.0.1:<PORT>The URL of the akterd host.

A - in the STATE column means that the actor has no stored state yet, because it has not run initial.

The table strips control characters from keys, state tags, and parent addresses. The --after hint shell-quotes the next key when the key holds characters that a shell treats as special.

Inspect one actor with akter studio⁠

  1. Start the inspector for the Order actor with the key ord_8821:

    Terminal
    bunx akter studio --url "$HOST_URL" --actor Order --key ord_8821
  2. Open the inspector URL that the command prints in a browser:

    Text
    akter studio: inspector http://127.0.0.1:53817/
    akter studio: read-only SQL for Drizzle Studio and TablePlus libsql://127.0.0.1:53817?tls=0
  3. To stop the inspector, press Ctrl+C.

To inspect an Akter.view, pass --view in place of --actor, such as --view Revenue --key eu. akter studio sends the view’s name as the actor of each inspect and sql call.

What the inspector shows⁠

The inspector page reloads its panel every second. For an actor, the panel shows these facts:

  • The state machine as a table of states and transitions, plus its Mermaid stateDiagram-v2 source.
  • The current state, marked in the table and in the diagram.
  • The stored state value as JSON.
  • Each armed timeout, with its timer, its command, its due time, and the time left.
  • The row count of each table that the actor declares.
  • The supervision tree, from the actor’s parent down to its children.
  • The libsql:// URL of the read-only SQL endpoint.

For a view, the page shows the view’s tables only, because a view has no state machine.

Studio flags⁠

FlagDefaultDescription
--actorNoneThe actor to inspect. Pass --actor or --view, but not both.
--viewNoneThe view to inspect. The page then shows its tables only.
--keyRequiredThe key of the actor or view.
--entrysrc/app.layer.tsThe module that exports app. akter studio reads the actor’s state machine from it.
--urlhttp://127.0.0.1:<PORT>The URL of the akterd host.

akter studio checks that the host stores the actor before it listens. An unknown actor name exits with code 2 and lists the app’s actors.

Query actor tables from a libSQL client⁠

  1. Copy the libsql:// URL that akter studio prints.
  2. In Drizzle Studio or TablePlus, add a libSQL connection with that URL and no auth token.
  3. Run SELECT statements against the actor’s tables.

The host enforces read-only SQL⁠

The endpoint speaks the Hrana v2 pipeline protocol over HTTP at /v2/pipeline. It forwards each statement to the host. The host runs the statement on a read-only connection and refuses any statement that writes.

  • akter studio also refuses a statement whose first word is a write keyword, such as INSERT or DROP. This filter saves a call to the host. The host is what enforces read-only access.
  • A refused write fails with Hrana error code SQLITE_READONLY. This holds for writes that akter studio refuses and for writes that the host refuses.
  • The host refuses reads of its own akter_* tables. Their names still appear in sqlite_schema.
  • BEGIN, COMMIT, and ROLLBACK succeed as empty results, so clients that wrap reads in a transaction still work.
  • Stored statements (sql_id) and named arguments fail. Use positional ? arguments.
  • sequence requests fail, so executeMultiple in @libsql/client does not work. Send each statement on its own, or send the statements as a batch.
  • A request that breaks the Hrana schema fails the whole pipeline with HTTP 400 and the decode error.
  • The server listens on 127.0.0.1 only. It answers HTTP 403 to a request whose Host header is not a loopback name.
  • It also answers HTTP 403 to a request whose Origin header is not the server’s own origin.

Akter Cloud proves migrations on forks of sampled actors⁠

A new build can change an actor’s tables or its states. akter-migration-prover in Akter Cloud proves that the change upgrades real stored actors.

The prover samples sleeping actors at each older schema version, from v1 to vN-1. It forks the database of each sampled actor copy-on-write. On each fork, it runs the new table migration and Akter.migrateState. It then checks PRAGMA integrity_check and checks that the upgraded state is a state of vN. A failure stops the proof with a named reason.

The prover enforces a budget of 2 ms for each fork and 100 ms for the whole proof. Its test with 5,000 actors meets both budgets. The deploy pipeline does not run the prover yet, so a rollout does not wait for a proof.

Upgrade every stored actor with a sweep⁠

An actor that never runs a turn under the new build keeps its old schema version. A sweep upgrades those sleeping actors in the background, at a pace that you set.

  1. Start the sweep with 64 actors at a time and a budget of 2000 page writes per second:

    Terminal
    bunx akter migrate --url "$HOST_URL" --sweep --concurrency 64 --iops 2000
  2. Read the progress line that the command prints every second:

    Text
    akter migrate: 2500 upgraded to schema v6, 0 failed, 0 parked, 2500 remaining, 64 at a time
    akter migrate: the sweep is done. 5000 upgraded to schema v6, 0 failed, 0 parked.
  3. If the command lists parked actors, failed actors, or actors that remain, fix each named actor. Then run the same command again.

When the sweep ends, the command lists each parked actor with its reason. It then lists failed actors with their reasons. The host keeps the last 32 failure reasons, sorted by actor and then by key. So the list can hold fewer actors than the failed count. The command strips control characters from every reason that it prints.

A sweep that is already running continues when you start it again. The command then follows that sweep’s progress.

The command stops after 60 polls in a row in which the upgraded, failed, and remaining counts all stay the same. It then exits with code 1 and reason SweepStalled.

Sweep flags and exit codes⁠

FlagDefaultDescription
--sweepRequiredUpgrades stored actors as a sweep. Without it, the command exits with code 2.
--concurrencyRequiredUpgrades this many actors at once, from 1 to 1024.
--iops2000 on the hostThe page writes per second that the whole sweep may spend.
--urlhttp://127.0.0.1:<PORT>The URL of the akterd host.
CodeMeaning
0The sweep upgraded every sleeping actor.
1Actors failed, were parked, or remain below the target version (SweepIncomplete).
1The counts stayed the same for 60 polls in a row (SweepStalled).
1The host does not serve the operation (HostUnserved), or it refused the request with HTTP 404.
2A flag is missing or out of range.
5The host did not answer, or it answered with HTTP 5xx.