Skip to content

Open-source status page, incident response and uptime monitoring

5.1 KB
Raw Blame

@openstatus/tinybird

Tinybird holds the monitoring time-series: every check result the probing tier produces lands here. Turso (see packages/db) holds application data. The two are linked by id only — no join across the boundary.

This package is two things:

  • Datafiles (datasources/, materializations/, endpoints/) — the schema and queries, deployed with the tb CLI.
  • A typed client (src/client.ts) — zod-validated wrappers over the published endpoints, consumed by the apps.

Now on Tinybird Forward

This project has migrated from Tinybird Classic to Tinybird Forward. If you last touched it under Classic, these are the changes that matter:

Classic Forward
pip install tinybird-cli pip install tinybird (or uv tool install tinybird) — currently 4.6.14
tb push / tb pull tb deploy — no push command exists anymore
Resources updated in place Deployments: build a staging one, then promote
New VERSION + backfill pipes per schema change Change the schema in place; add FORWARD_QUERY when existing rows need transforming
Datafiles anywhere datasources/, materializations/, endpoints/

The old _migration/ folder and its VERSION-bumping recipe are gone. Nothing in this repo uses tb push.

tb migrate-to-forward exists in the CLI for workspaces still on Classic. This one is already migrated — you do not need it.

Deploying to Tinybird Cloud

From this directory, after tb login:

tb --cloud deploy --check           # validate; changes nothing
tb --cloud deployment create --wait # build staging, run any backfills
tb --cloud deployment promote       # go live

tb --cloud deploy collapses the last two into one step. Prefer the split form when the diff touches a materialized view: create is where data gets copied, and you get to see it land before promoting. tb --cloud deployment discard throws a staging deployment away.

Changing a schema

Materialized views are the sharp edge. A .pipe under materializations/ and its target .datasource must agree on both column names and order, so a column added to a source datasource has to be added in three places:

  1. the source .datasource,
  2. the target mv__*.datasource schema,
  3. the SELECT in the aggregate__*.pipe that feeds it.

Never write SELECT * in a materialization. It silently breaks the next time a column is added to the source — the pipe starts producing a column the target has no slot for, and the deploy fails.

When the target datasource already exists in the cloud, deployment create repopulates it by re-running the materialized pipe over the source, so historical rows get real values rather than nulls. Check the "Data that will be copied with this deployment" table in --check output to confirm. That repopulation is not free — it re-materializes the full retention window.

Adding a nullable column, or a non-nullable one whose ClickHouse default is acceptable for old rows, needs nothing extra. Use FORWARD_QUERY when existing rows need a real transformation — a genuine default, a type change, a rename:

FORWARD_QUERY >
    SELECT *, 'unknown' AS source

It is a SELECT list only, no FROM/WHERE, and it applies to existing data until the next deploy compacts it. Remove it once the change is live.

Self-hosting

Tinybird is optional. Openstatus runs without it; you lose the charts and the time-series views. Set TINYBIRD_NOOP=true and every pipe and ingest call resolves to empty instead of hitting the network.

To run it for real, you have two options.

Tinybird Local

docker compose up starts a tinybird-local container (port 7181) alongside the rest of the stack. It comes up empty — the datafiles still need deploying:

cd packages/tinybird
tb --local deploy

Then point the apps at it:

TINYBIRD_URL=http://localhost:7181
TINY_BIRD_API_KEY=<token>          # tb --local token ls, then tb --local token copy <id>

Tinybird Cloud

Create a workspace, deploy the datafiles with the commands above, and set TINY_BIRD_API_KEY to a token with read access to the endpoints. TINYBIRD_URL can stay empty — it defaults to https://api.tinybird.co.

Gotcha: do not add a tinybird.config.json here

There was one; it has been removed on purpose. The CLI classifies a project by scanning the paths named in that config's folder/include for source-file extensions. With "folder": "." the scan covers this whole package, finds the .ts files in src/ and scripts/, decides it is a TypeScript-SDK project, and then fails on every command — including tb --help:

Error: Failed to generate Tinybird resources from TypeScript definitions.
Unable to load Tinybird SDK generator bridge. Cannot find package '@tinybirdco/sdk'

include only adds scan targets, so there is no way to narrow it. Without the config, the CLI falls back to detecting datasources/ and friends and treats this as a plain datafiles project, which is what we want.

If you ever do need a config here — for dev_mode, say — move the datafile folders into a subdirectory with no .ts beside them and point folder at that.