Navigate

Run Realtime Database locally

Realtime Database support is incomplete. Check its generated conformance page for the exact public API coverage before depending on a feature.

Realtime Database is one JSON tree that many clients watch at once. In Pyric it runs locally, rules enforced, with the modular calls you already know.

Store and read

Under pyric sandbox, your firebase/database imports resolve to the sandbox:

import { getDatabase, ref, set, get, onValue } from 'firebase/database';

const db = getDatabase();

await set(ref(db, 'status/alice'), { state: 'online', changedAt: Date.now() });

const snap = await get(ref(db, 'status/alice'));
console.log(snap.val()); // { state: 'online', changedAt: ... }

onValue(ref(db, 'status'), (snap) => {
  renderPresence(snap.val());
});

push appends with chronologically sortable IDs, update patches, and remove deletes. This path runs the same under pyric sandbox and the Vite plugin. Both swap firebase/database for the sandbox and run your onValueCreated functions against it. In Node, import the same functions from pyric/database and give getDatabase a sandbox:

import { initializeSandbox } from 'pyric/sandbox';
import { getDatabase, ref, set } from 'pyric/database';

const sandbox = initializeSandbox();
const db = getDatabase(sandbox.withAuth({ uid: 'alice' }));

Model the tree around your reads

Every RTDB path is an endpoint, and reading a path downloads everything below it. So structure follows the reads, not the entities. The defaults that hold up:

  • Flat, top-level collections. /users, /posts, /postSummaries. Never nest one entity type inside another, or one read drags the whole subtree.
  • Index tables for reverse lookups. /userGroups/$uid/$groupId: true answers “which groups is this user in” with one cheap read, and lets membership gate access in rules.
  • Summary nodes sized for list screens. The list reads /postSummaries, the detail screen fetches one /posts/$id.
  • Push IDs for anything append-only. Sequential numeric keys collide under concurrent writers; push IDs never do.

Duplicated data stays consistent through fan-out: one update at the root with full paths as keys commits atomically.

import { update } from 'firebase/database';

await update(ref(db), {
  'posts/p1/title': 'New title',
  'postSummaries/p1/title': 'New title',
});

Either both paths change or neither does. Queries take one orderBy, so multi-field filters want a precomputed composite key ("lang_level": "en_5") rather than a clever query.

Run your onValueCreated functions locally

Both pyric sandbox and the Vite plugin read the functions block in firebase.json and run your onValueCreated triggers in an isolated Node process against the same sandbox your app writes to. The same process serves your HTTP onRequest functions, v1 and v2, as Call your HTTP functions describes. No option is required. The block is enough. Other trigger kinds such as callable, scheduled, and Firestore log a warning and are skipped for now.

The plugin’s functions option tunes or disables this:

// vite.config.ts
import { pyric } from '@pyric/cli/vite';

export default {
  plugins: [
    pyric({
      functions: { region: 'europe-west1', instance: 'my-app-default-rtdb' },
      // or `functions: false` to keep the block and never run triggers locally
    }),
  ],
};

Each field wins over its environment variable, which wins over firebase files, which win over the default. region beats PYRIC_FUNCTIONS_RTDB_REGION (default us-central1). instance replaces the derived <projectId>-default-rtdb name. The project id is the one the server resolved, as Vite development setup describes, else demo-project.

Call your HTTP functions

An onRequest function answers at the emulator path on the server’s own origin: /<projectId>/<region>/<name>, such as http://localhost:3473/my-app/us-central1/api. The server prints one URL per function when it starts. The function sees / plus whatever follows its name. A POST to a name your source does not export gets a 404 that lists the functions that exist.

A hosting.rewrites entry whose destination is a function sends matching paths to it, as Firebase Hosting does:

  • The function sees the full original path and query, such as /api/messages.
  • A static file at the same path wins over the rewrite.
  • Only the __session cookie reaches the function.
  • A rewritten request that runs past 60 seconds gets a 504, whatever the function’s timeoutSeconds. The emulator path keeps the function’s own timeout.

Each request prints one line with the function, the path, the status, and how long it took.

A function that sets invoker: 'private' runs without authentication, where production refuses an unauthenticated call with 403. Pyric warns once when it starts. It answers your app’s own pages and callers that send no Origin, such as curl or server code, and refuses a call from any other site’s page with 403.

Under pyric sandbox, functions start once a browser tab connects to the sandbox. With --hosted they start with no tab open, as a deployed function does.

Under the plugin, saving a file in the functions source directory restarts the process, like a redeploy: ↻ [pyric] functions reloaded. In-flight executions in the old process can drop. Writes that land during the swap are treated as existing data by the new process and do not fire. A save that fails to load takes functions down until the next good save. Unlike rules, there is no last-good process to keep serving. functions: { watch: false } turns the reload off, matching pyric sandbox, where editing a function needs a server restart.

Running functions also mounts the agent bridge the process uses to reach the sandbox. That changes nothing about how your app runs: the page stays on the multi-tab SharedWorker path, and the bridge relays through it.

Inspect and simulate locally

Pyric keeps RTDB inspection and rules checks inside the sandbox. Studio and the CLI can crawl the current sandbox snapshot, while rtdbRules(...).simulate() evaluates reads and writes without contacting a production database. Production access happens only when the canonical Firebase package is selected outside the sandbox swap.

And from an agent

Ask an MCP-connected agent to inventory the reads your application performs, then inspect the local tree with rtdb_crawl_structure. Work with an agent gives a complete RTDB task prompt, and Set up your agent explains the browser bridge.

When firebase.json declares more than one database instance, pass --instance to pyric database, or instance to the MCP database tool, with the instance name or its URL. Without it, a call reads and writes the default instance. <projectId> and https://<projectId>.firebaseio.com, the default instance of a project created before about 2020, also select the default instance.

pyric database get --instance shard-00 --path rooms/lobby
pyric database set --instance https://shard-00.firebaseio.com --path rooms/lobby --value '{"name":"Lobby"}'

An instance that firebase.json does not declare, and that holds no data yet, is refused with the list of instances the project has.

Where to go next

When the paths are settled, write the rules that hold them in TypeScript: RTDB rules in TypeScript.