Connect to Neon securely

Neon requires that all connections use SSL/TLS encryption to ensure that data sent over the Internet cannot be viewed or manipulated by third parties. Neon rejects connections that do not use SSL/TLS, behaving in the same way as standalone Postgres with only hostssl records in a pg_hba.conf configuration file.

However, there are different levels of protection when using SSL/TLS encryption, which you can configure by appending an sslmode parameter to your connection string.

Connection modes

When connecting to Neon or any Postgres database, the sslmode parameter setting determines the security of the connection. You can append the sslmode parameter to your Neon connection string as shown:

postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=verify-full

Neon supports the following sslmode settings, in order of least to most secure.

The choice of which mode to use depends on the specific security requirements of the application and the level of risk that you are willing to tolerate. Neon recommends that you always use verify-full mode, which ensures the highest level of security and protects against a wide range of attacks including man-in-the-middle attacks. The following sections describe how to configure connections using verify-full mode.

The required configuration for your connection depends on the client you are using.

Connect from the psql client

To connect from the psql command-line client with sslmode=verify-full, provide the path to your system root certificates by setting the PGSSLROOTCERT variable to the location of your operating system's root certificates. You can set this environment variable in your shell, typically bash or similar, using the export command. For example, if your root certificate is at /path/to/root.crt, you would set the variable like so:

export PGSSLROOTCERT="/path/to/your/root.crt"

Refer to Location of system root certificates below to find the path to system root certificates for your operating system.

Connect from other clients

If the client application uses a popular Postgres client library, such as psycopg2 for Python or JDBC for Java, the library typically provides built-in support for SSL/TLS encryption and verification, allowing you to configure an sslmode setting in the connection parameters. For example:

import psycopg2

conn = psycopg2.connect(
    dbname='dbname',
    user='alex',
    password='AbC123dEf',
    host='ep-cool-darkness-123456.us-east-2.aws.neon.tech',
    port='5432',
    sslmode='verify-full',
    sslrootcert='/path/to/your/root.crt'
)

However, if your client application uses a non-standard Postgres client, SSL/TLS may not be enabled by default. In this case, you must manually configure the client to use SSL/TLS and specify an sslmode configuration. Refer to the client or the client's driver documentation for how to configure the path to your operating system's root certificates.

Location of system root certificates

Neon uses the public ISRG Root X1 certificate issued by Let’s Encrypt. You can find the PEM-encoded certificate here: isrgrootx1.pem. Typically, you do not need to download this file directly, as it is usually available in a root store on your operating system. A root store is a collection of pre-downloaded root certificates from various Certificate Authorities (CAs). These are highly trusted CAs, and their certificates are typically shipped with operating systems and some applications.

The location of the root store varies by operating system or distribution. Here are some locations where you might find the required root certificates on popular operating systems:

• Debian, Ubuntu, Gentoo, etc.

  /etc/ssl/certs/ca-certificates.crt

• CentOS, Fedora, RedHat

  /etc/pki/tls/certs/ca-bundle.crt

• OpenSUSE

  /etc/ssl/ca-bundle.pem

• Alpine Linux

  /etc/ssl/cert.pem

• Android

  /system/etc/security/cacerts

• macOS:

  /etc/ssl/cert.pem

• Windows

  Windows does not provide a file containing the CA roots that can be used by your driver. However, many popular programming languages used on Windows like C#, Java, or Go do not require the CA root path to be specified and will use the Windows internal system roots by default.

  However, if you are using a language that requires specifying the CA root path, such as C or PHP, you can obtain a bundle of root certificates from the Mozilla CA Certificate program provided by the Curl project. You can download the bundle at https://curl.se/docs/caextract.html. After downloading the file, you will need to configure your driver to point to the bundle.

The system root certificate locations listed above may differ depending on the version, distribution, and configuration of your operating system. If you do not find the root certificates in these locations, refer to your operating system documentation.