ping
Opens each data source of the project the way a test would, proves it answers, and says so in one line — with the driver's own error when it does not.
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. |
-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.
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 — conventions, sign-in, exit codes.
exec— run a statement of your own against a data source, once it answers.- Data sources and Providers — what each provider accepts.