🔌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.
Configuring a PostgreSQL connection
Follow the steps described in Add a connector, choose PostgreSQL
and fill in the connection information
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 thenSAVE
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
To create a dataset from PostgreSQL, refer to this dedicated guide to:
Select a
Database
Select a
Schema
Select
Table
orViews
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.
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
andPassword
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.
Last updated
Was this helpful?