---
title: "ping"
description: "catcli ping — test that one data source of the project, or all of them, answer, without running any test."
url: "https://docs.justcat.it/reference/cat-cli/ping/"
---
# ping


## Synopsis

```
catcli ping [-d <name>] [-p <path>] [-l <level>] [-q] [--format <form>]
```

## Options

| Short | Long | Value | Meaning |
|-------|------|-------|---------|
| `-d` | `--dataSource` | name | Name of one data source defined in the project. Omit it to test every data source, in the order of the project. |
| `-p` | `--project` | path | Project file, or a directory with exactly one `*.cat.yaml`. Default: the current directory. |
| `-l` | `--loggingLevel` | level | `None` (default), `Error`, `Information`, `Debug`, … — see [Logging](https://docs.justcat.it/reference/cat-cli/introduction/#logging "Logging"). |
| `-q` | `--quiet` | | Hide the "working offline" notice. |
|  | `--format` | `table` \| `csv` | Output form. Default: `table` at a terminal, `csv` when standard output is redirected (a pipe or a file). |

## What it does

Opens the project, and for each tested data source does what the data source's provider does when a test uses it, with a harmless statement in place of a real one. What counts as *answering* depends on the provider:

| Provider | What the test proves |
|----------|----------------------|
| SQL Server, PostgreSQL, MySQL, ClickHouse, Snowflake, Teradata, Databricks, Oracle, DuckDB@1 | Connects, runs a one-row statement (`SELECT 'cat' AS cat`, with `FROM DUAL` for Oracle) and reads the row. |
| DAX and Power BI providers (Windows) | Connects and reads the row of `EVALUATE ROW("cat", "cat")`. |
| ODBC, and the OleDb CSV and Excel providers (Windows) | Opens the connection and stops; no statement is run. |
| Excel@1, YAML | The file exists. The file is not read. |
| Csv@1 | The folder exists. |
| Excel@2 | The workbook file exists. It is not loaded — that is what a run does, and it can take seconds on a large file. |
| Csv@2 | At least one file matches the connection string. A pattern that matches nothing is caught only when no other entry of the list matches either. |

Nothing is loaded and no test runs. The statement has a fixed timeout of 30 seconds. Opening the connection is not covered by that number: it is bounded by the driver's own connect timeout, as written in the connection string, so an interactive Microsoft Entra sign-in has all the time it needs. There are no retries — a verdict is one attempt.

A misspelled host, a wrong database, a wrong password or a missing file fail within a second or two. A host that exists but does not answer waits for the driver's connect timeout. A Databricks SQL warehouse or cluster that was stopped starts on the first query and can take minutes; the test does not wait for that, and its verdict says the warehouse may still be starting. Test again a few minutes later. Press `Ctrl+C` to give up on a test that takes too long.

`%PLACEHOLDER%` values in a connection string are expanded as in a run. A placeholder that is not set reaches the driver as literal text, and the driver's error is the verdict.

## Output

**At a terminal** (or with `--format table`): one line per data source, printed as each verdict arrives — the verdict, the name, the provider, the time in seconds, and the message:

```
OK    AeroDWH  SqlServer@2  0.4 s  Connected and read one row
FAIL  Claims   Excel@2      0.0 s  File not found: /home/x/Aero/Claims.xlsx
```

**Through a pipe or a file** (or with `--format csv`): standard output carries only CSV, a header row and one row per data source:

```
Verdict,Name,Provider,DurationSeconds,Message
OK,AeroDWH,SqlServer@2,0.4,Connected and read one row
FAIL,Claims,Excel@2,0.0,File not found: /home/x/Aero/Claims.xlsx
```

## Exit code

`0` when every tested data source passed. `12` when at least one failed. `1` when the data source name does not exist — the message is printed on standard error, in both output forms — or the project could not be opened. `2`–`8` from the sign-in and plan check — see [Exit codes](https://docs.justcat.it/reference/cat-cli/introduction/#exit-codes "Exit codes").

## Examples

```
# test every data source of the project in the current directory
catcli ping

# test one
catcli ping -d AeroDWH

# a script that stops when a data source is down
catcli ping --format csv > ping.csv || echo "a data source is down"
```

## Related

- [Introduction](https://docs.justcat.it/reference/cat-cli/introduction/ "Introduction") — conventions, sign-in, exit codes.
- [`exec`](https://docs.justcat.it/reference/cat-cli/exec/ "exec") — run a statement of your own against a data source, once it answers.
- [Data sources](https://docs.justcat.it/reference/data-sources/ "Data sources") and [Providers](https://docs.justcat.it/reference/data-sources/providers/ "Providers") — what each provider accepts.