# DataRunner

> Scheduled SQL reporting, as a web console
> (SaaS). You connect a database and describe what you want in plain language;
> an AI model (included in every plan, or your own Claude, GPT or Gemini key)
> reads the schema and proposes the query, the cron expression and the timezone, which
> you review before anything is created. DataRunner then runs the SQL, formats
> the result and delivers it by email, chat or webhook. It also
> watches the health of every connected database, opens incidents when one goes
> down, and carries dashboards, alert routes and recipient lists in the
> same console.

Site: https://www.datarunner.app/
Console: https://console.datarunner.app
Languages: English (/en), Brazilian Portuguese (/pt)
Contact: projeto@datarunner.app (support, sales, security and privacy)
Full documentation as one text file: https://www.datarunner.app/llms-full.txt

## What it actually does

- **AI assistant.** Included in every plan as a monthly request quota (30 on Solo, 300 on Pro, 1,500 on Team, 5,000 on Business, with a per-person daily limit). A workspace can instead connect its own Anthropic (Claude), OpenAI (GPT) or Google (Gemini) key; usage is then billed by the provider and the plan quota no longer applies. Every request is recorded in the workspace's assistant history. The model receives the request and the schema of the chosen connection — table names, column names, types and the column descriptions written on the connection — never rows of data. It returns SQL; with the per-workspace `ai_autoconfigure` flag on, it also returns a cron expression, the timezone for that schedule and a report name. Operational requests come back as a monitor and an alert route. Everything arrives as a proposal that a human approves item by item, and every proposed action is checked against the caller's workspace permissions before it applies. The assistant is optional; everything else works without it.
- **Connections.** 20 database kinds, all of which execute queries: PostgreSQL, MySQL, SQL Server, SQLite, MariaDB, Redshift, CockroachDB, TimescaleDB, Greenplum, Oracle, ClickHouse, BigQuery, DuckDB, MotherDuck, Trino, Presto, Firebird, Snowflake, Databricks and Amazon Athena (Snowflake, Databricks and Amazon Athena marked beta).
- **Queries.** SQL workbench with syntax highlighting, autocomplete, `{{...}}` parameters bound as real driver parameters, per-save versioning, and a cost estimate for engines that bill by data scanned.
- **Schedules.** Cron expressions with a timezone per schedule, not per workspace. Run history records duration, row count and errors.
- **Reports and delivery.** Output as CSV, Excel (XLSX), PDF or inline HTML. 7 delivery channels: Email, WhatsApp (beta), Telegram, Generic webhook, Slack, Discord and Google Sheets. Delivery rules can skip an empty result or escalate past a row threshold.
- **Database monitor.** Availability, latency and connection metrics for every connected database. Incidents open and close themselves and show which schedules depend on the database; alert routes decide which channel the warning lands on. A bridge agent reaches databases on private networks, outbound only, limited to the addresses allowed on that machine.
- **Dashboards.** Grids of widgets, each fed by a saved query and drawn as one of thirteen shapes: table, number, line, area, bar, pie, scatter, histogram, gauge, heatmap, combo, treemap or funnel. Public links with optional password and expiry, and an embeddable iframe. Column masking applies on the dashboard exactly as it does in the editor.
- **Recipients.** Contacts with an e-mail, WhatsApp or Telegram channel, segmented lists that are re-evaluated on every send, and scoped unsubscribes. A report goes to a loose address, a contact or a list.
- **Governance.** Roles with per-resource permissions, passkeys and two-factor auth, audit logs, column masking policies, scoped API keys, data export and account deletion from the console.

## Pricing

- Solo — R$0/month or $0/month.
  1 user · 1 connection; 3 schedules · 500 queries/month; 500 e-mails/month · 5,000 rows per query; 1 database monitor; Checks every 5 min; 100 contacts · 2 dashboards; 14 days of history; 30 included AI requests/month · 100 e-mails without your own provider.
- Pro — R$79/month or $19/month, or R$790/year (2 months free).
  3 users · 5 connections; 20 schedules · 3,000 queries/month; 5,000 e-mails/month · 50,000 rows per query; 5 database monitors; Checks every 2 min; 1,000 contacts · 10 dashboards; 90 days of history; 300 included AI requests/month · 1,000 e-mails without your own provider.
- Team — R$197/month or $49/month, or R$1,970/year (2 months free).
  10 users · 25 connections; 100 schedules · 50,000 queries/month; 50,000 e-mails/month · 1,000,000 rows per query; 50 database monitors; Checks every 60 s; 10,000 contacts · 25 dashboards; 1 year of history; 1,500 included AI requests/month · 5,000 e-mails without your own provider. Everything in Pro, plus API keys and alert routes.
- Business — priced on request.
  50 users · 100 connections; 500 schedules · 500,000 queries/month; 500,000 e-mails/month · 10,000,000 rows per query; 500 database monitors; Checks every 15 s; 100,000 contacts · 200 dashboards; 3 years of history; 5,000 included AI requests/month · 20,000 e-mails without your own provider. Everything in Team, plus audit logs and priority support.

Billed through Stripe in Brazilian reais (BRL), or in US dollars outside Brazil — the checkout picks the currency by country. Monthly, or yearly in one payment with two months free. Business is quoted per company and invoiced. Every plan includes every connector; the plan sets volume, not features. No credit card is needed for Solo, and it does not expire.

## Apps

- Web console — the complete product, in a browser.
- Agent — Windows and Linux, x86-64 and ARM64, Native AOT, push-only. It holds no database credentials and accepts no remote command.
- CLI — scripts the same API from a terminal or a CI job.

## What DataRunner is not

- Not a BI platform. Dashboards exist, but there is no drag-and-drop chart builder: every widget is fed by a SQL query, written by you or by the assistant.
- Not an ETL platform. Nothing transforms data between warehouses, and there is no dimensional modelling.
- Not an AI product with a model of its own. The assistant is optional and runs on a key you supply; no output is applied without a human approving it.

## Documentation

- [Getting started](https://www.datarunner.app/en/docs/getting-started): From signup to the first delivered report, in the order the screens appear.
- [Connections](https://www.datarunner.app/en/docs/connections): Which databases are supported, what each one can actually do, and how credentials are stored.
- [Queries](https://www.datarunner.app/en/docs/queries): The SQL workbench, parameters, versions, and what happens when a result is too large.
- [AI assistant](https://www.datarunner.app/en/docs/assistant): The AI included in the plan or your own model, asking in plain language, and what the product lets the answer touch.
- [Schedules](https://www.datarunner.app/en/docs/schedules): Cron, per-schedule timezones, run history, and what happens when a run fails.
- [Reports and delivery](https://www.datarunner.app/en/docs/reports): Output formats, recipients, and the rules that decide whether a send happens at all.
- [Channels](https://www.datarunner.app/en/docs/channels): The seven delivery destinations, what each one needs, and what each one can carry. Each has its own page with the setup, the fields and how to test.
- [Command line](https://www.datarunner.app/en/docs/cli): Install the DataRunner command line, authenticate, and turn a query into a build step.
- [Database monitor](https://www.datarunner.app/en/docs/monitors): The health of every connected database: what is checked, the metrics that come with it, and how an incident starts.
- [Bridge to a private network](https://www.datarunner.app/en/docs/bridge): How to query a database only your network can reach, without opening a firewall port.
- [Alerts and routes](https://www.datarunner.app/en/docs/alerting): Where the notice of a database going down, or of a rule that fired, goes.
- [Security and data](https://www.datarunner.app/en/docs/security): Encryption, roles, authentication, audit, and what you can export or delete.
- [Dashboards and sharing](https://www.datarunner.app/en/docs/dashboards): Panels built from queries, per-dashboard filters, public links with password and expiry, and the iframe.
- [Recipients](https://www.datarunner.app/en/docs/contacts): Who receives a report: contacts, lists with segments, and unsubscribes.
- [API, keys and outbound webhooks](https://www.datarunner.app/en/docs/api): The browsable reference, how to authenticate with a key, and the events the product pushes to your endpoint.
- [Plans, billing and account](https://www.datarunner.app/en/docs/billing): Monthly or yearly, what happens when the card fails, extra workspaces, ownership and a confirmed e-mail.
- [Email](https://www.datarunner.app/en/docs/channel-email): Wiring up Email: what to create at the provider, what to paste here, what goes in Target, and how to test before depending on it.
- [WhatsApp](https://www.datarunner.app/en/docs/channel-whatsapp): Wiring up WhatsApp: what to create at the provider, what to paste here, what goes in Target, and how to test before depending on it.
- [Telegram](https://www.datarunner.app/en/docs/channel-telegram): Wiring up Telegram: what to create at the provider, what to paste here, what goes in Target, and how to test before depending on it.
- [Generic webhook](https://www.datarunner.app/en/docs/channel-webhook): Wiring up Generic webhook: what to create at the provider, what to paste here, what goes in Target, and how to test before depending on it.
- [Slack](https://www.datarunner.app/en/docs/channel-slack): Wiring up Slack: what to create at the provider, what to paste here, what goes in Target, and how to test before depending on it.
- [Discord](https://www.datarunner.app/en/docs/channel-discord): Wiring up Discord: what to create at the provider, what to paste here, what goes in Target, and how to test before depending on it.
- [Google Sheets](https://www.datarunner.app/en/docs/channel-google_sheets): Wiring up Google Sheets: what to create at the provider, what to paste here, what goes in Target, and how to test before depending on it.

## Ready-made SQL queries

- [PostgreSQL health](https://www.datarunner.app/en/templates): [Dead tuples by table](https://www.datarunner.app/en/templates/postgres/dead-tuples), [Indexes never used](https://www.datarunner.app/en/templates/postgres/unused-indexes), [Transactions open for more than 5 minutes](https://www.datarunner.app/en/templates/postgres/open-transactions), [Sessions waiting on a lock](https://www.datarunner.app/en/templates/postgres/lock-waits), [Statements by total time](https://www.datarunner.app/en/templates/postgres/slowest-statements), [Largest tables](https://www.datarunner.app/en/templates/postgres/largest-tables), [Cache hit ratio](https://www.datarunner.app/en/templates/postgres/cache-hit), [Connections by state](https://www.datarunner.app/en/templates/postgres/connections-by-state), [Sequences past 80% of their range](https://www.datarunner.app/en/templates/postgres/sequences-near-limit), [Replication lag](https://www.datarunner.app/en/templates/postgres/replication-lag)
- [MySQL health](https://www.datarunner.app/en/templates): [Largest tables and their free space](https://www.datarunner.app/en/templates/mysql/table-sizes), [Tables without a primary key](https://www.datarunner.app/en/templates/mysql/tables-without-pk), [Queries running for more than 60 seconds](https://www.datarunner.app/en/templates/mysql/long-queries), [Statements by total time](https://www.datarunner.app/en/templates/mysql/slowest-statements), [Indexes never used](https://www.datarunner.app/en/templates/mysql/unused-indexes), [Connections by command](https://www.datarunner.app/en/templates/mysql/connections-by-command), [InnoDB buffer pool hit ratio](https://www.datarunner.app/en/templates/mysql/buffer-pool)
- [SQL Server health](https://www.datarunner.app/en/templates): [Blocked sessions](https://www.datarunner.app/en/templates/mssql/blocking), [Missing indexes the optimiser asked for](https://www.datarunner.app/en/templates/mssql/missing-indexes), [Indexes written to but never read](https://www.datarunner.app/en/templates/mssql/unused-indexes), [Queries by total CPU](https://www.datarunner.app/en/templates/mssql/top-cpu-queries), [Top waits since restart](https://www.datarunner.app/en/templates/mssql/wait-stats), [Largest tables](https://www.datarunner.app/en/templates/mssql/table-sizes), [Sessions by status](https://www.datarunner.app/en/templates/mssql/sessions-by-status)

## Pages

- [Home](https://www.datarunner.app/en): what DataRunner does, plans and FAQ
- [Download](https://www.datarunner.app/en/download): bridge agent and CLI
- [Changelog](https://www.datarunner.app/en/changelog): release notes
- [Blog](https://www.datarunner.app/en/blog): product notes
- [Coming from PopSQL](https://www.datarunner.app/en/popsql): PopSQL has been in limited support since 2025-09-02; its shutdown, announced for 2026-09-01, was postponed on 2026-08-11 with no new date, and PopSQL promises at least 90 days of notice. Importing its queries, and what maps to what
- [Redash alternative](https://www.datarunner.app/en/alternatives/redash): importing Redash queries with their parameters, what maps to what, and what does not come across
- [Metabase alternative](https://www.datarunner.app/en/alternatives/metabase): importing native SQL questions, what maps to what, and the gaps (no visual builder, no embedding)
- [Free Postgres health check](https://www.datarunner.app/en/tools/postgres-health): one read-only query, pasted result analyzed in the browser: unused indexes, dead rows, stuck transactions, sequences near their limit
- [About](https://www.datarunner.app/en/about): why the product exists
- [Contact](https://www.datarunner.app/en/contact): support, sales, privacy and security
- [Privacy policy](https://www.datarunner.app/en/privacy)
- [Terms of service](https://www.datarunner.app/en/terms)

Portuguese versions live under /pt with the same paths.

---

# Getting started

Source: https://www.datarunner.app/en/docs/getting-started

From signup to the first delivered report, in the order the screens appear.

## The idea in one sentence

You save a connection, write a query, and attach a schedule to it. On every trigger DataRunner runs the SQL, formats the result and delivers it through the channels you pointed at. The database monitor and the alerts exist so you find out when that path breaks.

## The whole path

1. Create an account at console.datarunner.app. The workspace is created with it and you own it.
2. Under Connections, add your database. Test the connection before saving: the test runs a trivial SELECT and tells you exactly what failed.
3. Under Queries, write the SQL and run it once. The result appears below, with the row count and duration.
4. Save the query and attach a schedule: cron expression, timezone and output format.
5. Point at least one delivery channel. With no channel the run still happens, but the result stays in the history.

> The free plan (Solo) allows one connection, three schedules and five hundred queries a month. That is enough to put a real report into production before deciding anything.

## Knowing it worked

Every trigger writes a line into the query history, with start time, duration, row count, and the error when there was one. Delivery writes its own receipt: the channel, the destination, and the answer it gave. If the email did not arrive, the receipt says whether it left here.

- Run history: what the database answered.
- Delivery receipts: what each channel answered.
- Failure alerts: who was told, and when.

---

# Connections

Source: https://www.datarunner.app/en/docs/connections

Which databases are supported, what each one can actually do, and how credentials are stored.

## Two levels of support

Not every connector does the same thing, and the difference changes what you can build on top of it. There are two levels, and the new-connection screen shows which one an engine is at.

| Level | What you can do |
| --- | --- |
| Query + schema | Reports, schedules, autocomplete and table browsing |
| Query | Reports and schedules; no autocomplete |

- PostgreSQL: query, query + schema
- MySQL: query, query + schema
- SQL Server: query, query + schema
- SQLite: query, query + schema
- MariaDB: query, query + schema
- Redshift: query, query + schema
- CockroachDB: query, query + schema
- TimescaleDB: query, query + schema
- Greenplum: query, query + schema
- Oracle: query
- ClickHouse: query
- BigQuery: query
- DuckDB: query
- MotherDuck: query
- Trino: query
- Presto: query
- Firebird: query
- Snowflake: query (beta)
- Databricks: query (beta)
- Amazon Athena: query (beta)

> Snowflake, Databricks and Amazon Athena are marked beta: the provider is written and compiles, but has never been exercised against a live instance. The first real run will be yours, and we would rather say so than find out alongside you.

## Credentials

- Credentials are encrypted with AES-GCM before they touch the database, and the key does not live in the same table.
- The connection to your database uses TLS when the server offers it; hostless engines such as BigQuery, Athena and Snowflake authenticate through their own SDK.
- A password is never returned by the API after it is saved. On edit the field is blank and is only rewritten if you type something.

## Plan limits

| Plan | Connections | Queries per month | Rows per query |
| --- | --- | --- | --- |
| Solo | 1 | 500 | 5,000 |
| Pro | 5 | 3,000 | 50,000 |
| Team | 25 | 50,000 | 1,000,000 |
| Business | 100 | 500,000 | 10,000,000 |

---

# Queries

Source: https://www.datarunner.app/en/docs/queries

The SQL workbench, parameters, versions, and what happens when a result is too large.

## The workbench

The workbench is a SQL editor with syntax highlighting and autocomplete fed by the connection schema, on the engines that expose one. Running it once shows the result, the duration and the row count, and it is what you should do before scheduling anything.

## Parameters

A parameter is written in double braces and becomes a real driver parameter, not string concatenation. That is what stops a value containing a quote from becoming SQL injection.

revenue_by_region.sql:

```
SELECT region,
       sum(total) AS revenue
  FROM orders
 WHERE day >= {{start}}
   AND day <  {{end}}
 GROUP BY 1
 ORDER BY 2 DESC
```

The schedule sets each parameter value. Values relative to the run date are resolved in that schedule’s timezone, not the server’s.

## Versions

Every save keeps the previous version with its author and date. You can compare two versions and restore one. It is the answer to the question that always follows a strange number in a report: what did this query do last month.

## When the result is large

- The row ceiling per query comes from the plan. On hitting it the run stops and the report is marked truncated, rather than delivering half a set without saying so.
- There is a time limit per run; a query that exceeds it is cancelled at the database, not abandoned.
- For engines that bill by data scanned, the workbench shows a cost estimate before you run.

---

# AI assistant

Source: https://www.datarunner.app/en/docs/assistant

The AI included in the plan or your own model, asking in plain language, and what the product lets the answer touch.

## Included AI or your own key

Every plan comes with AI requests each month: 30 on Solo, 300 on Pro, 1,500 on Team and 5,000 on Business. Each person can make up to 20 requests a day, and in a workspace with more than one person nobody can use more than half of the month. The counter is under Settings → Billing.

If you prefer, connect your own Anthropic (Claude), OpenAI (GPT) or Google (Gemini) account under Settings → Integrations. Usage is then billed to you by them directly, and the plan quota stops applying. The key is encrypted at rest like any database credential.

- More than one provider can be connected; the card says which one is answering, because three "connected" badges would read as three independent facts, and the assistant calls exactly one.
- The model field takes a specific id. Left empty, the catalogue default applies. Swapping the id is how you follow a new model without waiting for a release of ours.
- The "Test" button makes a real call to the provider and shows what it said. A revoked key fails here rather than halfway through a request.
- If you do not use the assistant, the rest of the product works the same.

## What leaves here

Your request and the structure of the chosen connection: table names, column names, types, and any descriptions you wrote on the columns of the connection. Rows from your data are not sent. The call goes from our server to the provider (Anthropic for the included AI, or the one you connected). Each request and its reply are kept in the workspace's assistant history, with who asked and what was applied.

> The quality of the SQL rests almost entirely on that structure. PostgreSQL, MySQL, SQL Server and SQLite connections have introspection, so the model can see the schema; on the other engines it writes blind, and the query is worth reading line by line before you schedule it.

## Asking for a query

In the workbench, open Tools → AI and describe what you want to see. "Generate SQL" streams the query back as it is written, with an explanation and warnings when the output contains a destructive verb. "Replace editor SQL" moves the result into the editor, where it is yours to review, run and save like any other.

A request carrying everything the proposal needs:

```
Read the database: weekly revenue by region,
with the change against the week before.
Every Tuesday at 10am, São Paulo time.
```

The five things that sentence carries are the five that come back: the data, the cut, the comparison, the cadence and the timezone. It works the other way too: drop the Tuesday and no cron comes back, drop "São Paulo time" and no timezone does. The model does not invent a schedule nobody asked for, and when the timezone is missing the card says so: the workspace default applies, never UTC.

## Asking for the schedule too

With the flag on, the same request comes back with more than SQL: the cron expression, the timezone for that schedule, the model’s own plain-language reading of the cron, and a name for the report. None of it is applied; the screen shows a proposal and a button. Wrong SQL shows a wrong number on one screen and somebody notices; a wrong cron delivers to real recipients on a timetable nobody chose, and the first to find out is a recipient.

1. Settings → Feature flags → turn on "ai_autoconfigure". It starts off in every workspace on purpose: widening what a model’s output may touch is the tenant’s call, not ours.
2. In the workbench, write the request and use "Propose schedule too".
3. Check the cron against the plain-language reading beside it. That reading is what lets a human validate the expression without parsing cron.
4. "Apply and schedule" creates the schedule and, when none exists yet, the report that will deliver it. The notice says so rather than letting you find a report you never asked for.

## The things that are not SQL

Ctrl/⌘ I opens the assistant from any screen. There the request is about the workspace, and the answer is a plan of actions, each with the reason it is there and a checkbox that decides whether it happens. The catalogue is closed: the model cannot even describe an action the product does not know how to execute.

| Action | What for |
| --- | --- |
| Monitor | something reachable or not: a URL, a port, a certificate, a database, or a job that should have checked in |
| Alert route | where an alert goes once it fires: which channel, in what order, after what delay |
| Schedule | a query that starts running on its own |
| Open screen | when the request already has an answer on a screen that exists, and creating anything would be wrong |

> Every action carries the permission it requires, checked against your workspace role before it is applied. A viewer gets the plan and cannot apply it, because the same limit applies here as everywhere else.

## Where else it shows up

- Dashboards: describe the board and the model picks the widgets, the chart for each and which of your saved queries feeds them, and says so when none fits.
- Connection context: the model reads the schema and writes what that database is: the domain, the tables that matter, how they join. It is the only AI output in the product that can be saved without field-by-field approval, because the worst case is a bad paragraph somebody fixes. It stays editable: the model reads structure, not intent.

---

# Schedules

Source: https://www.datarunner.app/en/docs/schedules

Cron, per-schedule timezones, run history, and what happens when a run fails.

## The expression

A schedule is a five-field cron expression. The minimum interval depends on the plan: five minutes on Solo, two minutes on Pro, sixty seconds on Team, fifteen seconds on Business.

Examples:

```
0 8 * * 1-5      every weekday morning at 08:00
0 */15 * * *     every 15 minutes
30 23 L * *      23:30 on the last day of the month
```

## Timezone

The timezone belongs to the schedule, not the workspace. The workspace only supplies a default so the field arrives filled in; from there each schedule carries its own. That is what lets the same report go out at 08:00 in São Paulo and 08:00 in Lisbon without duplicating the query.

> UTC is never chosen silently. If a schedule is in UTC, it is because somebody picked UTC.

## History

Every trigger records start time, duration, rows returned and the error when there was one. History is kept for the plan’s retention: 14 days on Solo, 90 days on Pro, one year on Team, three years on Business.

## When it fails

- The run is marked failed with the message the database returned, unrewritten.
- The schedule stays active; one failure does not switch a report off.
- If a failure alert is configured, it fires through the workspace’s alert route.

---

# Reports and delivery

Source: https://www.datarunner.app/en/docs/reports

Output formats, recipients, and the rules that decide whether a send happens at all.

## Formats

| Format | When to use it |
| --- | --- |
| Inline HTML | A few rows that need reading on a phone, without opening an attachment |
| CSV | Input for another system, or a large volume |
| Excel (XLSX) | The recipient will filter, sum and paste it somewhere else |
| PDF | The document has to look the same for everyone who opens it |

## Recipients

A report destination is a loose address, a contact, or a broadcast list, and the contact or list is resolved again on every send, so whoever joins the list afterwards starts receiving it. Which channel carries a recipient follows from the kind of address they have; when the workspace holds more than one account of a kind (two WhatsApp Business numbers, say), the list picks which one it goes out on, and everything else falls back to the default account. Addresses that returned a hard bounce go onto the suppression list and stop being retried.

## Delivery rules

The rule decides whether the send happens, based on that run’s result. It is what separates a report from an alert, and what stops somebody’s inbox receiving thirty empty messages a week until it becomes a filter.

- Skip the send when the result comes back empty.
- Send only above a row count.
- Escalate to another channel past a threshold.

---

# Channels

Source: https://www.datarunner.app/en/docs/channels

The seven delivery destinations, what each one needs, and what each one can carry. Each has its own page with the setup, the fields and how to test.

## What exists

| Channel | Configuration | Carries attachments |
| --- | --- | --- |
| Email | The workspace SMTP server, or ours; sender verifiable by domain | Yes |
| WhatsApp | Meta’s WhatsApp Cloud API: phone number id, access token, and the template they approved | Yes, when the approved template declares a DOCUMENT header |
| Telegram | Bot token, and the destination’s numeric chat id; the bot has to be in the group or chat | Yes, sent as a document with the text as its caption |
| Webhook | URL, optional headers, and a secret for signing | Yes, the body is the result |
| Slack | Incoming webhook URL; a bot token with files:write for uploads | Only with a bot token |
| Discord | Webhook URL of the channel | No; it sends a summary and link |
| Google Sheets | Service account and spreadsheet id; share the spreadsheet with the service account as Editor | No; it writes rows to a tab |

- [Email](/docs/channel-email)
- [WhatsApp](/docs/channel-whatsapp)
- [Telegram](/docs/channel-telegram)
- [Webhook](/docs/channel-webhook)
- [Slack](/docs/channel-slack)
- [Discord](/docs/channel-discord)
- [Google Sheets](/docs/channel-google_sheets)

> The WhatsApp integration uses Meta’s official Cloud API. Messages outside the 24-hour window need a template they approved. That rule is Meta’s. On Telegram, a bot only reaches whoever messaged it first: the destination is the numeric chat id, and a person’s @name is not addressable by the Bot API.

## Test before depending on it

Every channel has a test button that validates the credentials against the provider without sending a message, and records the outcome: date, status, and the provider’s error when there was one. A channel that has never been tested is flagged in the list. To check delivery end to end, run the report: the run log says which channel each recipient went through and what the provider answered.

## Webhook signature

When you set a secret, every POST carries an HMAC-SHA256 signature of the body in a header. Verify it before processing: without that, anyone who discovers the URL can inject a fake report into your system.

---

# Command line

Source: https://www.datarunner.app/en/docs/cli

Install the DataRunner command line, authenticate, and turn a query into a build step.

## Install

A single self-contained binary. The machine needs nothing installed first, neither a runtime nor a package manager. That is what makes it usable in a lean CI image.

Linux and macOS:

```
curl -fsSL https://api.datarunner.app/downloads/cli/install.sh | bash
```

Windows:

```
irm https://api.datarunner.app/downloads/cli/install.ps1 | iex
```

> Neither asks for root or administrator: it installs into a user directory and adjusts that user PATH. The installer verifies the published SHA256 before installing and refuses on a mismatch.

Pin the version in CI. A job that resolves “latest” on every run changes behaviour without anybody making a commit.

```
curl -fsSL https://api.datarunner.app/downloads/cli/install.sh | bash -s -- --version 0.1.1
```

## The first five minutes

After installing, this is a whole session end to end. The step that usually goes missing is the second one: a query has an id, and listing is the only place it comes from.

1. Log in, once per machine. The key comes from Settings → API keys in the console, and is only shown at the moment you create it. The command asks for it without echoing, so it never goes through the command line or into shell history.
2. List what exists in the workspace. This is where the id the other commands want comes from.
3. Run a query and look at the result.
4. Turn that query into a check the build understands.

1 · log in:

```
datarunner auth login

  → chave: ••••••••••••••••••••••••

  ✔ servidor respondeu       api.datarunner.app • 84 ms
  ✔ chave aceita             you@acme.com • admin • Acme
  ✔ perfil 'default' salvo   cifrado para este usuário do Windows (DPAPI)
```

2 · see what exists:

```
datarunner query list

id                                    nome             conexao     atualizada
────────────────────────────────────  ───────────────  ──────────  ──────────────
3f2a91c4-8e17-4b2a-9f03-1d5c7e8a2b60  Monthly revenue  Postgres    2026-09-01 14:22
a7c04e12-3b95-4d81-b6ef-92a10c4d7f38  Orphan orders    Postgres    2026-08-28 09:10
```

3 · run it:

```
datarunner query run 3f2a91c4-8e17-4b2a-9f03-1d5c7e8a2b60

month       total
──────────  ─────────
2026-07     184320.50
2026-08     201455.00

2 linha(s) em 340ms.
```

4 · make it a build check:

```
datarunner query assert a7c04e12-3b95-4d81-b6ef-92a10c4d7f38 --expect-empty

ok — 0 linha(s) em 120ms.
```

> That last command exits 0 when no row came back and 1 when one did. That, and only that, is what stops the build when data integrity broke.

## Credential

The key comes from Settings → API keys. Its scopes narrow what the tool reaches on top of the role of whoever created it: a restricted key stays restricted even when it belongs to an admin, and a key never grants platform-wide powers.

On your machine: asks for the key without echoing:

```
datarunner auth login
datarunner auth login --url https://datarunner.yourcompany.com   # self-hosted
```

In CI: nothing is written to disk:

```
export DATARUNNER_URL=https://api.datarunner.app
export DATARUNNER_KEY=dr_...
```

> To run queries in CI, tick the run:queries scope. It already includes reading and cannot change anything. Listing queries and executing SQL against a production database are different powers, so read:queries alone does not run.

API keys are available from Team up, so the command line is too; Solo and Pro do not have it.

## A query as a build step

A query that lists orphaned rows is something anybody can write today and cannot enforce anywhere. With the command below it becomes a build step: if a migration broke referential integrity, the build fails instead of production finding out later.

```
datarunner query assert 3f2a... --expect-empty
```

| Check | Fails when |
| --- | --- |
| --expect-empty | any row came back |
| --expect-rows <n> | the count is not exactly that |
| --min-rows <n> | fewer than that came back |
| --max-rows <n> | more than that came back |

> If the result hits the plan row cap, the check fails rather than passes. A truncated count is not a count, and an --expect-empty that passes because the cap hid the rows is worse than no check at all, because somebody is relying on it.

## Every command

| Command | What it does | Key scope |
| --- | --- | --- |
| auth login \| list \| use \| logout | stores and switches credentials | — |
| whoami | checks the current credential | — |
| query list | lists queries, with the id | read:queries |
| query run <id> | runs and prints | run:queries |
| query assert <id> | runs and checks; exits 1 on failure | run:queries |
| monitor list \| status | monitor state | read:monitors |
| connection list | lists connections | read:connections |

Every command has its own help: datarunner help query, datarunner help monitor, and so on. datarunner help ci prints a ready CI file.

> run:queries already includes reading, so a CI key that only checks data needs nothing else. Listing queries and executing SQL against a production database are different powers, which is why read:queries alone does not run anything.

## Working with more than one environment

The first thing anybody does with this is point it at staging and then at production. Profiles exist so that switch is not another login.

```
datarunner auth login --url https://api.acme.dev --profile dev
datarunner auth login --url https://api.acme.com --profile prod

datarunner auth use prod
datarunner query list --profile dev    # without switching the current one
```

The file lives at ~/.datarunner/config.json. On Windows the key is sealed with DPAPI for your user: the file copied to another machine, another account or a backup does not open. On Linux and macOS, mode 600 in a 700 directory. Logout removes the profile from your machine; the key stays valid on the server until somebody revokes it in the console.

## Interactive mode

Type just datarunner in a terminal. The opening screen connects to the server and shows who you are and which workspace you are in; then a prompt takes the same commands without the prefix. Scripts and CI see no change: with no terminal, the bare binary still prints the help and exits 2.

```
datarunner:prod › query run Monthly rev⇥
datarunner:prod › query run 3f2a91c4-8e17-4b2a-9f03-1d5c7e8a2b60
→ Monthly revenue (3f2a91c4)
```

- Tab completes commands, options and ids by name. The list comes from the API, with your key's permissions.
- Wherever a command takes an id, a name or the start of the id works too, in and out of interactive mode. If it matches more than one, the CLI refuses and lists them instead of picking.
- Ctrl+C stops the running command, not the shell. History lives in memory only and never keeps a line carrying a key.

## AI agents (MCP)

The CLI is also an MCP (Model Context Protocol) server. Claude Desktop, Claude Code, Cursor and Windsurf get to see the workspace: connections, schemas, saved queries, read-only SQL, monitors and alerts. The agent can do at most what the key can, because permissions are checked on the server, exactly as for the console.

Connect in one command:

```
datarunner auth login
datarunner mcp install claude-desktop    # or: cursor, windsurf, claude-code

datarunner mcp tools                     # what the agent can do with this key
```

- No key goes into the AI client's config: it points at the profile, which stays sealed. The profile is pinned by name, so a later auth use prod does not repoint the agent at production.
- Read-only by default. Acknowledging alerts and testing connections are not even shown to the model without --allow-writes.
- Every id is validated before it becomes a URL, queries are rate-limited per minute, and the instructions tell the model that database content is data, never instructions.

> Free-form SQL takes the same path as the console editor: the server refuses destructive statements and applies column-masking policies before the result reaches the model.

## Output and exit codes

The default format is a table. Pass --json or --csv when a program will read the output. Only then does progress go to standard error, so it cannot dirty what you are capturing. Nothing is guessed: PowerShell reports output as redirected even at an ordinary prompt, so trying to detect it printed JSON at people who just wanted to look.

```
datarunner query run 3f2a... | jq '.rows[0]'
datarunner query run 3f2a... --format csv > revenue.csv
```

| Code | Means |
| --- | --- |
| 0 | ok |
| 1 | a check you asked for failed (the tool worked) |
| 2 | wrong usage |
| 3 | credential missing or refused |
| 4 | the server refused, or could not be reached |

> The split between 1 and 4 is the point: a build has to tell “the data is wrong” from “the tool is broken” without parsing prose.

## Other commands

- datarunner monitor status --fail-on-down: hold a deploy while something is already down.
- datarunner query list, connection list, whoami.

---

# Database monitor

Source: https://www.datarunner.app/en/docs/monitors

The health of every connected database: what is checked, the metrics that come with it, and how an incident starts.

## What is checked

Each connection can have a monitor. It runs, on a clock, the same health test the connections screen uses. A new connection starts with its monitor on, every 5 minutes; you can switch it off when creating the connection or change the interval later.

When the database answers, the monitor uses the same connection to read the engine’s own statistics: active sessions and their ceiling, idle transactions, blocked sessions, the oldest running query, cache hit ratio, database size and replication lag. What the engine does not report is left blank, never zero.

## Rules on the metrics

On the connection screen, a rule states the limit that matters, for example “sessions above 80% of the ceiling for 5 minutes”. It only fires after the tolerance period and tells you again when things are back to normal.

## Interval and limits

| Plan | Monitors | Minimum interval |
| --- | --- | --- |
| Solo | 1 | 5 minutes |
| Pro | 5 | 2 minutes |
| Team | 50 | 60 seconds |
| Business | 500 | 15 seconds |

## From failure to incident

A single failure does not open an incident. Networks hiccup, and an alert per hiccup trains everyone to ignore alerts. An incident opens when failures pass the threshold you set, and closes by itself when checks pass again. The recorded duration starts at the first failure, not at the moment the incident opened.

The alert says what depends on the database: which reports read from it and how many recipients are waiting for the result. Those reports’ schedules can be held until the database is back.

---

# Bridge to a private network

Source: https://www.datarunner.app/en/docs/bridge

How to query a database only your network can reach, without opening a firewall port.

## How it works

The DataRunner agent runs on a machine inside your network and opens an outbound line to us itself. A connection marked “through the bridge” reaches its database over that line, so a database on 10.0.0.5 or behind a VPN becomes queryable with no inbound rule at all.

## Install

1. In the console, under Connections → Bridges, create a bridge. The key is shown once.
2. Install the agent on the machine and run the command the screen shows, with the key and the list of databases it may reach.
3. On the connection, pick the bridge. From then on queries, reports and the monitor go through it.

```
datarunner-agent bridge --server https://api.datarunner.app --key drb_… --allow 10.0.0.5:5432 --save
```

## What the agent can and cannot do

What the bridge can reach is decided by the allow-list, on your machine: a request for any other address is refused right there. The agent holds no database credential, exposes no port and accepts no remote command. The key is stored hashed on the server and can be rotated at any time.

It keeps itself up to date: a few times a day it reads the manifest from the channel it was installed from, and when there is a newer version it downloads the binary from that version’s immutable directory, verifies the declared SHA-256, runs the binary once so it states its own version, and only then swaps it in.

## Platforms

- Windows: x86-64 and ARM64
- Linux: x86-64 and ARM64

> There is no macOS build. When there is, it will appear on the download page.

---

# Alerts and routes

Source: https://www.datarunner.app/en/docs/alerting

Where the notice of a database going down, or of a rule that fired, goes.

## Alert routes

A route says which channel an alert goes out on, and in what order: email, Slack, Telegram, WhatsApp or webhook. It applies to database monitors, metric rules and report rules, and is defined once.

A later step with a delay is escalation: if nobody acknowledges the alert within 10 minutes, the second channel is told. Every alert also reaches the console bell, route or not.

> The routes screen has a simulator: it tells you whether an alert would match a route and whether each step would reach anyone, without waiting for a real outage.

---

# Security and data

Source: https://www.datarunner.app/en/docs/security

Encryption, roles, authentication, audit, and what you can export or delete.

## Encryption

- Connection credentials and channel configuration: AES-GCM at rest.
- User passwords: bcrypt at work factor 12. Never in plaintext, never reversible.
- Traffic: TLS between you and the service, and between the service and your database when the server offers it.

## Who gets in, and what they can do

- Password, passkey, or social sign-in.
- Roles with per-resource permissions; a workspace can adjust what each role reaches.
- Scoped per-workspace API keys for automation and for the command line. The scope narrows on top of the role of whoever created the key, and a key never grants platform-wide powers. Available from Team up.
- Sessions are visible and revocable one by one.

## Audit

The audit log records who did what and when, and can be exported on a schedule to a workspace destination. Column policies let you mask sensitive fields in query results for roles that should not see them.

> Masking matches on the source schema, table and column. The alias the query gave the field does not count. On Trino, Presto and Athena the protocol does not report which table each result column came from, so a policy on those sources is stored and never applied. The screen says so at the moment you create the policy; to mask for real on those sources, do it in the view or table itself.

## Export and delete

- Export: download your personal data in a machine-readable format, straight from the console.
- Deletion: the account enters a grace period before permanent removal, and you can cancel within it.
- Retention: run data follows the plan’s retention and is deleted by a routine, not on request.

> Security issues: write to projeto@datarunner.app. We acknowledge receipt and keep you posted until the fix ships.

---

# Dashboards and sharing

Source: https://www.datarunner.app/en/docs/dashboards

Panels built from queries, per-dashboard filters, public links with password and expiry, and the iframe.

## What a dashboard is

A dashboard is a grid of widgets, and each widget is a saved query drawn as a table, number, line, area, bar, pie, scatter, histogram, gauge, heatmap, combo, treemap or funnel. The query stays one thing: changing the SQL changes the widget on every dashboard that uses it. Plan limits: 2 dashboards on Solo, 10 on Pro, 25 on Team, 200 on Business.

- Dashboard filters become query parameters (`:name`), so one date-range filter reaches every widget that declares it.
- Results come from the query cache when there is one; "Refresh" forces a re-read from the database.
- Column masking policies apply on a dashboard exactly as in the editor, and no path returns the raw value.

## Public link

Any query, report or dashboard can get a public link: whoever has it sees the resource read-only, no account needed. Data is re-read on every visit, always with masking applied.

1. On the dashboard, choose Share and, optionally, set a password and an expiry date.
2. The link is shown once, because it is stored hashed and cannot be displayed again. Lost it? Settings → Shares issues a replacement without losing the view count.
3. "Copy embed code" gives the same link as an `<iframe>`, for a wall screen or an intranet page.
4. Revoke under Settings → Shares; the link stops working immediately.

> Without a password, anyone with the link sees the data. The dashboard says so when the link is created, and the shares screen shows how many times each one was opened.

---

# Recipients

Source: https://www.datarunner.app/en/docs/contacts

Who receives a report: contacts, lists with segments, and unsubscribes.

## Who receives it

A report is delivered to recipients: a loose address, a contact, or a list. A contact is a person with at least one channel: e-mail, WhatsApp or Telegram. A list is a set of contacts, assembled by hand or by segment, which is a filter over the fields ("state = SP and plan = pro") and re-evaluates on its own. The contact or list is read again on every send, so whoever joins or leaves the list starts or stops receiving without any change to the schedule.

1. Import from a spreadsheet: `.xlsx` or `.csv`. The preview shows what will go in before anything is saved.
2. Fields beyond name and channel are defined per workspace under Settings → Contact fields, and can be used as segment filters.
3. The API (`POST /api/v1/contacts`) creates and updates by channel.

## Unsubscribe

Someone who no longer wants a report unsubscribes through the link at the foot of the e-mail, or through the mail provider's own button (the `List-Unsubscribe` header). An unsubscribe has a scope: the list that sent it, or the whole workspace. It never deletes the contact; it only records that the address no longer receives, and the Unsubscribes screen shows who left and through where.

---

# API, keys and outbound webhooks

Source: https://www.datarunner.app/en/docs/api

The browsable reference, how to authenticate with a key, and the events the product pushes to your endpoint.

## Reference

Every route is documented at `https://api.datarunner.app/docs` (OpenAPI at `/openapi/v1.json`). It is the same API the console uses, with no separate "public" version that has less in it.

## API keys

A key (`dr_…`) belongs to a workspace and carries scopes: `queries:read`, `monitors:read`, and so on. The scope narrows on top of the role of whoever created the key, and a key never grants platform power. Available on Team (25) and Business (100).

Both accepted forms:

```
curl -H "X-Api-Key: dr_…" https://api.datarunner.app/api/v1/queries
curl -H "Authorization: Bearer dr_…" https://api.datarunner.app/api/v1/queries
```

## Outbound webhooks

Under Settings → Webhooks you register a URL and pick events. Every delivery is a POST with JSON `{ event, timestamp, data }` and, when a secret is set, the header `X-DataRunner-Signature: sha256=<HMAC of the body>`. The delivery log keeps 30 days of attempts with status, error and duration.

| Event | When |
| --- | --- |
| run.succeeded | a query run finished successfully |
| run.failed | a query run failed |
| usage.threshold_crossed | monthly usage crossed 50%, 80% or 100% of the plan |

Verifying the signature (Node):

```
const expected = 'sha256=' + crypto
  .createHmac('sha256', SECRET)
  .update(rawBody)
  .digest('hex');
if (expected !== req.headers['x-datarunner-signature']) return res.status(401).end();
```

---

# Plans, billing and account

Source: https://www.datarunner.app/en/docs/billing

Monthly or yearly, what happens when the card fails, extra workspaces, ownership and a confirmed e-mail.

## Plans

Solo (free), Pro ($19/month or $190/year), Team ($49/month or $490/year) and Business (priced on request, invoiced). Yearly is one payment for ten months, two free. Billed through Stripe by card, in US dollars, or in Brazilian reais (R$ 79/790 and R$ 197/1,970) when you are in Brazil, since cards issued there must pay in reais; the currency follows your country, nothing to pick. Changing plan or cadence happens in the Stripe portal, from Settings → Billing; the change applies immediately and is prorated. For Business, talk to us and we set the subscription up for you.

> Declined card: the workspace runs on Solo limits until Stripe manages to charge (it retries for a few days). The owner gets an e-mail and the console shows a bar with a link to update the card. Nothing is deleted.

## Account and workspace

- Confirming your e-mail (six-digit code at signup) unlocks opening more workspaces. Unconfirmed, the rest of the product works.
- Changing your e-mail: Settings → Profile, with your current password; the code goes to the new address and the old one gets a notice.
- More than one workspace: "New workspace…" in the workspace menu. Each has its own connections, members and plan; an account can own up to ten.
- Owner: the one who can delete the workspace and hand it over (Settings → Workspace → Ownership, to a member with a confirmed e-mail). The previous owner stays an admin.
- Passkeys and sign-in with Google, Microsoft or GitHub under Settings → Security; social sign-in only enters an account that already exists with the same e-mail.

---

# Email

Source: https://www.datarunner.app/en/docs/channel-email

Wiring up Email: what to create at the provider, what to paste here, what goes in Target, and how to test before depending on it.

## What it is

Sends through the email provider configured for this workspace. The channel itself holds no credentials.

## Set up

About 2 minutes to a working channel.

1. Configure the workspace mailer first. Settings → Email: pick a provider (SMTP or Resend) and a verified sender address. Reports go out from your domain, not ours.
2. Name the channel. Name it, and pick which of your verified domains it sends as — leave that on the default and it uses the workspace From. Create one channel per sending address; the recipient lives on the route, not here.
3. Test, then attach it to a report. Test sends through the workspace provider, so a failure here is an email-settings problem. Then open a report → Destinations to pick who receives it.

## Fields

| Field | Required | What it is |
| --- | --- | --- |
| Send from | No | Which of your verified domains this channel sends as. Transport still comes from the workspace provider — this only sets the From. |

## What goes in Target

The recipient address, e.g. team@acme.com. Required — an email route with an empty Target never leaves.

> Target is required for this channel: a route without one never leaves. — recipient@example.com

## Test

Every channel has a Test button in the channel list (Settings → Channels). The result is kept (date, status and the provider's error when there was one), and a channel that was never tested is marked in the list.

> The e-mail channel has no test of its own: it sends through the workspace provider. Test the transport in Settings → E-mail → Test, which sends a real e-mail to the address you give.

## Check it end to end

1. Report: open a report, add this channel under Destinations (with the Target when the channel needs one), click Run now and open the run. The log says which channel each recipient went through and what the provider answered.
2. Alert: under Alerts → Alert routes, create a route with this channel as an escalation step. Routes match on severity and source; the first match wins.
3. To fire an alert without breaking anything: use a test database you can switch off, and create a database monitor pointing at it, on a short interval. When it goes down the alert leaves through the route; delete the monitor afterwards. The message carries an acknowledge link; click it and the escalation stops.
4. Report rules (new rows, value out of range) arrive through the same route, with source "report rule".

## What most often goes wrong

> There is no fallback to the platform mailer. A workspace with no email provider configured fails the delivery instead of sending from our domain.

## Official documentation

- [DataRunner — email and sending domains](https://www.datarunner.app/en/docs/channels#email)
- [Channels overview](/docs/channels)

---

# WhatsApp

Source: https://www.datarunner.app/en/docs/channel-whatsapp

Wiring up WhatsApp: what to create at the provider, what to paste here, what goes in Target, and how to test before depending on it.

## What it is

Meta’s official Cloud API — no ban risk, but Meta decides what may be sent. Proactive delivery requires an approved template.

> This channel is in beta: it works, but has not yet been exercised in production by many customers. Tell us what you find.

## Set up

About 20 minutes to a working channel.

1. Create a Business app on Meta. developers.facebook.com → My Apps → Create App → type Business. You need a Meta Business account; creating one takes a couple of minutes.
2. Add the WhatsApp product and open API Setup. That screen shows the Phone number ID (copy it) and a temporary access token valid for 24h — good enough for the first test, not for production.
3. Register your own number under “To”. While the app is in test mode Meta only delivers to numbers verified in that list. Skipping this is the most common cause of “it says sent but nothing arrived”.
4. Generate a permanent token. Business Settings → Users → System Users → create one → Add Assets (your WhatsApp app) → Generate new token with the whatsapp_business_messaging permission. That one does not expire.
5. Create a template and get it approved. WhatsApp Manager → Message templates. The body can declare as many parameters as you like, or none — the Template parameters field below says what fills each. To attach the report file the template must also declare a DOCUMENT header. Approval takes minutes to hours.
6. Fill the fields here, then Test. Test validates the token and the phone number id against the Graph API without sending a message. The real send happens when a report runs.

- [Meta — my apps](https://developers.facebook.com/apps)
- [Meta — Cloud API: get started](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started)
- [Meta — permanent System User token](https://developers.facebook.com/docs/whatsapp/business-management-api/get-started)
- [WhatsApp Manager — my templates](https://business.facebook.com/wa/manage/message-templates/)

## Fields

| Field | Required | What it is |
| --- | --- | --- |
| Phone Number ID | Yes | Meta app → WhatsApp → API Setup. It is a number id, not the phone number itself. (1234567890) |
| Access token | Yes | Temporary token from API Setup (24h) for a first test, or a permanent System User token for production. |
| API version | No | Graph API version. Leave v21.0 unless Meta deprecates it. (v21.0) |
| Approved template | No | Required for proactive sends. How many parameters the body declares is up to you — the field below says what fills each. A DOCUMENT header is needed when the report produces a file (CSV/XLSX/PDF), and unnecessary when it is Inline HTML. Empty means free-form text, which Meta delivers only inside the 24h window. (report_ready) |
| Template language | No | Meta language code of the approved template, e.g. pt_BR or en_US. A mismatch here comes back as “template not found”, which points at the name and not the language. Left blank it falls back to en_US. (pt_BR) |
| Template parameters | No | One line per body parameter of the approved template: line 1 fills {{1}}, line 2 fills {{2}}, and so on. Use {{message}} for the report copy, plus any report placeholder — {{report_name}}, {{rows}}, {{result_summary}}, {{date}}. Meta refuses the send when the count differs from what the template declares (error 132000). Left blank it sends one parameter carrying the whole message, which is right for a template written as a bare {{1}}; a single - means the template takes no parameters at all, which is right for one whose body is fixed text. ({{message}}) |

## What goes in Target

The recipient phone in international format, digits only: 5511999999999. No plus sign, spaces or dashes — anything else is stripped before the call.

> Target is required for this channel: a route without one never leaves. — 5511999999999

## Test

Every channel has a Test button in the channel list (Settings → Channels). The result is kept (date, status and the provider's error when there was one), and a channel that was never tested is marked in the list.

> Test validates the access token and the phone number id against Meta without sending a message. The first real delivery is what proves the template and the 24-hour window.

## Check it end to end

1. Report: open a report, add this channel under Destinations (with the Target when the channel needs one), click Run now and open the run. The log says which channel each recipient went through and what the provider answered.
2. Alert: under Alerts → Alert routes, create a route with this channel as an escalation step. Routes match on severity and source; the first match wins.
3. To fire an alert without breaking anything: use a test database you can switch off, and create a database monitor pointing at it, on a short interval. When it goes down the alert leaves through the route; delete the monitor afterwards. The message carries an acknowledge link; click it and the escalation stops.
4. Report rules (new rows, value out of range) arrive through the same route, with source "report rule".

## What most often goes wrong

> Outside the 24h customer-service window Meta only delivers approved templates. With Approved template empty a report goes out as free-form text, which means it reaches almost nobody and reports no error; a campaign refuses to send rather than pretend. It is Meta’s rule, not a DataRunner bug.

## Official documentation

- [Meta — Cloud API: get started](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started)
- [Meta — message templates](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates)
- [Meta — permanent System User token](https://developers.facebook.com/docs/whatsapp/business-management-api/get-started)
- [Meta — error codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes)
- [Channels overview](/docs/channels)

---

# Telegram

Source: https://www.datarunner.app/en/docs/channel-telegram

Wiring up Telegram: what to create at the provider, what to paste here, what goes in Target, and how to test before depending on it.

## What it is

Bot API. The bot must already be in the chat, and the chat id goes on the route or on the contact — not here.

## Set up

About 5 minutes to a working channel.

1. Create the bot with @BotFather. Open Telegram, talk to @BotFather, send /newbot, choose a display name and a username ending in “bot”. He answers with a token shaped like 123456789:AAE… .
2. Paste the token, then Test. Test calls getMe: it proves the token is valid. It does not send a message, because the destination chat lives on the route.
3. Put the bot where you want the report. Direct chat: send it any message. Group: add it as a member, then send a message. Channel: add it as an administrator.
4. Read the chat_id. Use the Chat ids button on this channel: it lists every chat that has messaged the bot, with the id to copy. (The same data is at https://api.telegram.org/bot<TOKEN>/getUpdates, but that puts your bot token in a browser URL.) Groups come back negative — copy the minus sign too.
5. Put the chat_id on the route. Report → Destinations → Channel, and paste the chat_id into Target. An empty Target fails with “Telegram route Target is empty (need chat_id)”.

- [Open @BotFather](https://t.me/BotFather)
- [Bot API — getUpdates](https://core.telegram.org/bots/api#getupdates)

## Fields

| Field | Required | What it is |
| --- | --- | --- |
| Bot token | Yes | What @BotFather answered to /newbot. The chat id does not go here — it goes on the route. (123456789:AAE…) |

## What goes in Target

The numeric chat_id. A person: a positive number, and they must have messaged the bot first — a bot cannot open a conversation. A group or supergroup: negative, usually starting with -100, and the bot has to be a member. A PUBLIC channel or supergroup is the one case where @name works; a person’s @name never does.

> Target is required for this channel: a route without one never leaves. — chat_id, e.g. -1001234567890

## Test

Every channel has a Test button in the channel list (Settings → Channels). The result is kept (date, status and the provider's error when there was one), and a channel that was never tested is marked in the list.

> Test calls getMe with the token: it proves the bot exists. It does not prove the chat id: if the bot is not in the group, or nobody has messaged it, the first real delivery fails with "chat not found".

## Check it end to end

1. Report: open a report, add this channel under Destinations (with the Target when the channel needs one), click Run now and open the run. The log says which channel each recipient went through and what the provider answered.
2. Alert: under Alerts → Alert routes, create a route with this channel as an escalation step. Routes match on severity and source; the first match wins.
3. To fire an alert without breaking anything: use a test database you can switch off, and create a database monitor pointing at it, on a short interval. When it goes down the alert leaves through the route; delete the monitor afterwards. The message carries an acknowledge link; click it and the escalation stops.
4. Report rules (new rows, value out of range) arrive through the same route, with source "report rule".

## What most often goes wrong

> A person’s @username is not addressable by a bot at all — “@someone” always comes back as “chat not found”. Use the numeric id, and remember the bot cannot see messages sent before it joined: send one afterwards or there is no chat id to read.

## Official documentation

- [Telegram — creating a bot](https://core.telegram.org/bots#how-do-i-create-a-bot)
- [Bot API — getUpdates](https://core.telegram.org/bots/api#getupdates)
- [Bot API — sendDocument](https://core.telegram.org/bots/api#senddocument)
- [Channels overview](/docs/channels)

---

# Generic webhook

Source: https://www.datarunner.app/en/docs/channel-webhook

Wiring up Generic webhook: what to create at the provider, what to paste here, what goes in Target, and how to test before depending on it.

## What it is

Generic JSON POST. The body carries report metadata, the rendered HTML and the attachment as base64.

## Set up

About 5 minutes to a working channel.

1. Have an endpoint that accepts POST. It must accept application/json and answer 2xx. Anything else is recorded as a delivery failure with the status code and body. To try it without writing code, webhook.site gives you a URL that shows every request live.
2. Paste the URL, then Test. Test posts a tiny probe body, not the real shape. The delivery payload is the larger envelope described in the payload reference below.
3. Optional: sign the payload. With an HMAC secret set, every request carries X-DataRunner-Signature: sha256=<hex> — the HMAC-SHA256 of the raw body. Recompute it on your side before trusting the payload.
4. Optional: extra headers. A flat JSON object, e.g. an Authorization header. Invalid JSON is dropped silently instead of blocking the save — check this field first if a header never arrives.
5. Attach it to a report. Report → Destinations → Channel. Treat delivery as at-least-once and dedupe on the run id plus the route.

- [webhook.site — throwaway test URL](https://webhook.site)
- [DataRunner — webhook payload](https://www.datarunner.app/en/docs/channels#webhooks)

## Fields

| Field | Required | What it is |
| --- | --- | --- |
| URL | Yes | Must be public and reachable over HTTPS. Private addresses are refused by the SSRF guard. (https://api.example.com/hooks/datarunner) |
| HMAC secret (optional) | No | When set, X-DataRunner-Signature carries sha256=<hex> of the raw body. |
| Extra headers JSON | No | Flat JSON object. Invalid JSON is dropped without blocking the save. ({"X-Tenant":"acme"}) |

## What goes in Target

Optional. Whatever you type is appended as a path to the configured URL — leave it empty to post to the URL itself.

> Target is optional for this channel. — optional extra path

## Test

Every channel has a Test button in the channel list (Settings → Channels). The result is kept (date, status and the provider's error when there was one), and a channel that was never tested is marked in the list.

> Test POSTs the body {"event":"datarunner.test"} with the configured headers. Your endpoint must answer 2xx; what it does with that event is up to you, and ignoring it is fine.

## Check it end to end

1. Report: open a report, add this channel under Destinations (with the Target when the channel needs one), click Run now and open the run. The log says which channel each recipient went through and what the provider answered.
2. Alert: under Alerts → Alert routes, create a route with this channel as an escalation step. Routes match on severity and source; the first match wins.
3. To fire an alert without breaking anything: use a test database you can switch off, and create a database monitor pointing at it, on a short interval. When it goes down the alert leaves through the route; delete the monitor afterwards. The message carries an acknowledge link; click it and the escalation stops.
4. Report rules (new rows, value out of range) arrive through the same route, with source "report rule".

## What most often goes wrong

> Private addresses (localhost, 10.x, 192.168.x, *.internal) are blocked as SSRF protection. To reach a service on your machine, expose it through a public tunnel first.

## Official documentation

- [DataRunner — webhook payload](https://www.datarunner.app/en/docs/channels#webhooks)
- [webhook.site — throwaway test URL](https://webhook.site)
- [Channels overview](/docs/channels)

---

# Slack

Source: https://www.datarunner.app/en/docs/channel-slack

Wiring up Slack: what to create at the provider, what to paste here, what goes in Target, and how to test before depending on it.

## What it is

Incoming webhook. Reports arrive as a message with the summary; alerts carry severity, source and a link back to the console.

## Set up

About 3 minutes to a working channel.

1. Create a Slack app with Incoming Webhooks. Open api.slack.com/apps → Create New App → From scratch. In the app, open Incoming Webhooks, switch it on, and click “Add New Webhook to Workspace”. Slack asks which channel it may post to.
2. Copy the webhook URL. It looks like https://hooks.slack.com/services/T…/B…/… . Paste it here. Test posts a short message to that channel — if it lands, everything else will.
3. Attach it to a report or an alert route. Report → Destinations → Channel sends the result summary. Alerts → Alert routes → add this channel as a step: a monitor that fires arrives with severity and a link.
4. Optional: attach the result file. Webhooks cannot upload files. If you want the CSV or XLSX in Slack, give the app the files:write scope, install it, paste the bot token (xoxb-…), and put the channel id in the route Target.
5. Silence what you do not want. A report that sends every hour to a busy channel gets muted by everyone. Use report rules (skip when empty, deliver only above N rows) so Slack only hears what is worth reading.

- [Slack — your apps](https://api.slack.com/apps)
- [Slack — uploading files](https://api.slack.com/messaging/files)

## Fields

| Field | Required | What it is |
| --- | --- | --- |
| Webhook URL | Yes | From the app’s Incoming Webhooks page. Bound to one channel; treated as a secret. (https://hooks.slack.com/services/T000/B000/XXXX) |
| Bot token (optional) | No | Only for file uploads. Needs the files:write scope and the app installed in the workspace. (xoxb-…) |

## What goes in Target

Optional. An incoming webhook is bound to one Slack channel when you create it, so Target is ignored for messages. With a bot token, Target is the channel id (C0123…) the result file is uploaded to.

> Target is optional for this channel. — channel id for file upload (optional)

## Test

Every channel has a Test button in the channel list (Settings → Channels). The result is kept (date, status and the provider's error when there was one), and a channel that was never tested is marked in the list.

> Test posts "DataRunner channel test ✅" to the channel the webhook is bound to. If that lands, everything else lands.

## Check it end to end

1. Report: open a report, add this channel under Destinations (with the Target when the channel needs one), click Run now and open the run. The log says which channel each recipient went through and what the provider answered.
2. Alert: under Alerts → Alert routes, create a route with this channel as an escalation step. Routes match on severity and source; the first match wins.
3. To fire an alert without breaking anything: use a test database you can switch off, and create a database monitor pointing at it, on a short interval. When it goes down the alert leaves through the route; delete the monitor afterwards. The message carries an acknowledge link; click it and the escalation stops.
4. Report rules (new rows, value out of range) arrive through the same route, with source "report rule".

## What most often goes wrong

> One webhook posts to exactly one Slack channel — the one chosen when the webhook was created. To reach #alerts and #reports, create two channels here, each with its own webhook URL. The URL is a secret: anyone holding it can post as you.

## Official documentation

- [Slack — incoming webhooks](https://api.slack.com/messaging/webhooks)
- [Slack — uploading files](https://api.slack.com/messaging/files)
- [Channels overview](/docs/channels)

---

# Discord

Source: https://www.datarunner.app/en/docs/channel-discord

Wiring up Discord: what to create at the provider, what to paste here, what goes in Target, and how to test before depending on it.

## What it is

Channel webhook. The message carries the summary; the result file is attached when there is one.

## Set up

About 2 minutes to a working channel.

1. Create a webhook on the channel. Channel settings (gear) → Integrations → Webhooks → New Webhook. Name it, pick the channel, and “Copy Webhook URL”.
2. Paste the URL, then Test. Test posts a short message to the channel. The display name here overrides the one set in Discord.
3. Attach it to a report or an alert route. Report → Destinations → Channel, or Alerts → Alert routes. Alerts arrive with severity and a link to the console.

- [Discord — webhooks](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks)

## Fields

| Field | Required | What it is |
| --- | --- | --- |
| Webhook URL | Yes | From the channel’s Integrations page. Treated as a secret. (https://discord.com/api/webhooks/…) |
| Display name (optional) | No | Shown as the sender. Leave empty to keep the name set on the webhook. (DataRunner) |

## What goes in Target

Optional. A thread id: the message is posted inside that thread instead of the channel the webhook belongs to.

> Target is optional for this channel. — thread id (optional)

## Test

Every channel has a Test button in the channel list (Settings → Channels). The result is kept (date, status and the provider's error when there was one), and a channel that was never tested is marked in the list.

> Test posts a short message to the webhook's channel.

## Check it end to end

1. Report: open a report, add this channel under Destinations (with the Target when the channel needs one), click Run now and open the run. The log says which channel each recipient went through and what the provider answered.
2. Alert: under Alerts → Alert routes, create a route with this channel as an escalation step. Routes match on severity and source; the first match wins.
3. To fire an alert without breaking anything: use a test database you can switch off, and create a database monitor pointing at it, on a short interval. When it goes down the alert leaves through the route; delete the monitor afterwards. The message carries an acknowledge link; click it and the escalation stops.
4. Report rules (new rows, value out of range) arrive through the same route, with source "report rule".

## What most often goes wrong

> A Discord message holds 2,000 characters. Long result tables are cut — the full result travels as the attached file, so keep the attachment on for reports that matter.

## Official documentation

- [Discord — webhooks](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks)
- [Channels overview](/docs/channels)

---

# Google Sheets

Source: https://www.datarunner.app/en/docs/channel-google_sheets

Wiring up Google Sheets: what to create at the provider, what to paste here, what goes in Target, and how to test before depending on it.

## What it is

Writes the report rows to a tab of a Google Sheets spreadsheet, through a service account. Each run replaces the tab, or adds rows under it.

## Set up

About 10 minutes to a working channel.

1. Create a service account key. In Google Cloud, enable the Google Sheets API on a project. Then create a service account, and add a JSON key to it (IAM → Service accounts → Keys → Add key → JSON).
2. Share the spreadsheet with the service account. Open the spreadsheet → Share, and add the client_email from the key file (it ends in .iam.gserviceaccount.com) as Editor.
3. Paste the key and the spreadsheet. Paste the whole JSON file into Service account JSON, and the spreadsheet link or id into Spreadsheet. Test reads the spreadsheet to confirm it can see it.
4. Attach it to a report. Report → Destinations → Channel, and set the Target to the tab name. The rows are the run’s result as masked for delivery, the same ones the e-mail carries.

- [Google Cloud — service account keys](https://cloud.google.com/iam/docs/keys-create-delete)

## Fields

| Field | Required | What it is |
| --- | --- | --- |
| Spreadsheet | Yes | The browser link, or the id between /d/ and /edit in it. (https://docs.google.com/spreadsheets/d/…/edit) |
| Service account JSON | Yes | Paste the whole key file. Treated as a secret. Share the spreadsheet with its client_email as Editor. ({"type":"service_account", …}) |

## What goes in Target

The tab name in the spreadsheet, e.g. Sheet1. Add |append to add rows under the existing ones (Sheet1|append); without it, each run replaces the tab. Leave it empty for the first tab.

> Target is optional for this channel. — tab name, e.g. Sheet1 (or Sheet1|append)

## Test

Every channel has a Test button in the channel list (Settings → Channels). The result is kept (date, status and the provider's error when there was one), and a channel that was never tested is marked in the list.

> 

## Check it end to end

1. Report: open a report, add this channel under Destinations (with the Target when the channel needs one), click Run now and open the run. The log says which channel each recipient went through and what the provider answered.
2. Alert: under Alerts → Alert routes, create a route with this channel as an escalation step. Routes match on severity and source; the first match wins.
3. To fire an alert without breaking anything: use a test database you can switch off, and create a database monitor pointing at it, on a short interval. When it goes down the alert leaves through the route; delete the monitor afterwards. The message carries an acknowledge link; click it and the escalation stops.
4. Report rules (new rows, value out of range) arrive through the same route, with source "report rule".

## What most often goes wrong

> The service account only sees spreadsheets shared with its client_email. Share the spreadsheet with that address as Editor, or every run and Test fails with 403.

## Official documentation

- [Google Sheets API — getting started](https://developers.google.com/workspace/sheets/api/guides/concepts)
- [Google Cloud — service account keys](https://cloud.google.com/iam/docs/keys-create-delete)
- [Channels overview](/docs/channels)

---

# PostgreSQL health (PostgreSQL)

Dead tuples, unused indexes, open transactions, lock waits, cache hit and the statements that cost the most.

## Dead tuples by table

Source: https://www.datarunner.app/en/templates/postgres/dead-tuples

Tables where dead rows pile up against live ones. Above 20% the autovacuum is losing; above 50% reads are paying for it.

```sql
SELECT schemaname || '.' || relname AS table_name,
       n_live_tup AS live_rows,
       n_dead_tup AS dead_rows,
       ROUND(100.0 * n_dead_tup / NULLIF(n_live_tup + n_dead_tup, 0), 1) AS dead_pct,
       last_autovacuum,
       last_vacuum
FROM pg_stat_user_tables
WHERE n_live_tup + n_dead_tup > 1000
ORDER BY n_dead_tup DESC
LIMIT 25
```

## Indexes never used

Source: https://www.datarunner.app/en/templates/postgres/unused-indexes

Non-unique indexes with zero scans since the last statistics reset, with the space they take. Each one is write cost with no read benefit.

```sql
SELECT s.schemaname || '.' || s.relname AS table_name,
       s.indexrelname AS index_name,
       pg_size_pretty(pg_relation_size(s.indexrelid)) AS size,
       pg_relation_size(s.indexrelid) AS size_bytes,
       s.idx_scan AS scans
FROM pg_stat_user_indexes s
JOIN pg_index i ON i.indexrelid = s.indexrelid
WHERE s.idx_scan = 0
  AND NOT i.indisunique
  AND NOT i.indisprimary
ORDER BY pg_relation_size(s.indexrelid) DESC
LIMIT 25
```

## Transactions open for more than 5 minutes

Source: https://www.datarunner.app/en/templates/postgres/open-transactions

Sessions holding a transaction open, including idle-in-transaction ones, which block vacuum and hold locks while doing nothing.

```sql
SELECT pid,
       usename AS user_name,
       application_name,
       client_addr,
       state,
       EXTRACT(EPOCH FROM (now() - xact_start))::int AS open_seconds,
       LEFT(query, 200) AS query
FROM pg_stat_activity
WHERE xact_start IS NOT NULL
  AND now() - xact_start > interval '5 minutes'
  AND pid <> pg_backend_pid()
ORDER BY xact_start
```

## Sessions waiting on a lock

Source: https://www.datarunner.app/en/templates/postgres/lock-waits

Who is waiting, on whom, and for how long. An empty result is the healthy one.

```sql
SELECT w.pid AS waiting_pid,
       w.usename AS waiting_user,
       EXTRACT(EPOCH FROM (now() - w.query_start))::int AS waiting_seconds,
       LEFT(w.query, 120) AS waiting_query,
       b.pid AS blocking_pid,
       b.usename AS blocking_user,
       b.state AS blocking_state,
       LEFT(b.query, 120) AS blocking_query
FROM pg_stat_activity w
JOIN LATERAL unnest(pg_blocking_pids(w.pid)) AS bp(pid) ON true
JOIN pg_stat_activity b ON b.pid = bp.pid
WHERE w.wait_event_type = 'Lock'
ORDER BY w.query_start
```

## Statements by total time

Source: https://www.datarunner.app/en/templates/postgres/slowest-statements

The statements that cost the most in aggregate: mean time × calls. Optimising the top three usually moves the whole server.

> Requires: The pg_stat_statements extension must be installed and in shared_preload_libraries.

```sql
SELECT LEFT(query, 160) AS statement,
       calls,
       ROUND(total_exec_time::numeric, 0) AS total_ms,
       ROUND(mean_exec_time::numeric, 2) AS mean_ms,
       rows,
       ROUND(100.0 * shared_blks_hit / NULLIF(shared_blks_hit + shared_blks_read, 0), 1) AS cache_hit_pct
FROM pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 20
```

## Largest tables

Source: https://www.datarunner.app/en/templates/postgres/largest-tables

Total size including indexes and TOAST. The number to watch over weeks, not once.

```sql
SELECT n.nspname || '.' || c.relname AS table_name,
       pg_size_pretty(pg_total_relation_size(c.oid)) AS total_size,
       pg_total_relation_size(c.oid) AS total_bytes,
       pg_size_pretty(pg_relation_size(c.oid)) AS table_size,
       pg_size_pretty(pg_indexes_size(c.oid)) AS indexes_size,
       c.reltuples::bigint AS estimated_rows
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE c.relkind IN ('r', 'p', 'm')
  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
ORDER BY pg_total_relation_size(c.oid) DESC
LIMIT 20
```

## Cache hit ratio

Source: https://www.datarunner.app/en/templates/postgres/cache-hit

Share of reads served from shared buffers, for tables and for indexes. Below 99% on a warm OLTP server means the working set no longer fits.

```sql
SELECT 'tables' AS kind,
       ROUND(100.0 * SUM(heap_blks_hit) / NULLIF(SUM(heap_blks_hit) + SUM(heap_blks_read), 0), 2) AS hit_pct
FROM pg_statio_user_tables
UNION ALL
SELECT 'indexes',
       ROUND(100.0 * SUM(idx_blks_hit) / NULLIF(SUM(idx_blks_hit) + SUM(idx_blks_read), 0), 2)
FROM pg_statio_user_indexes
```

## Connections by state

Source: https://www.datarunner.app/en/templates/postgres/connections-by-state

Open sessions grouped by state, against max_connections. Many idle sessions mean the pool is too big; many active ones mean the server is too small.

```sql
SELECT COALESCE(state, 'unknown') AS state,
       COUNT(*) AS sessions,
       (SELECT setting::int FROM pg_settings WHERE name = 'max_connections') AS max_connections
FROM pg_stat_activity
WHERE backend_type = 'client backend'
GROUP BY state
ORDER BY sessions DESC
```

## Sequences past 80% of their range

Source: https://www.datarunner.app/en/templates/postgres/sequences-near-limit

An integer sequence that reaches its maximum stops the inserts on that table. This catches it months earlier.

```sql
SELECT schemaname || '.' || sequencename AS sequence_name,
       last_value,
       max_value,
       ROUND(100.0 * last_value / max_value, 2) AS used_pct
FROM pg_sequences
WHERE last_value IS NOT NULL
  AND last_value > max_value * 0.8
ORDER BY used_pct DESC
```

## Replication lag

Source: https://www.datarunner.app/en/templates/postgres/replication-lag

For a primary with replicas: how far behind each one is, in bytes and in time. Empty on a server with no replicas.

```sql
SELECT client_addr,
       application_name,
       state,
       sync_state,
       pg_wal_lsn_diff(pg_current_wal_lsn(), replay_lsn) AS replay_lag_bytes,
       EXTRACT(EPOCH FROM replay_lag)::numeric(10,2) AS replay_lag_seconds
FROM pg_stat_replication
ORDER BY replay_lag_bytes DESC
```

---

# MySQL health (MySQL)

Fragmented tables, tables without a primary key, long-running queries, the statements that cost the most, and the buffer pool.

## Largest tables and their free space

Source: https://www.datarunner.app/en/templates/mysql/table-sizes

Data, index and reclaimable space per table. A large data_free is fragmentation an OPTIMIZE TABLE would recover.

```sql
SELECT CONCAT(table_schema, '.', table_name) AS table_name,
       table_rows AS estimated_rows,
       ROUND((data_length + index_length) / 1048576, 1) AS total_mb,
       ROUND(data_length / 1048576, 1) AS data_mb,
       ROUND(index_length / 1048576, 1) AS index_mb,
       ROUND(data_free / 1048576, 1) AS free_mb
FROM information_schema.tables
WHERE table_schema NOT IN ('mysql', 'information_schema', 'performance_schema', 'sys')
  AND table_type = 'BASE TABLE'
ORDER BY (data_length + index_length) DESC
LIMIT 25
```

## Tables without a primary key

Source: https://www.datarunner.app/en/templates/mysql/tables-without-pk

InnoDB builds a hidden key for these, replication row-based is slow on them, and online schema tools refuse them.

```sql
SELECT CONCAT(t.table_schema, '.', t.table_name) AS table_name,
       t.table_rows AS estimated_rows,
       t.engine
FROM information_schema.tables t
LEFT JOIN information_schema.table_constraints c
       ON c.table_schema = t.table_schema
      AND c.table_name = t.table_name
      AND c.constraint_type = 'PRIMARY KEY'
WHERE t.table_schema NOT IN ('mysql', 'information_schema', 'performance_schema', 'sys')
  AND t.table_type = 'BASE TABLE'
  AND c.constraint_name IS NULL
ORDER BY t.table_rows DESC
```

## Queries running for more than 60 seconds

Source: https://www.datarunner.app/en/templates/mysql/long-queries

Everything in the process list that has been executing for over a minute.

```sql
SELECT id AS process_id,
       user,
       host,
       db,
       command,
       time AS running_seconds,
       state,
       LEFT(info, 200) AS query
FROM information_schema.processlist
WHERE command <> 'Sleep'
  AND time > 60
  AND id <> CONNECTION_ID()
ORDER BY time DESC
```

## Statements by total time

Source: https://www.datarunner.app/en/templates/mysql/slowest-statements

Aggregated by digest: the statement shapes that cost the most across all their calls.

> Requires: performance_schema must be ON (it is by default since 5.6).

```sql
SELECT LEFT(digest_text, 160) AS statement,
       schema_name,
       count_star AS calls,
       ROUND(sum_timer_wait / 1e12, 1) AS total_seconds,
       ROUND(avg_timer_wait / 1e9, 2) AS avg_ms,
       sum_rows_examined AS rows_examined,
       sum_rows_sent AS rows_sent
FROM performance_schema.events_statements_summary_by_digest
WHERE schema_name IS NOT NULL
ORDER BY sum_timer_wait DESC
LIMIT 20
```

## Indexes never used

Source: https://www.datarunner.app/en/templates/mysql/unused-indexes

Indexes with no reads since the server started, from performance_schema. Restart resets the counters — trust it after a few days of uptime.

> Requires: performance_schema must be ON.

```sql
SELECT CONCAT(object_schema, '.', object_name) AS table_name,
       index_name
FROM performance_schema.table_io_waits_summary_by_index_usage
WHERE index_name IS NOT NULL
  AND index_name <> 'PRIMARY'
  AND count_star = 0
  AND object_schema NOT IN ('mysql', 'information_schema', 'performance_schema', 'sys')
ORDER BY object_schema, object_name
```

## Connections by command

Source: https://www.datarunner.app/en/templates/mysql/connections-by-command

Open sessions grouped by what they are doing, against max_connections.

```sql
SELECT command,
       COUNT(*) AS sessions,
       (SELECT variable_value FROM performance_schema.global_variables WHERE variable_name = 'max_connections') AS max_connections
FROM information_schema.processlist
GROUP BY command
ORDER BY sessions DESC
```

## InnoDB buffer pool hit ratio

Source: https://www.datarunner.app/en/templates/mysql/buffer-pool

Share of page reads served from memory. Below 99% on a busy server means the buffer pool is smaller than the working set.

```sql
SELECT ROUND(100 * (1 - disk.v / NULLIF(mem.v, 0)), 2) AS hit_pct,
       mem.v AS read_requests,
       disk.v AS disk_reads
FROM (SELECT CAST(variable_value AS UNSIGNED) AS v FROM performance_schema.global_status WHERE variable_name = 'Innodb_buffer_pool_read_requests') mem,
     (SELECT CAST(variable_value AS UNSIGNED) AS v FROM performance_schema.global_status WHERE variable_name = 'Innodb_buffer_pool_reads') disk
```

---

# SQL Server health (SQL Server)

Blocking, missing and unused indexes, the queries burning CPU, wait statistics and table sizes.

## Blocked sessions

Source: https://www.datarunner.app/en/templates/mssql/blocking

Requests waiting on another session, with both sides' text. Empty is healthy.

```sql
SELECT r.session_id AS blocked_session,
       r.blocking_session_id AS blocking_session,
       r.wait_type,
       r.wait_time / 1000 AS wait_seconds,
       s.login_name,
       s.program_name,
       LEFT(t.text, 200) AS blocked_query
FROM sys.dm_exec_requests r
JOIN sys.dm_exec_sessions s ON s.session_id = r.session_id
CROSS APPLY sys.dm_exec_sql_text(r.sql_handle) t
WHERE r.blocking_session_id <> 0
ORDER BY r.wait_time DESC
```

## Missing indexes the optimiser asked for

Source: https://www.datarunner.app/en/templates/mssql/missing-indexes

The engine's own suggestions, ranked by the improvement it expects. Treat the top few as candidates, not orders.

```sql
SELECT TOP 20
       d.statement AS table_name,
       d.equality_columns,
       d.inequality_columns,
       d.included_columns,
       CAST(s.avg_total_user_cost * s.avg_user_impact * (s.user_seeks + s.user_scans) AS bigint) AS improvement_measure,
       s.user_seeks + s.user_scans AS uses
FROM sys.dm_db_missing_index_details d
JOIN sys.dm_db_missing_index_groups g ON g.index_handle = d.index_handle
JOIN sys.dm_db_missing_index_group_stats s ON s.group_handle = g.index_group_handle
WHERE d.database_id = DB_ID()
ORDER BY improvement_measure DESC
```

## Indexes written to but never read

Source: https://www.datarunner.app/en/templates/mssql/unused-indexes

Non-clustered indexes with updates and no seeks, scans or lookups since the last restart.

```sql
SELECT TOP 25
       OBJECT_SCHEMA_NAME(i.object_id) + '.' + OBJECT_NAME(i.object_id) AS table_name,
       i.name AS index_name,
       u.user_updates AS writes,
       u.user_seeks + u.user_scans + u.user_lookups AS reads
FROM sys.indexes i
JOIN sys.dm_db_index_usage_stats u
       ON u.object_id = i.object_id AND u.index_id = i.index_id AND u.database_id = DB_ID()
WHERE i.type_desc = 'NONCLUSTERED'
  AND i.is_primary_key = 0
  AND i.is_unique = 0
  AND u.user_seeks + u.user_scans + u.user_lookups = 0
ORDER BY u.user_updates DESC
```

## Queries by total CPU

Source: https://www.datarunner.app/en/templates/mssql/top-cpu-queries

Cached plans ranked by worker time across all executions, to find the SQL Server queries that use the most CPU.

```sql
SELECT TOP 20
       LEFT(SUBSTRING(t.text, (s.statement_start_offset / 2) + 1,
            ((CASE s.statement_end_offset WHEN -1 THEN DATALENGTH(t.text) ELSE s.statement_end_offset END - s.statement_start_offset) / 2) + 1), 160) AS statement,
       s.execution_count AS calls,
       s.total_worker_time / 1000 AS total_cpu_ms,
       s.total_worker_time / s.execution_count / 1000 AS avg_cpu_ms,
       s.total_logical_reads AS logical_reads,
       s.last_execution_time
FROM sys.dm_exec_query_stats s
CROSS APPLY sys.dm_exec_sql_text(s.sql_handle) t
ORDER BY s.total_worker_time DESC
```

## Top waits since restart

Source: https://www.datarunner.app/en/templates/mssql/wait-stats

What the server spends its time waiting on. Filters out the benign background waits.

```sql
SELECT TOP 15
       wait_type,
       wait_time_ms / 1000 AS wait_seconds,
       waiting_tasks_count,
       CAST(100.0 * wait_time_ms / NULLIF(SUM(wait_time_ms) OVER (), 0) AS decimal(5,2)) AS pct
FROM sys.dm_os_wait_stats
WHERE wait_type NOT LIKE 'SLEEP%'
  AND wait_type NOT LIKE 'BROKER%'
  AND wait_type NOT LIKE 'XE%'
  AND wait_type NOT IN ('CLR_AUTO_EVENT','CLR_MANUAL_EVENT','LAZYWRITER_SLEEP','CHECKPOINT_QUEUE',
                        'REQUEST_FOR_DEADLOCK_SEARCH','LOGMGR_QUEUE','ONDEMAND_TASK_QUEUE',
                        'DIRTY_PAGE_POLL','HADR_FILESTREAM_IOMGR_IOCOMPLETION','SP_SERVER_DIAGNOSTICS_SLEEP',
                        'QDS_PERSIST_TASK_MAIN_LOOP_SLEEP','QDS_CLEANUP_STALE_QUERIES_TASK_MAIN_LOOP_SLEEP',
                        'WAITFOR','FT_IFTS_SCHEDULER_IDLE_WAIT','DISPATCHER_QUEUE_SEMAPHORE','SQLTRACE_INCREMENTAL_FLUSH_SLEEP')
ORDER BY wait_time_ms DESC
```

## Largest tables

Source: https://www.datarunner.app/en/templates/mssql/table-sizes

Rows and reserved space per table, from partition stats, to see which SQL Server tables take up the most disk.

```sql
SELECT TOP 25
       s.name + '.' + t.name AS table_name,
       SUM(CASE WHEN p.index_id IN (0, 1) THEN p.row_count ELSE 0 END) AS rows_count,
       SUM(p.reserved_page_count) * 8 / 1024 AS reserved_mb,
       SUM(p.used_page_count) * 8 / 1024 AS used_mb
FROM sys.dm_db_partition_stats p
JOIN sys.tables t ON t.object_id = p.object_id
JOIN sys.schemas s ON s.schema_id = t.schema_id
GROUP BY s.name, t.name
ORDER BY reserved_mb DESC
```

## Sessions by status

Source: https://www.datarunner.app/en/templates/mssql/sessions-by-status

User sessions grouped by status (running, sleeping, dormant), from sys.dm_exec_sessions. Many sleeping sessions usually mean an oversized connection pool.

```sql
SELECT status,
       COUNT(*) AS sessions
FROM sys.dm_exec_sessions
WHERE is_user_process = 1
GROUP BY status
ORDER BY sessions DESC
```