🔌Add a PostgreSQL connection

How to configure a postgreSQL connection in Toucan.

Connector Features

You can use the Toucan PostgreSQL connector to connect to a PostgreSQL cluster with a basic authentication and access tables or views with a SQL query or by using our no-code form .

With a PostgreSQL connection, you can fetch data from your PostgreSQL database to fill your charts and dashboards.

Changelog December 23 - this connector is NativeSQL compatible

April 24 - This connector supports materialized views November 2024 - This connector supports hybrid pipelines

July 25 - This data connector is supported for connection and NativeSQL by our new Data Execution system

Configuring a PostgreSQL connection

Follow the steps described in Add a connector, choose PostgreSQL and fill in the connection information

Field	Format / Type	Description	Example
Name (mandatory)	String	Use it to identify your connection	MyPostGreSQLConnection
Host (mandatory)	String	The domain name or IP address of your database server	"db.example.com" or "192.168.1.100"
Port (mandatory)	Integer	The listening port of your database server	3306
User (mandatory)	String	Your login username	myuser
Password (mandatory)	String	Your login password	secretpassword123
Default database (optional)	String	The default database to connect to	postgres
Charset (optional)	String	Character encoding for the connection	"utf8mb4" (default)
Connect Timeout (optional)	Integer	Connection timeout in seconds	30
Retry Policy (optional)	Boolean	Boolean allows to configure a retry policy if the connection is flaky. max attempts: maximum number of retries before giving up max_delay: in seconds, above the connection is dropped wait_time: time in seconds between each retry
Slow Queries' Cache Expiration Time (optional)	Integer	Slow queries' cache expiration time in seconds
Include materialized views	Boolean	Show or hide materialized views when you are connected to your Postgres cluster	N/A

• Click on the TEST CONNECTION button then SAVE the connection

After successfully configuring the connector, you will be able to find it in the Connector section of the DataHub "Datasource" tab

Create a dataset from a PostgreSQL connection

This data connector is supported in simple and code/SQL mode with:

• our current Data Execution system

• new Data Execution system

To create a dataset from PostgreSQL, refer to this dedicated guide to:

• Select a Database

• Select a Schema

• Select Table or Views

• Keep the columns you need

After selecting data from your connector you will be able to create a dataset thanks to YouPrep using the selection as "source step".

How to troubleshoot a PostgreSQL connection

Generally ensure all mandatory fields (Name, Host, Port, User, Password) are filled.

Test connection modal

Use the Test connection modal to troubleshoot a misconfiguration

• If the modal displays a title Cannot establish connection with a warning icon in front of a line, check this specific connection step

• Inspect the modal error message for details—typically indicates network issues, authentication errors, or database unavailability.

Network access

If the modal displays a warning icon on Host resolved line and a displayed message:

failed to lookup address information: Name or service not known

[Errno -2] Name or service not known

• Verify that the Host (IP or DNS) is reachable from Toucan IP and is not blocked by firewalls.

Check our IP for our Current Data Execution System and New Data Execution System

If the modal displays a warning icon on Port opened line and a displayed message:

warning icon on port opened Connection refused (os error 111)

• Check that the Port (default is 5432) matches the PostgreSQL server’s configuration and is open.

If encountering SSL-related errors, check server SSL configuration

Authentication

If the modal displays a warning icon on Authenticated to PostgreSQL line and the message displayed is:

error returned from database: password authentication failed for user or

(psycopg.OperationalError) connection failed: connection to server at "{{your_server_ip}}", port 28561 failed: FATAL: password authentication failed for user "{{your_user}}" connection to server at "{{your_server_ip}}", port {{your_server_port}} failed: FATAL: password authentication failed for user "{{your_user}}"

• Confirm User and Password are valid and have been granted connect permissions to the target database.

Other options

Default database

If the modal displays a warning icon on Authenticated to PostgreSQL line and the message displayed is:

error returned from database: database "{{default_database}}" does not exist or

(psycopg.OperationalError) connection failed: connection to server at "{{your_server_ip}}", port {{your_server_port}} failed: FATAL: database "{{database}}" does not exist

• Check the default database exists or that your user has acceess to it.

Charset

• If specified, make sure Charset is supported by the database instance.

Connect timeout

• Adjust Connect Timeout if timeouts occur, especially in remote or slow network situations.

Advanced troubleshooting

• Review logs on PostgreSQL server for more detailed error information.

• For persistent issues, attempt to connect using CLI with the same parameters to isolate issues.