Test-CatDataSource
Opens each data source the way a test would, proves it answers, and returns one result per data source — with the driver's own error when it does not.
Synopsis
Test-CatDataSource [[-Name] <string>] [-DataSource <DataSourceDefinition[]>]
Parameters
| Parameter | Type | Position | Default | Meaning |
|---|---|---|---|---|
-Name |
string | 0 | none | Name of a data source of the open project (exact name, as in the project file). Omit it to test every data source of the project. |
-DataSource |
DataSourceDefinition[] | none | Data source definitions to test, from the pipeline or by name. Each one is tested as it is, whether or not it is part of the project. |
With neither -Name nor -DataSource, every data source of the project is tested, in the order of the project.
What it does
For each tested data source it 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. |
The statement has a fixed timeout of 30 seconds; opening the connection is bounded by the driver’s own connect timeout from the connection string, and there are no retries. A Databricks SQL warehouse or cluster that was stopped starts on the first query and can take minutes: the result says it may still be starting, so test again a few minutes later.
Output
One DataSourceTestResult per data source, written as each arrives:
| Property | Meaning |
|---|---|
Name |
The data source name as written in the project; (unnamed) when there is none. |
Provider |
The provider and version, as written, for example SqlServer@2. |
Success |
$true when the data source answered. |
Message |
What was proven (Connected and read one row, File exists: …), or the error. |
Duration |
A TimeSpan. |
Errors
A failed test is a result with Success set to $false, not an error of the cmdlet, so Test-CatDataSource | Where-Object { -not $_.Success } lists what is broken. The cmdlet itself fails when nothing is open (There is no open CAT project. Open a project first.) and for an unknown name (The provided data source name '…' was not found. Only data sources with these names are available: …).
Examples
Open-CatProject -Path 'D:\Testing\Aero.cat.yaml'
# all data sources
Test-CatDataSource
# one
Test-CatDataSource AERO_PROD
# only the broken ones
Test-CatDataSource | Where-Object { -not $_.Success } | Format-Table Name, Message
# some of them: the parentheses make PowerShell hand over the data sources one by one
(Get-CatDataSource) | Where-Object Name -like 'AERO*' | Test-CatDataSource
# all of them through the pipeline
Get-CatDataSource | Test-CatDataSource
Related
- Introduction — session model, logging, errors, sign-in.
Invoke-CatCommand— run a statement of your own once the data source answers.Get-CatDataSource— the names to use.- Providers — what each provider accepts.