Connect from old clients

In most cases, copying a connection string from the Neon Dashboard and using it in your project should work as is. However, with older clients and some native PostgreSQL clients, you may receive the following error:

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

In most cases, this happens if your client library or application does not support the SNI (Server Name Indication) mechanism in TLS. See Details for more context and Workarounds for a list of ways to work around this issue.

Details

To route incoming connections, we use different domain names for different compute endpoints. For example, to connect to the compute endpoint ep-mute-recipe-239816, we ask you to connect to ep-mute-recipe-239816.us-east-2.aws.neon.tech. However, the PostgreSQL wire protocol does not transfer the server domain name, so we rely on the SNI (Server Name Indication) extension of the TLS protocol, which allows a client to indicate what domain name it is attempting to connect to. This is the same mechanism that allows hosting several https-enabled websites on a single IP address. SNI support was added to the libpq (an official PostgreSQL client library) in version 14, released in September 2021. All libpq-based clients like Python's psycopg2 and Ruby's ruby-pg should work if the system libpq version is >= 14.

Workarounds

If you encounter a Project ID is not specified error and a library or application upgrade does not help, we provide several fallback options. When SNI domain name information is missing, we need to obtain this information through other means.

A. Pass the endpoint ID as an option

We support a special connection option named project, which you can set to identify the compute endpoint you are connecting to. More specifically, you can set pass options=project%3Dmy-endpoint-123456 as a GET parameter in the connection string. The %3D is a URL-encoded =.

For example, instead of the following connection string:

postgres://<user>:<password>@my-endpoint-123456.us-east-2.aws.neon.tech/main

you can use that one:

postgres://<user>:<password>@my-endpoint-123456.us-east-2.aws.neon.tech/main?options=project%3Dmy-endpoint-123456

This option is expected to work if your application or library permits it to be set. But not all of them do, especially in the case of GUI applications.

B. Use libpq key=value syntax in the database field

If your application or client is libpq-based and you can't easily upgrade the library, such as when the library is compiled inside of a pre-built application, you can use the fact that libpq permits adding options to the database name. So instead of only the database name, you can specify:

dbname=main options=project=<endpoint_id>

This workaround is expected to work with all libpq-based applications.

C. Set verify-full for golang-based clients

If your application or service uses golang PostgreSQL clients like pgx and lib/pg, you can set sslmode=verify-full, which causes SNI information to be sent. Most likely, this behavior is not intentional but happens inadvertently due to the golang's TLS library API design.

D. Specify the endpoint ID in the password field

You can specify the endpoint ID in the password field as a last resort. So, instead of your actual password, you can define a string consisting of the endpoint and the password. For example:

project=ep-mute-recipe-239816;<password>

This approach is the least secure of all the recommended workarounds. It causes the authentication method to be downgraded from scram-sha-256 (never transfers a plain text password) to password (transfers a plain text password) on the fly. The connection is still over a TLS-encrypted connection, so the amount of security is the same as with https websites. However, we intend deprecate this option when most libraries and applications adopt SNI.

Applications

Libraries

libpq-based clients from this list https://wiki.postgresql.org/wiki/List_of_drivers are expected to work with the system libpq, version >= 14.

Native client libraries:

Need help?

Send a request to support@neon.tech, or join the Neon community forum.