Local Testing

The Connector SDK's debug tool, Fivetran Local Tester, emulates Fivetran’s core locally, allowing you to validate your connector’s behavior, inspect output data, and catch issues early, before deploying or debugging production syncs. Run your connector locally against real source data, verify the results, and refine your implementation. The connector runs in the same process as the fivetran debug command, and its data goes to a local DuckDB file. To write the data to an Apache Iceberg catalog instead, see Write to an Iceberg catalog.

Run your connector locally

Run a local debug session from a terminal or directly from your IDE.

Option 1: In the terminal, navigate to the directory containing your connector.py file and run:
```
fivetran debug --configuration configuration.json
```
Configuration is required. If configuration.json is in your project folder, the CLI detects it automatically, and you can omit the --configuration flag. If your connector does not use configuration, pass an empty configuration.json file. For more information, see Working with configuration.json.
See our CLI Commands documentation for more details about the fivetran debug command.

Option 2: If you prefer to run debug from your IDE, include the following snippet in connector.py:

if __name__ == "__main__":
 # Open the configuration.json file and load its contents into a dictionary.
 with open("configuration.json", "r") as f:
     configuration = json.load(f)
 # Adding this code to your `connector.py` allows you to test your connector by running your file directly from your IDE.
 connector.debug(configuration=configuration)

For a walkthrough of testing your connector locally, see the Test the connector locally step in our Complete Walkthrough.

What to expect

A successful debug run produces output showing sync statistics — upserts, updates, deletes, truncates, schema changes, and checkpoints.

After a successful run, the Local Tester generates a local warehouse.db file, a DuckDB representation of the data delivered by the connection to the destination at <project directory>/files/warehouse.db. You can use this file to inspect and validate your connector output during development.

warehouse.db path

Expand to see an example debug log

The test also outputs a log in the terminal where you ran the command or the built-in terminal in your IDE. The final lines of the debug log look similar to this example:

21:21:08.312 INFO     ⚡ sdk       Final checkpoint: committing any remaining operations
21:21:08.316 INFO     ⚡ sdk       SYNC SUCCEEDED — total elapsed 00:00:00.090
Operation       | Counts
----------------+------------
Upserts         | 2
Updates         | 0
Deletes         | 0
Truncates       | 0
Schema changes  | 2
Checkpoints     | 2
File uploads    | 0

21:21:08.316 INFO     ⚡ sdk       debug results in duckdb view using `duckdb -ui files/warehouse.db`

During a local run, the op.error() and op.warning() methods print messages to the terminal instead of the Fivetran dashboard.

For more examples of Local Tester logs, see the Connector SDK technical reference.

Inspect the warehouse.db file

After running fivetran debug, validate that your connector is working correctly by inspecting the generated data in warehouse.db.

Where your tables appear depends on whether your connector declares schemas. If you omit the schema key, the tables appear in the tester schema. If you declare schemas, the tables appear in tester_<schema> with Fivetran naming or in <schema> with source naming. For example, a table in the sales schema appears in tester_sales with Fivetran naming. For more information, see Declaring multiple schemas.

You can open warehouse.db using any of the following tools or another tool of your choice.

DuckDB CLI

Expand to see steps

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
```

DuckDB UI

Expand to see steps

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.

DBeaver

Expand to see steps

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.

DuckDB allows only one process to connect to warehouse.db at a time. Before running fivetran debug again, close your DBeaver connection to the file.

Harlequin CLI

Expand to see steps

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
```

If tables are not created in warehouse.db after a debug run, your connector schema may include DuckDB reserved keywords such as order, group, or desc. See Local Debug Runs Do Not Create Tables or Persist state.json for steps to resolve this.

Iterate and debug

Local testing is an iterative process:

Run fivetran debug.
Inspect output in warehouse.db.
Update your connector code.
Optionally, reset the local debug environment with fivetran reset.
Re-run and validate changes.

Reset the local debug environment when needed

Most changes to your schema work between debug runs, because the local tester changes warehouse.db to fit them:

A new column is added to the table, and the rows that are already there have no value for it.
A column whose type has to change, for example an integer that now receives strings, is changed to the new type, and its values are converted.
A changed primary key rewrites the table, if its rows fit the new key. If they do not (a key that would be duplicated, or null), the run fails with a message such as Primary key change for table tester.my_table would create duplicate rows under the new primary key ['name'], and warehouse.db is left as it was.

Reset the local debug environment to start from scratch, for example to test the initial sync again, or after a failure like the last one. Run 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.

Testing tips

Use fivetran debug with real source data to test and troubleshoot your connector's behavior.
Run fivetran debug on multiple small samples of your data to fully test your connector's logic. The Local Tester is slower than production because it runs entirely on your local machine.
Deploy to Fivetran and run end-to-end tests before moving to larger or production-sized syncs.
State management and configuration can be used to control exactly what is tested with each run.
Use fivetran reset to reset the locally saved cursor and warehouse.db files, allowing you to re-run fivetran debug from scratch. It simulates a historical sync.

Next steps

Once you have deployed your connector to Fivetran, potential next steps include:

Profile performance and identify bottlenecks
Optimize memory usage