Connect a GUI application

This topic describes how to connect to a Neon database from a GUI application or IDE. Most GUI applications and IDEs that support connecting to a Postgres database also support connecting to Neon.

Gather your connection details

The following details are typically required when configuring a connection:

hostname
port
database name
role (user)
password

You can gather these details from the Connection Details widget on the Neon Dashboard. Select a branch, a role, and the database you want to connect to. A connection string is constructed for you.

Connection details widget

note

Neon supports pooled and direct connections to the database. Use a pooled connection string if your application uses a high number of concurrent connections. For more information, see Connection pooling.

The connection string includes the role, password, hostname, and database name.

postgres://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname
           ^              ^                                               ^
           |- <role>      |- <hostname>                                   |- <database>

role name: alex
hostname: ep-cool-darkness-123456.us-east-2.aws.neon.tech
database name: dbname

Neon uses the default Postgres port, 5432.

Connect to the database

In the GUI application or IDE, enter the connection details into the appropriate fields and connect. Some applications permit specifying a connection string while others require entering connection details into separate fields. In the pgAdmin example below, connection details are entered into separate fields, and clicking Save establishes the database connection.

Some Java-based tools that use the pgJDBC driver for connecting to Postgres, such as DBeaver, DataGrip, and CLion, do not support including a role name and password in a database connection string or URL field. When you find that a connection string is not accepted, try entering the database name, role, and password values in the appropriate fields in the tool's connection UI when configuring a connection to Neon. For example, the DBeaver client has a URL field, but connecting to Neon requires specifying the connection details as shown:

DBeaver connection

Tested GUI applications and IDEs

Connections from the GUI applications and IDEs in the table below have been tested with Neon.

note

Some applications require an Server Name Indication (SNI) workaround. Neon uses compute domain names to route incoming connections. However, the Postgres wire protocol does not transfer the server domain name, so Neon relies on the Server Name Indication (SNI) extension of the TLS protocol to do this. Not all application clients support SNI. In these cases, a workaround is required. For more information, see Connection errors.

Application or IDE	Notes
Appsmith
AskYourDatabase
AWS Database Migration Service (DMS)	Use SNI workaround D. Use a `$` character as a separator between the `endpoint` option and password. For example: `endpoint=<endpoint_id>$<password>`. Also, you must set Secure Socket Layer (SSL) mode to `require`. See Migrate with AWS DMS.
Azure Data Studio	Requires the PostgreSQL extension and SNI workaround D
Beekeeper Studio	Requires the Enable SSL option
CLion
Datagran	Requires SNI workaround D connection workaround
DataGrip
DBeaver
dbForge
DbVisualizer
DronaHQ hosted cloud version	Requires selecting Connect using SSL when creating a connector
Forest Admin	The database requires at least one table
Grafana	Requires `sslmode=verify-full`. See SNI workaround C.
Google Looker Studio	Requires Enable SSL and uploading the PEM-encoded ISRG Root X1 public root certificate issued by Let's Encrypt, which you can find here: isrgrootx1.pem. See Connect to Looker Studio, in the Neon Community forum.
Google Cloud Platform (GCP)	May require uploading the PEM-encoded ISRG Root X1 public root certificate issued by Let's Encrypt, which you can find here: isrgrootx1.pem.
Google Colab	See Use Google Colab with Neon.
ILLA Cloud
Luna Modeler	Requires enabling the SSL/TLS option
Metabase
Postico	SNI support since v1.5.21. For older versions, use SNI workaround B. Postico's keep-connection-alive mechanism, enabled by default, may prevent your compute from scaling to zero.
PostgreSQL VS Code Extension by Chris Kolkman
pgAdmin 4
Retool
Tableau	Use the PostgreSQL connector with the Require SSL option selected
TablePlus	SNI support on macOS since build 436, and on Windows since build 202. No SNI support on Linux currently. For older versions, use SNI workaround B.
Segment	Requires SNI workaround D
Skyvia	Requires setting the SSL Mode option to `Require`, and SSL TLS Protocol to 1.2. The other SSL fields are not required for SSL Mode: `Require`.

Connection issues

Applications that use older client libraries or drivers that do not support Server Name Indication (SNI) may not permit connecting to Neon. If you encounter the following error, refer to Connection errors for possible workarounds.

ERROR: The endpoint ID is not specified. Either upgrade the Postgres client library (libpq) for SNI support or pass the endpoint ID (the first part of the domain name) as a parameter: '&options=endpoint%3D'. See [https://neon.tech/sni](https://neon.tech/sni) for more information.

Need help?

Join our Discord Server to ask questions or see what others are doing with Neon. Users on paid plans can open a support ticket from the console. For more detail, see Getting Support.