Console
Try queries and fix records by hand in a console with your Models loaded.
Opening the console
Run the console from your project’s folder. It opens your local database, or your remote one with --remote:
npx active-record console
On Postgres, it opens the url your active-record.jsonc declares, or with --remote its remoteUrl. The rest of this page shows D1.
It prints which database and Models it opened, then waits for a line:
Local database DB (.wrangler/state)
Models: Post, User
local> const user = await User.find("c5c765b4-b7e1-428e-aa00-88d58f622c71")
#=> undefined
local> user
#=> User { id: 'c5c765b4-b7e1-428e-aa00-88d58f622c71', name: 'Alice', email: [FILTERED] }
local> await user.update({ name: "Johnny" })
#=> true
local> const admins = await User.where({ role: "admin" }).toArray()
#=> undefined
Leave with quit, exit, or Ctrl-D. Ctrl-C stops a line that’s still running. .help lists the console’s own commands, and npx active-record c is the short form.
What you can use
- Your Models, by class name, from every file in
src/models. They query your database, local unless you pass--remote, with nodbto pass. db, your connected database, fordb.batch(...)anddb.model(...).- Top-level
await, andconstandlet, which last until you leave.
A record prints as it does in a log: its class and attributes, with a filtered attribute as [FILTERED] and an unsaved change next to the value it had. Printing records has the details.
An error prints and the console carries on.
Reloading your Models
After you edit a Model, or a file it imports, read them again without leaving:
> reload!
Reloaded: Post, User
.reload does the same. A Model you added appears, and one whose file you removed goes. Records and values you already hold keep their old class, so run the lines that made them again.
If a file fails to load, say a syntax error in the middle of an edit, the console names the file and keeps the Models you had.
Seeing the SQL
Start with --verbose to see each statement a line runs, or turn it on and off while you work with .verbose:
> .verbose
SQL logging on
> await User.find(1)
User 1.2ms SELECT * FROM "users" WHERE (("id" = ?)) LIMIT ? [ 1, 1 ]
#=> User { id: 1, name: 'Alice', email: [FILTERED] }
Each line shows the Model, the time, the SQL, and the values it bound. Filtered attributes show as [FILTERED], as they do in onQuery. A statement that fails prints failed and the reason in place of the time. verbose! toggles it too, and .verbose on and .verbose off set it explicitly.
Choosing what to open
| Option | |
|---|---|
--database <name> |
The database to open, when active-record.jsonc names several. |
--models <path> |
Where your Models are: a folder (src/models by default) or one file (src/models.ts). |
--config <file> |
Use this config file, in place of active-record.jsonc. |
--no-history |
Don’t keep what you type in the history file. |
--verbose |
Print each statement a line runs, to begin with. .verbose turns it on and off. |
-e, --eval <code> |
Run this code, print its result, and exit. See Running one piece of code. |
--remote |
Open your remote database instead, after you type its name. See below. |
--yes |
With --remote, don’t ask first. It’s also how to open it without a terminal. |
--history |
Keep what you type in a remote session, which isn’t kept unless you ask. |
Where your data lives
The console opens the local database in .wrangler/state, beside your Wrangler config. It’s the same one wrangler dev and wrangler d1 migrations apply --local use, so apply your migrations first, and what you change in the console is what your dev server sees. With wranglerConfig, it’s beside the config that setting names.
It opens your remote database only when you ask with --remote, and never for a binding your config marks remote: true by itself.
It starts only that D1 binding. The rest of your Wrangler config (Durable Objects, services, vars, and the secrets in .dev.vars) isn’t started, so it can’t warn or fail on them, and your Models can’t reach them either.
On a terminal, what you type is kept in .wrangler/active-record-history, which Wrangler projects already ignore. A line can hold a token or an email, so add --no-history when you’d rather it wasn’t kept.
Opening your remote database
--remote opens the real database your binding points at, to look at production data or fix one record by hand:
npx active-record console --remote
It names the database and waits for you to type its name. Anything else, including y, cancels and opens nothing. Anything you type or paste after the name is dropped, so a pasted block can’t run on the real database before you’ve seen the prompt:
Remote database DB (shop, id 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d)
What you change in the console is changed in this database, not a copy.
Type its name to continue, anything else cancels: shop
Once it’s open, the prompt says remote> (in red on a terminal) where a local session says local>, so the two can’t be mistaken for each other:
Remote database DB (shop, id 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d)
Models: Post, User
remote> await User.count()
#=> 42
The console signs in with your Wrangler login, or with CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID in the environment, and takes the account from account_id in your Wrangler config when it names one. When Cloudflare refuses, the console prints its reason and how to sign in.
There’s no one to type the name unless both your input and output are a terminal, so a piped session refuses unless you add --yes, which is how a script opens it:
echo 'await User.count()' | npx active-record console --remote --yes
What you type isn’t kept unless you add --history, and then it goes in .wrangler/active-record-history-remote, a file of its own, so the up arrow never offers a local session a line you typed against the real database.
Running one piece of code
-e runs one piece of code with your Models and db in scope, prints its result, and exits, which is how to use the console from a script:
npx active-record console -e 'await User.count()'
42
- The result is on stdout. A string prints as it is, without quotes, so
$(…)captures it, and anything else prints as the console prints it, without#=>.undefinedprints nothing. What your code logs withconsole.logcomes first, andconsole.errorgoes to stderr, as innode -e. - Everything else is on stderr: which database and Models it opened, the SQL with
--verbose, and a refusal to start. - A failure exits 1. Its stack goes to stderr, no result goes to stdout, and no statement after it runs. Success exits 0.
- Join statements with
;. The last value is the result:-e 'await User.create({ name: "Dan" }); await User.count()'. - It keeps no history, ignores what is piped to it, and has no time limit: stop it with Ctrl-C, or run it under
timeout.
Running a few lines at once
Lines you paste or pipe run in order, each after the one before, and the console finishes them before it exits:
echo 'await User.count()' | npx active-record console
That prints the same transcript a session does (the database, a prompt before each line, #=> before each result) and exits 0 even when a line fails. For a script that checks the result or the exit code, use -e.