Testing Connectors

Once your project is ready for local testing, use the fivetran debug command to test and troubleshoot the connection's behavior with the source's actual data. The command generates a local warehouse.db file, a DuckDB representation of the data delivered by the connection to the destination.

See our CLI Commands documentation for more details about the fivetran debug command.

Working with warehouse.db

When you run fivetran debug, the local tester saves the data sent by your connector code into a DuckDB database file located at:

<project directory>/files/warehouse.db

You can use this file to inspect and validate your connector output during development.

Resetting the local debug environment

The local tester supports basic data operations. Schema-altering changes, such as modifying table definitions, are not fully supported in incremental debug runs. If you encounter failures after making schema changes, reset the local debug environment by running the following command from the root project folder:

fivetran reset

This command:

Deletes the existing warehouse.db
Deletes the local state.json file
Clears the local debug environment

After reset, run fivetran debug again to perform a clean test of your updated connector code. If the error persists, it is likely caused by an issue in your connector code.

Connecting to DuckDB

The Fivetran Local Tester saves the data synced locally by your connector code into a DuckDB warehouse.db file stored at the <project directory>/files/warehouse.db path:

warehouse.db path

Using DuckDB CLI

Install DuckDB CLI.
Run DuckDB CLI:
```
duckdb files/warehouse.db
```
Once running, you can see the tables and their schema as well as query the warehouse with SQL:
```
.tables
.schema
SELECT * FROM default_schema.hello_world;
```
To stop DuckDB, run the following command:
```
.exit
```

Launching DuckDB UI

Navigate to your project root directory.
Start the DuckDB UI by running:
```
duckdb files/warehouse.db -ui
```
This starts a local HTTP server and prints a URL, such as http://localhost:4213/. The DuckDB UI opens automatically in your default browser.
In the UI:
- Expand Attached databases to browse schemas and tables created during your local fivetran debug run.
- Create notebooks and execute SQL queries interactively to inspect your connector's debug output. Here's a sample screenshot of DuckDB UI connected to a warehouse.db file:
To stop DuckDB UI, close the browser tab and interrupt the terminal process by pressing Ctrl + C or type .exit.

For more information about the UI extension and advanced configuration options, see the official DuckDB UI extension documentation.

Using Harlequin CLI

Install the Harlequin CLI:
```
pip install harlequin
```
Run Harlequin with your warehouse.db with:
```
harlequin "path/to/warehouse.db"
```
Replace path/to/warehouse.db with the path to your warehouse.db file.
Once running, you can see the data catalog and their schema as well as query the warehouse with SQL:
```
SELECT * FROM tester.hello;
```
Here is a sample screenshot of Harlequin connected to a warehouse.db file:
To stop Harlequin, run the following command:
```
Ctrl + q
```

Using DBeaver

Install DBeaver.
To connect to a database, in the DBeaver menu go to Database > New Database Connection and select DuckDB.
Click Open to navigate to and select the warehouse.db file created by running fivetran debug.
Click Connection details (name, type, ...) if you wish to provide a custom name to the connection.
DBeaver may need to download updated drivers, then show that it's connected to the local warehouse.db file, and enable you to explore it using regular SQL. Your tables will be located in the tester schema of the warehouse catalog.

`fivetran debug` issue with open connection

If you use fivetran debug while a connection with warehouse.db is already open, the command doesn't work until the connection is closed. The command fails with an error message that starts with:

IO Error: Could not set lock on file "/Users/john.smith/connector/files/warehouse.db": Conflicting lock is held in...

This occurs because DuckDB does not support concurrent connections to the same database file, as explained in their concurrency documentation. To resolve this issue, close the connection in DBeaver or DuckDB UI before running fivetran debug again.