-
Notifications
You must be signed in to change notification settings - Fork 251
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #3277 from EnterpriseDB/release/2022-19-21
Release: 2022-19-21
- Loading branch information
Showing
9 changed files
with
242 additions
and
179 deletions.
There are no files selected for viewing
146 changes: 146 additions & 0 deletions
146
...l/release/using_cluster/02_connecting_your_cluster/connecting_from_a_client.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,146 @@ | ||
| --- | ||
| title: Connecting from a client app | ||
| --- | ||
|
|
||
| You can connect to your cluster using the client of your choice including: | ||
| - [`psql`](http://postgresguide.com/utilities/psql.html) — terminal-based client for Postgres | ||
| - other common database drivers | ||
| - pgAdmin — desktop or web UI client to inspect, monitor, manage, and query your cluster's databases | ||
|
|
||
|
|
||
| ## Recommended settings for SSL mode | ||
|
|
||
| Different clients can have different default TLS/SSL modes (sslmode). For example, `psql` defaults to `prefer`, which means the client will attempt to establish a TLS connection but fall back to non-TLS if the server does not support it. In the `psql` example provided by EDB in the **Quick Connect** field, `sslmode` is explicitly set to `require`, which means the client will attempt a TLS connection and fail if the connection to the server can't be encrypted. | ||
|
|
||
| For public connections and in most environments, EDB recommends setting `sslmode` to `verify-full`. This setting ensures that you connect to the server you specified and that the connection is encrypted. | ||
|
|
||
| BigAnimal generates certificates with LetsEncrypt, a widely trusted certificate authority. Your client machine might already have a bundled CA certificate for LetsEncrypt, for example, at `/etc/ssl/certs/ca-certificates.crt` or `/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem`. If it doesn't, your client machine needs a [CA certificate for Let's Encrypt](https://letsencrypt.org/certificates/). Once the CA certificate is in place on your client machine, configure the `sslrootcert` parameter to its location and set the `sslmode` parameter to `verify-full` to verify the certificate to fully validate the connection. | ||
|
|
||
| To view the encryption protocol being used for communication, [connect to the cluster using `psql`](#connect-to-your-cluster-using-psql) and use the `conninfo` meta-command. In the case of BigAnimal, TLS (v1.2+) is supported: | ||
|
|
||
| ``` | ||
| edb_admin=> \conninfo | ||
| You are connected to database "edb_admin" as user "edb_admin" on host "xxxxxxxxx.xxxxx.biganimal.io" at port "5432". | ||
| SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off) | ||
| ``` | ||
|
|
||
| ## Connect to your cluster using `psql` or `edb-psql` | ||
|
|
||
| !!!note | ||
| When connecting to a EDB Postgres Advanced Server database, use `edb-psql`. `edb-psql` is a symbolic link to a binary called `psql`, a modified version of the PostgreSQL community `psql`, with added support for EDB Postgres Advanced Server features. | ||
|
|
||
| 1. Sign in to the [BigAnimal](https://portal.biganimal.com) portal. | ||
|
|
||
| 2. Go to the [Clusters](https://portal.biganimal.com/clusters) page. | ||
|
|
||
| 3. Select the name of your cluster. | ||
|
|
||
| 4. On the **Overview** tab, select the copy icon to the right of the **Quick Connect** field to copy the command for connecting to your cluster using `psql` to your clipboard. `psql` prompts for the edb_admin user password you selected when you created the cluster. | ||
|
|
||
| 5. Paste the command in your terminal. | ||
|
|
||
| ## Connect to your cluster using common database drivers | ||
|
|
||
| 1. Sign in to the [BigAnimal](https://portal.biganimal.com) portal. | ||
|
|
||
| 2. Go to the [Clusters](https://portal.biganimal.com/clusters) page. | ||
|
|
||
| 3. Select the name of your cluster. | ||
|
|
||
| 4. Select the **Connect** tab. You can review and copy all the relevant information you need from this screen except for the edb_admin user password. | ||
|
|
||
| Connection string examples for common database drivers using the recommended setting for SSL mode (consult the client driver documentation for more information): | ||
|
|
||
| - #### libpq (psql or edb-psql) | ||
|
|
||
| ``` | ||
| psql -W "postgres://[email protected]:5432/edb_admin?sslmode=verify-full&sslrootcert=/usr/share/ca-certificates/ca-cert_name.pem" | ||
| ``` | ||
|
|
||
| - #### JDBC for Java | ||
|
|
||
| ``` | ||
| jdbc:postgresql://xxxxxxxxx.xxxxx.biganimal.io:5432/edb_admin?&sslrootcert=/usr/share/ca-certificates/ca-cert_name.pem&sslmode=verify-full?user=edb_admin&password=$PWD | ||
| ``` | ||
|
|
||
| - #### Npgsql for DotNet Core | ||
|
|
||
| ``` | ||
| Host=xxxxxxxxx.xxxxx.biganimal.io;Port=5432;Username=edb_admin;Password=$PWD;Database=edb_admin;SslRootCert=/usr/share/ca-certificates/ca-cert_name.pem;SslMode=verify-full | ||
| ``` | ||
|
|
||
| - #### ODBC for Windows | ||
|
|
||
| ``` | ||
| Driver={PostgreSQL};Server=xxxxxxxxx.xxxxx.biganimal.io;Port=5432;Database=myDataBase;Uid=edb_admin;Pwd=$PWD;sslrootcert=C:\\ssl\\ca-certificate.pem;sslmode=verify-full; | ||
| ``` | ||
|
|
||
|
|
||
|
|
||
| ## Connect to your cluster using pgAdmin | ||
|
|
||
| To connect to your BigAnimal cluster from [pgAdmin](https://www.pgadmin.org/docs/), you need to enter your cluster values into pgAdmin. Keep BigAnimal and pgAdmin open to copy and paste the values. | ||
|
|
||
| Navigate to the location of the values: | ||
|
|
||
| 1. Sign in to the [BigAnimal](https://portal.biganimal.com) portal. | ||
|
|
||
| 1. Go to the [Clusters](https://portal.biganimal.com/clusters) page. | ||
|
|
||
| 1. Select the cluster you want to connect to. | ||
|
|
||
| 1. Select the **Connect** tab. | ||
|
|
||
| Enter the values in pgAdmin: | ||
|
|
||
| 1. Open pgAdmin. | ||
|
|
||
| 1. In the **Quick Links** panel, select **Add New Server**. | ||
|
|
||
| 1. In the Create-Server dialog box, under the **General** tab, enter a server name in the **Name** field. | ||
|
|
||
| 1. Select the **Connection** tab. | ||
|
|
||
| 1. Copy the corresponding values from BigAnimal and paste them into pgAdmin. | ||
|
|
||
| | BigAnimal field | pgAdmin field | Example value | | ||
| |-----------------|-------------------|---------------| | ||
| | Host | Host name/address | p-n85scw2ies.fcrziuxgkqazmhkl.s.edbcloud.io | | ||
| | Port | Port | 5432 | | ||
| | Dbname | Maintenance database | edb_admin | | ||
|
|
||
| 1. In the **Username** and **Password** fields, enter the cluster's administrator credentials. These are the same credentials you set when configuring the cluster. If you didn't set the username, then copy and paste the default administrator username from the **User** field in BigAnimal. | ||
|
|
||
| 1. In the **SSL** tab, set the **SSL mode** field to **Require**. | ||
|
|
||
| 1. Select **Save**. pgAdmin attempts to connect to the BigAnimal cluster. | ||
|
|
||
| ## Connect a read-only workload | ||
|
|
||
| Clusters that are read-only enabled display separate connection strings for **Read-only** and **Read/write** access. | ||
|
|
||
| To connect to your cluster with the read-only workload: | ||
|
|
||
| 1. Sign in to the [BigAnimal](https://portal.biganimal.com) portal. | ||
|
|
||
| 1. Go to [Clusters](https://portal.biganimal.com/clusters). | ||
|
|
||
| 1. Select the cluster you want to connect to. | ||
|
|
||
| 1. Select the **Connect** tab. | ||
|
|
||
| 1. Copy the **Read-only Service URI**. | ||
|
|
||
| 1. Use the **Read-only Service URI** to connect to the cluster according to your database driver. | ||
|
|
||
| We recommend that your applications run `SET default_transaction_read_only = true` for all read-only activity. For a libpq driver, add `options='-c default_transaction_read_only=true'` to the database connection string. Other drivers use similiar connection parameters. Also, applications can run `BEGIN TRANSACTION READ ONLY` to mark individual transactions as read-only. | ||
|
|
||
| !!!Note | ||
| On read-only workloads, BigAnimal might cancel long-running queries and display an error message like the following: | ||
|
|
||
| ```text | ||
| ERROR: canceling statement due to conflict with recovery | ||
| ``` | ||
|
|
||
| For more information on querying standby replicas, see the [PostgreSQL Hot Standby documentation](https://www.postgresql.org/docs/current/hot-standby.html). | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -7,162 +7,37 @@ redirects: | |
| - connecting_your_cluster | ||
| --- | ||
|
|
||
| You can connect to your cluster using the client of your choice including: | ||
| - [`psql`](http://postgresguide.com/utilities/psql.html) — terminal-based client for Postgres | ||
| - pgAdmin — desktop or web UI client to inspect, monitor, manage, and query your cluster's databases | ||
| - other common database drivers | ||
| You can connect to your cluster from your cloud applications, from your client apps, and from integration points such as EDB's migration tools or PgBouncer. | ||
|
|
||
| You can manage your connections using the EDB PgBouncer connection pooler. For more information, see [Configuring EDB PgBouncer for BigAnimal](pgbouncer_configuring). | ||
|
|
||
| For additional security measures see: | ||
|
|
||
| - [Recommendations for settings for SSL mode](#recommended-settings-for-ssl-mode) | ||
| - [Using a private network to connect to your cluster](#setting-up-cloud-infrastructure-to-connect-to-a-private-network-cluster) | ||
|
|
||
| ## Recommended settings for SSL mode | ||
|
|
||
| Different clients can have different default TLS/SSL modes (sslmode). For example, `psql` defaults to `prefer`, which means the client will attempt to establish a TLS connection but fall back to non-TLS if the server does not support it. In the `psql` example provided by EDB in the **Quick Connect** field, `sslmode` is explicitly set to `require`, which means the client will attempt a TLS connection and fail if the connection to the server can't be encrypted. | ||
|
|
||
| For public connections and in most environments, EDB recommends setting `sslmode` to `verify-full`. This setting ensures that you connect to the server you specified and that the connection is encrypted. | ||
|
|
||
| BigAnimal generates certificates with LetsEncrypt, a widely trusted certificate authority. Your client machine might already have a bundled CA certificate for LetsEncrypt, for example, at `/etc/ssl/certs/ca-certificates.crt` or `/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem`. If it doesn't, your client machine needs a [CA certificate for Let's Encrypt](https://letsencrypt.org/certificates/). Once the CA certificate is in place on your client machine, configure the `sslrootcert` parameter to its location and set the `sslmode` parameter to `verify-full` to verify the certificate to fully validate the connection. | ||
|
|
||
| To view the encryption protocol being used for communication, [connect to the cluster using `psql`](#connect-to-your-cluster-using-psql) and use the `conninfo` meta-command. In the case of BigAnimal, TLS (v1.2+) is supported: | ||
|
|
||
| ``` | ||
| edb_admin=> \conninfo | ||
| You are connected to database "edb_admin" as user "edb_admin" on host "xxxxxxxxx.xxxxx.biganimal.io" at port "5432". | ||
| SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off) | ||
| ``` | ||
|
|
||
| ## Connect to your cluster using `psql` | ||
|
|
||
| 1. Sign in to the [BigAnimal](https://portal.biganimal.com) portal. | ||
|
|
||
| 2. Go to the [Clusters](https://portal.biganimal.com/clusters) page. | ||
|
|
||
| 3. Select the name of your cluster. | ||
|
|
||
| 4. On the **Overview** tab, select the copy icon to the right of the **Quick Connect** field to copy the command for connecting to your cluster using `psql` to your clipboard. `psql` prompts for the edb_admin user password you selected when you created the cluster. | ||
|
|
||
| 5. Paste the command in your terminal. | ||
|
|
||
| ## Connect to your cluster using common database drivers | ||
| ## From your applications | ||
|
|
||
| 1. Sign in to the [BigAnimal](https://portal.biganimal.com) portal. | ||
|
|
||
| 2. Go to the [Clusters](https://portal.biganimal.com/clusters) page. | ||
| The Private Networking option offers a higher level of isolation and security by moving your cluster out of the public Internet. Clusters with Private Networking enabled are by default not accessible from outside of your cluster's resource network. You need to perform additional configuration steps to connect your applications in other parts of your cloud infrastructure to your clusters via private network links. | ||
|
|
||
| 3. Select the name of your cluster. | ||
| !!!Note | ||
| EDB strongly discourages provisioning additional resources in the cluster's resource virtual network. | ||
|
|
||
| 4. Select the **Connect** tab. You can review and copy all the relevant information you need from this screen except for the edb_admin user password. | ||
| See: | ||
|
|
||
| Connection string examples for common database drivers using the recommended setting for SSL mode (consult the client driver documentation for more information): | ||
| - [Connecting from Azure](01_connecting_from_azure) | ||
| - [Connecting from AWS](02_connecting_from_aws) | ||
|
|
||
| - libpq (psql) | ||
|
|
||
| ``` | ||
| psql -W "postgres://[email protected]:5432/edb_admin?sslmode=verify-full&sslrootcert=/usr/share/ca-certificates/ca-cert_name.pem" | ||
| ``` | ||
|
|
||
| - JDBC for Java | ||
| ## From a client app | ||
|
|
||
| ``` | ||
| jdbc:postgresql://xxxxxxxxx.xxxxx.biganimal.io:5432/edb_admin?&sslrootcert=/usr/share/ca-certificates/ca-cert_name.pem&sslmode=verify-full?user=edb_admin&password=$PWD | ||
| ``` | ||
| For details on connecting from psql or edb-psql, other common database drivers, and pgAdmin, see [Connecting from a client app](connecting_from_a_client). | ||
|
|
||
| - Npgsql for DotNet Core | ||
|
|
||
| ``` | ||
| Host=xxxxxxxxx.xxxxx.biganimal.io;Port=5432;Username=edb_admin;Password=$PWD;Database=edb_admin;SslRootCert=/usr/share/ca-certificates/ca-cert_name.pem;SslMode=verify-full | ||
| ``` | ||
| - [psql or edb-psql](connecting_from_a_client/#connect-to-your-cluster-using-psql-or-edb-psql) | ||
| - [other common database drivers](connecting_from_a_client/#connect-to-your-cluster-using-common-database-drivers) | ||
| - [pgAdmin](connecting_from_a_client/#connect-to-your-cluster-using-pgadmin) | ||
|
|
||
| - ODBC for Windows | ||
| There you'll also find details on connecting read-only workloads and configuring SSL settings. | ||
|
|
||
| ``` | ||
| Driver={PostgreSQL};Server=xxxxxxxxx.xxxxx.biganimal.io;Port=5432;Database=myDataBase;Uid=edb_admin;Pwd=$PWD;sslrootcert=C:\\ssl\\ca-certificate.pem;sslmode=verify-full; | ||
| ``` | ||
|
|
||
| ## Connect your cluster to EDB's migration tools | ||
| ## From an EDB's migration tools integration point | ||
|
|
||
| To connect your cluster to EDB's migration tools, see [Migrating databases to BigAnimal](/biganimal/latest/migration/). | ||
|
|
||
| ## From an EDB PgBouncer integration point | ||
|
|
||
| ## Connect to your cluster using pgAdmin | ||
|
|
||
| To connect to your BigAnimal cluster from [pgAdmin](https://www.pgadmin.org/docs/), you need to enter your cluster values into pgAdmin. Keep BigAnimal and pgAdmin open to copy and paste the values. | ||
|
|
||
| Navigate to the location of the values: | ||
|
|
||
| 1. Sign in to the [BigAnimal](https://portal.biganimal.com) portal. | ||
|
|
||
| 1. Go to the [Clusters](https://portal.biganimal.com/clusters) page. | ||
|
|
||
| 1. Select the cluster you want to connect to. | ||
|
|
||
| 1. Select the **Connect** tab. | ||
|
|
||
| Enter the values in pgAdmin: | ||
|
|
||
| 1. Open pgAdmin. | ||
|
|
||
| 1. In the **Quick Links** panel, select **Add New Server**. | ||
|
|
||
| 1. In the Create-Server dialog box, under the **General** tab, enter a server name in the **Name** field. | ||
|
|
||
| 1. Select the **Connection** tab. | ||
|
|
||
| 1. Copy the corresponding values from BigAnimal and paste them into pgAdmin. | ||
|
|
||
| | BigAnimal field | pgAdmin field | Example value | | ||
| |-----------------|-------------------|---------------| | ||
| | Host | Host name/address | p-n85scw2ies.fcrziuxgkqazmhkl.s.edbcloud.io | | ||
| | Port | Port | 5432 | | ||
| | Dbname | Maintenance database | edb_admin | | ||
|
|
||
| 1. In the **Username** and **Password** fields, enter the cluster's administrator credentials. These are the same credentials you set when configuring the cluster. If you didn't set the username, then copy and paste the default administrator username from the **User** field in BigAnimal. | ||
|
|
||
| 1. In the **SSL** tab, set the **SSL mode** field to **Require**. | ||
|
|
||
| 1. Select **Save**. pgAdmin attempts to connect to the BigAnimal cluster. | ||
|
|
||
| ## Connect a read-only workload | ||
|
|
||
| Clusters that are read-only enabled display separate connection strings for **Read-only** and **Read/write** access. | ||
|
|
||
| To connect to your cluster with the read-only workload: | ||
|
|
||
| 1. Sign in to the [BigAnimal](https://portal.biganimal.com) portal. | ||
|
|
||
| 1. Go to [Clusters](https://portal.biganimal.com/clusters). | ||
|
|
||
| 1. Select the cluster you want to connect to. | ||
|
|
||
| 1. Select the **Connect** tab. | ||
|
|
||
| 1. Copy the **Read-only Service URI**. | ||
|
|
||
| 1. Use the **Read-only Service URI** to connect to the cluster according to your database driver. | ||
|
|
||
| We recommend that your applications run `SET default_transaction_read_only = true` for all read-only activity. For a libpq driver, add `options='-c default_transaction_read_only=true'` to the database connection string. Other drivers use similiar connection parameters. Also, applications can run `BEGIN TRANSACTION READ ONLY` to mark individual transactions as read-only. | ||
|
|
||
| !!!Note | ||
| On read-only workloads, BigAnimal might cancel long-running queries and display an error message like the following: | ||
|
|
||
| ```text | ||
| ERROR: canceling statement due to conflict with recovery | ||
| ``` | ||
|
|
||
| For more information on querying standby replicas, see the [PostgreSQL Hot Standby documentation](https://www.postgresql.org/docs/current/hot-standby.html). | ||
|
|
||
| ## Setting up cloud infrastructure to connect to a private network cluster | ||
|
|
||
| The Private Networking option offers a higher level of isolation and security by moving your cluster out of the public Internet. Clusters with Private Networking enabled are by default not accessible from outside of your cluster's resource network. You need to perform additional configuration steps to connect your applications in other parts of your cloud infrastructure to your clusters via private network links. | ||
|
|
||
| !!!Note | ||
| EDB strongly discourages provisioning additional resources in the cluster's resource virtual network. | ||
|
|
||
| For examples to guide you through the different methods of connecting to your cluster, see | ||
| You can manage your connections using the EDB PgBouncer connection pooler. For more information, see [Configuring EDB PgBouncer for BigAnimal](pgbouncer_configuring). | ||
|
|
||
| - [Connecting from Azure](01_connecting_from_azure) | ||
| - [Connecting from AWS](02_connecting_from_aws) | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.