From 745857519581af306c1a9f6591d565a3d9970798 Mon Sep 17 00:00:00 2001 From: Betsy Gitelman <93718720+ebgitelman@users.noreply.github.com> Date: Thu, 27 Apr 2023 16:58:04 -0400 Subject: [PATCH 01/15] Rest of edits to BigAnimal --- .../docs/biganimal/release/knowledge_base.mdx | 2 +- .../using_cluster/01_postgres_access.mdx | 36 ++++---- .../using_cluster/04_backup_and_restore.mdx | 16 ++-- .../05a_deleting_your_cluster.mdx | 29 ++++--- .../06_analyze_with_superset.mdx | 14 +-- .../06_demonstration_oracle_compatibility.mdx | 86 +++++++++---------- .../using_cluster/managing_replicas.mdx | 56 ++++++------ .../using_cluster/terraform_provider.mdx | 26 +++--- 8 files changed, 127 insertions(+), 138 deletions(-) diff --git a/product_docs/docs/biganimal/release/knowledge_base.mdx b/product_docs/docs/biganimal/release/knowledge_base.mdx index fc0b893b6c2..68419805641 100644 --- a/product_docs/docs/biganimal/release/knowledge_base.mdx +++ b/product_docs/docs/biganimal/release/knowledge_base.mdx @@ -8,7 +8,7 @@ The BigAnimal Support team provides a [knowledge base](https://support.biganimal Follow the knowledge base to be notified of new articles. -## Stepping up specific identity provider articles +## Setting up specific identity provider articles See the following articles for step-by-step instructions for setting up specific identity providers: diff --git a/product_docs/docs/biganimal/release/using_cluster/01_postgres_access.mdx b/product_docs/docs/biganimal/release/using_cluster/01_postgres_access.mdx index e6d69df0636..d484f7ad871 100644 --- a/product_docs/docs/biganimal/release/using_cluster/01_postgres_access.mdx +++ b/product_docs/docs/biganimal/release/using_cluster/01_postgres_access.mdx @@ -2,15 +2,15 @@ title: "Managing Postgres access" --- -You control access to your Postgres database by database authentication implemented by creating databases with specific roles and privileges. Database authentication differs from portal authentication, which controls access to the BigAnimal portal. +You control access to your Postgres database using database authentication implemented by creating databases with specific roles and privileges. Database authentication differs from portal authentication, which controls access to the BigAnimal portal. For information on portal authentication, see: -- [Setting up your identity provider](/biganimal/latest/getting_started/identity_provider/) if you purchased BigAnimal directly from EDB, or +- [Setting up your identity provider](/biganimal/latest/getting_started/identity_provider/) if you purchased BigAnimal directly from EDB - [Setting up your Azure Marketplace account](/biganimal/latest/getting_started/02_azure_market_setup/) if you purchased BigAnimal through Azure Marketplace ## Setting up your database authentication -Don't use the `edb_admin` database role and `edb_admin` database created when creating your cluster in your application. Instead, create a new database role and a new database, which provides a high level of isolation in Postgres. If multiple applications are using the same cluster, each database can also contain multiple schemas, essentially a namespace in the database. If strict isolation is needed, use a dedicated cluster or dedicated database. If that strict isolation level isn't required, you can deploy a single database with multiple schemas. Refer to [Privileges](https://www.postgresql.org/docs/current/ddl-priv.html) in the PostgreSQL documentation to further customize ownership and roles to your requirements. +Don't use the edb_admin database role and edb_admin database created when creating your cluster in your application. Instead, create a new database role and a new database, which provides a high level of isolation in Postgres. If multiple applications are using the same cluster, each database can also contain multiple schemas, essentially a namespace in the database. If you need strict isolation, use a dedicated cluster or dedicated database. If you don't need that strict isolation level, you can deploy a single database with multiple schemas. See [Privileges](https://www.postgresql.org/docs/current/ddl-priv.html) in the PostgreSQL documentation to further customize ownership and roles to your requirements. To create a new role and database, first connect using `psql`: @@ -18,35 +18,35 @@ To create a new role and database, first connect using `psql`: psql -W "postgres://edb_admin@xxxxxxxxx.xxxxx.biganimal.io:5432/edb_admin?sslmode=require" ``` !!! Note - Avoid storing data in the `postgres` system database. + Avoid storing data in the postgres system database. ## Notes on the edb_admin role -- The `edb_admin` role does not have superuser privileges by default. Contact [Support](../overview/support) to request superuser privileges for `edb_admin`. If you request superuser privileges, you **must** take care to limit the number of connections used by superusers to avoid degraded service and/or compromising availability. +- The edb_admin role doesn't have superuser privileges by default. Contact [Support](../overview/support) to request superuser privileges for edb_admin. If you request superuser privileges, you must take care to limit the number of connections used by superusers to avoid degraded service or compromising availability. !!! note - Superuser privileges allow you to make Postgres configuration changes using `ALTER SYSTEM` queries. We recommend you don't do this because it may lead to an unpredictable/unrecoverable state of the cluster. In addition, `ALTER SYSTEM` changes are not replicated across the cluster. + Superuser privileges allow you to make Postgres configuration changes using `ALTER SYSTEM` queries. We recommend you don't do this because it might lead to an unpredictable or unrecoverable state of the cluster. In addition, `ALTER SYSTEM` changes aren't replicated across the cluster. -- Changes to system configuration (GUCs) made by edb_admin or other Postgres users are not persisted though a reboot or maintenance. Use the BigAnimal portal to modify system configuration. +- Changes to system configuration (GUCs) made by edb_admin or other Postgres users don't persist through a reboot or maintenance. Use the BigAnimal portal to modify system configuration. -- You have to remember your `edb_admin` password as EDB does not have access to it. If you forget it, you can set a new one in the BigAnimal portal on the Edit Cluster page. +- You have to remember your edb_admin password, as EDB doesn't have access to it. If you forget it, you can set a new one in the BigAnimal portal on the Edit Cluster page. -- Don't use the `edb_admin` user or the `edb_admin` database in your applications. Instead, use `CREATE USER; GRANT; CREATE DATABASE.` +- Don't use the edb_admin user or the edb_admin database in your applications. Instead, use `CREATE USER; GRANT; CREATE DATABASE.` -- BigAnimal stores all database-level authentication securely and directly in PostgreSQL. The `edb_admin` user password is SCRAM-SHA-256 hashed prior to storage. This hash, even if compromised, cannot be replayed by an attacker to gain access to the system. +- BigAnimal stores all database-level authentication securely and directly in PostgreSQL. The `edb_admin` user password is `SCRAM-SHA-256` hashed prior to storage. This hash, even if compromised, can't be replayed by an attacker to gain access to the system. ## One database with one application -For one database hosting a single application, replace app1 with your preferred user name: +For one database hosting a single application, replace `app1` with your preferred user name: 1. Create a new database user. For example, ``` edb_admin=# create user app1 with password 'app1_pwd'; ``` -2. Assign the new role to your `edb_admin` user. Assigning this role allows you to assign ownership to the new user in the next step. For example: +2. Assign the new role to your edb_admin user. Assigning this role allows you to assign ownership to the new user in the next step. For example: ``` edb_admin=# grant app1 to edb_admin; ``` @@ -56,11 +56,11 @@ For one database hosting a single application, replace app1 with your preferred edb_admin=# create database app1 with owner app1; ``` -Using this example, the username and database in your connection string is `app1`. +Using this example, the username and database in your connection string is app1. ## One database with multiple schemas -If a single database is used to host multiple schemas, create a database owner and then roles and schemas for each application. This example shows creating two database roles and two schemas. The default `search_path` for database roles in BigAnimal is `"$user",public`. If the role name and schema match, then objects in that schema match first, and no `search_path` changes or fully qualifying of objects are needed. The [PostgreSQL documentation](https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-PATH) covers the schema search path in detail. +If you use a single database to host multiple schemas, create a database owner and then roles and schemas for each application. This example shows creating two database roles and two schemas. The default `search_path` for database roles in BigAnimal is `"$user",public`. If the role name and schema match, then objects in that schema match first, and no `search_path` changes or fully qualifying of objects are needed. The [PostgreSQL documentation](https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-PATH) covers the schema search path in detail. 1. Create a database owner and new database. For example: ``` @@ -83,14 +83,14 @@ If a single database is used to host multiple schemas, create a database owner a prod1=# grant app2 to edb_admin; ``` -4. Create a new schema for each application with the AUTHORIZATION clause for the application owner. For example: +4. Create a new schema for each application with the `AUTHORIZATION` clause for the application owner. For example: ``` prod1=# create schema app1 authorization app1; prod1=# create schema app2 authorization app2; ``` ## IAM authentication for Postgres -Any AWS user with an AWS account connected to a BigAnimal subscription who has the Postgres role of "iam_aws" can authenticate to the database using their AWS IAM credentials. +Any AWS user with an AWS account connected to a BigAnimal subscription who has the Postgres role of iam_aws can authenticate to the database using their AWS IAM credentials. ### Configuring IAM for Postgres @@ -100,7 +100,7 @@ Provision your cluster before configuring IAM for Postgres. 1. On the **Additional Settings** tab, under **Authentication**, select **Identity and Access Management (IAM) Authentication**. 1. Select **Create Cluster** or **Save**. !!!note - To turn on IAM authentication using the CLI, see the [Using IAM authentication on AWS](/biganimal/latest/reference/cli/using_features/#iam-authentication-cli-commands) section in the Using the BigAnimal CLI topic. + To turn on IAM authentication using the CLI, see [Using IAM authentication on AWS](/biganimal/latest/reference/cli/using_features/#iam-authentication-cli-commands). 1. In AWS, get the ARN of each IAM user requiring database access. In the AWS account connected to BigAnimal, use AWS Identity and Access Management (IAM) to perform user management. See the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_manage.html). 1. In Postgres, if the IAM role doesn’t exist yet, run this Postgres command: @@ -124,7 +124,7 @@ If IAM integration is configured for your cluster, you can log in to Postgres us 1. Using your AWS CLI or Cloud shell, obtain your ARN and access key. For guidance on obtaining your ARN and access key, see [Managing access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html). 1. Connect to Postgres using your IAM credentials. -1. When prompted for the password, enter your access key (<access key ID>:<secret access key>). +1. When prompted for the password, enter your access key (``). ### Using IAM authentication CLI commands diff --git a/product_docs/docs/biganimal/release/using_cluster/04_backup_and_restore.mdx b/product_docs/docs/biganimal/release/using_cluster/04_backup_and_restore.mdx index 42f422b6e5b..d9e029b715e 100644 --- a/product_docs/docs/biganimal/release/using_cluster/04_backup_and_restore.mdx +++ b/product_docs/docs/biganimal/release/using_cluster/04_backup_and_restore.mdx @@ -4,7 +4,7 @@ title: "Backing up and restoring" ## Backups -BigAnimal backs up the data in your PostgreSQL clusters. You can change the retention period on the [Backups tab](../getting_started/creating_a_cluster/#additional-settings-tab) when you create or edit your cluster. Depending on the cloud your cluster is deployed on, BigAnimal uses either of the following cloud object storage solutions: +BigAnimal backs up the data in your PostgreSQL clusters. You can change the retention period on the [Backups tab](../getting_started/creating_a_cluster/#additional-settings-tab) when you create or edit your cluster. Depending on the cloud your cluster is deployed on, BigAnimal uses either of the following cloud object storage solutions. | Cloud | Object storage solution | | |----------------------------|--------------------------------------------------------------------------------------|---| @@ -13,14 +13,14 @@ BigAnimal backs up the data in your PostgreSQL clusters. You can change the rete Your organization is responsible for the charges associated with the cloud object storage solution. -PostgreSQL clusters in BigAnimal are continuously backed up through a combination of base backups and transaction log (WAL) archiving. When a new cluster is created, an initial "base" backup is taken. After that, every time a WAL file is closed, which is, by default, up to every 5 minutes, it is automatically uploaded to the cloud object storage solution. If your cluster has faraway replicas, BigAnimal copies the WAL files from your cloud object storage solution and asynchronously transfers them to the faraway replicas. Your organization is responsible for the charges associated with the cloud object storage solution. +PostgreSQL clusters in BigAnimal are continuously backed up through a combination of base backups and transaction log (WAL) archiving. When a new cluster is created, an initial "base" backup is taken. After that, every time a WAL file is closed, which is, by default, up to every 5 minutes, it's uploaded to the cloud object storage solution. If your cluster has faraway replicas, BigAnimal copies the WAL files from your cloud object storage solution and asynchronously transfers them to the faraway replicas. Your organization is responsible for the charges associated with the cloud object storage solution. You can change the retention period on the [Additional Settings tab](../getting_started/creating_a_cluster/#additional-settings-tab) when you create or edit your cluster. ## Faraway replicas -As new data from a cluster is archived, BigAnimal copies and transfers the WAL files from your cloud object storage solution and *asynchronously* transfers them to faraway replicas. If the time interval set for closing a WAL file is too large, it can introduce a delay until the faraway replica receives the latest record. Log shipping does not make any changes to the database tables. It facilitates: +As new data from a cluster is archived, BigAnimal copies and transfers the WAL files from your cloud object storage solution and asynchronously transfers them to faraway replicas. If the time interval set for closing a WAL file is too large, it can introduce a delay until the faraway replica receives the latest record. Log shipping doesn't make any changes to the database tables. It facilitates: - Low administration overhead - Predictable timelines @@ -30,9 +30,9 @@ You can configure backups for faraway replicas as well. ## Restores -If a restore is necessary—for example, in case of an accidental `DROP TABLE` statement—you can restore clusters to any point within the backup retention period. +If a restore is necessary—for example, in case of an accidental `DROP TABLE` statement—you can restore clusters to any point in the backup retention period. -Cluster restores aren't performed "in-place" on an existing cluster. Instead, a new cluster is created and initialized with data from the backup archive. Restores must replay the transaction logs between the most recent full database backup and the target restore point. Thus restore times (that is, RTO) are dependent on the write activity in the source cluster. +Cluster restores aren't performed in place on an existing cluster. Instead, a new cluster is created and initialized with data from the backup archive. Restores must replay the transaction logs between the most recent full database backup and the target restore point. Thus restore times (that is, RTO) depend on the write activity in the source cluster. BigAnimal retains backups for 30 days by default. You can restore backups into a new cluster in any region supported by BigAnimal. @@ -40,11 +40,11 @@ BigAnimal retains backups for 30 days by default. You can restore backups into a The restore operation is available for any cluster that has at least one available backup. For newly created clusters, the initial backup becomes available a few minutes after the new cluster is fully operational. -1. Select the cluster you want to restore on the [Clusters](https://portal.biganimal.com/clusters) page in the [BigAnimal](https://portal.biganimal.com) portal. +1. Select the cluster you want to restore on the [Clusters](https://portal.biganimal.com/clusters) page in the [BigAnimal portal](https://portal.biganimal.com). 2. From **Quick Actions**, select **Restore**. 3. On the Restore Cluster page: 1. Fill in the required fields. - 2. In the **Source** section, in the **Point in Time Restore** field, select **Now** on the calendar to restore to the last possible recovery point. Or, choose a timestamp to restore further back in time. + 2. To restore to the last possible recovery point, in the **Source** section, in the **Point in Time Restore** field, select **Now** on the calendar. Or, to restore further back in time, choose a timestamp. 3. Review your selections in **Cluster Summary** and select **Restore Cluster** to begin the restore process. 4. The new cluster is now available on the [Clusters](https://portal.biganimal.com/clusters) page. @@ -52,7 +52,7 @@ The restore operation is available for any cluster that has at least one availab You can restore one data group from a PGD cluster into a new PGD cluster. To restore two data groups, restore one data group into a new cluster, and add the second data group manually. -1. On the [Clusters](https://portal.biganimal.com/clusters) page in the [BigAnimal](https://portal.biganimal.com) portal, select the cluster you want to restore. +1. On the [Clusters](https://portal.biganimal.com/clusters) page in the [BigAnimal portal](https://portal.biganimal.com), select the cluster you want to restore. 1. Select **Quick Actions > Restore**. 1. In the **Cluster Settings** tab, enter a cluster name and password for your restored cluster. 1. Select **Next: Data Group**. diff --git a/product_docs/docs/biganimal/release/using_cluster/05a_deleting_your_cluster.mdx b/product_docs/docs/biganimal/release/using_cluster/05a_deleting_your_cluster.mdx index 31105732d98..a5c92aea373 100644 --- a/product_docs/docs/biganimal/release/using_cluster/05a_deleting_your_cluster.mdx +++ b/product_docs/docs/biganimal/release/using_cluster/05a_deleting_your_cluster.mdx @@ -2,25 +2,28 @@ title: "Deleting your cluster" --- -If you no longer need a particular cluster, you can delete it from the BigAnimal portal. Deleted clusters can be restored after the cluster has been deleted for as long as the backup is available. The backup remains available for the retention period set for each cluster, after which it is deleted. To stop the management costs on the cluster, contact EDB's BigAnimal Support team; otherwise, costs may continue to accumulate. +If you no longer need a particular cluster, you can delete it from the BigAnimal portal. You can restore deleted clusters after you delete the cluster for as long as the backup is available. The backup remains available for the retention period set for each cluster. After the retention period, the backup is deleted. + +To stop the management costs on the cluster, contact EDB's BigAnimal Support team, Otherwise, costs might continue to accumulate. ## Delete your cluster !!! Important - You can not delete a cluster unless you have either promoted or deleted each of its faraway replicas. See [Faraway replicas](/biganimal/latest/overview/replication/) + You can delete a cluster only if you have either promoted or deleted each of its faraway replicas. See [Faraway replicas](/biganimal/latest/overview/replication/). -1. Go to the [**Clusters**](https://portal.biganimal.com/clusters) page in the [BigAnimal](https://portal.biganimal.com) portal. -2. Do one of the following to delete the cluster: - - Select the Delete cluster icon in the row for the cluster. - - Select the cluster you wish to delete and from **Quick Actions** on the cluster details page, select **Delete**. -3. Confirm you want to delete the cluster. When the process completes, the cluster is listed on the **Deleted** tab of the **Clusters** page. -4. Contact [Support](../overview/support/) to stop the associated management costs. For more information on management costs see [Pricing and billing](../pricing_and_billing/#management-costs). +1. Go to the [Clusters](https://portal.biganimal.com/clusters) page in the [BigAnimal portal](https://portal.biganimal.com). +2. To delete the cluster, do one of the following: + - Select the **Delete cluster** icon in the row for the cluster. + - Select the cluster you want to delete. From **Quick Actions** on the cluster details page, select **Delete**. +3. Confirm that you want to delete the cluster. When the process finishes, the cluster is listed on the **Deleted** tab of the Clusters page. +4. To stop the associated management costs, contact [Support](../overview/support/). For more information on management costs, see [Pricing and billing](../pricing_and_billing/#management-costs). ## Restore your cluster -You can restore your cluster after the cluster has been deleted for as long as the backup is available. +You can restore your deleted cluster for as long as the backup is available. + +1. Select the **Delete** tab on the [Clusters](https://portal.biganimal.com/clusters) page in the [BigAnimal portal](https://portal.biganimal.com). +2. Select the **Restore** icon for the cluster you want to restore. +3. On the Restore Cluster page, review your selections in the **Cluster Summary**. Select **Restore Cluster** to begin the restore process. -1. Select the **Delete** tab on the [**Clusters**](https://portal.biganimal.com/clusters) page in the [BigAnimal](https://portal.biganimal.com) portal. -2. Select the Restore icon for the cluster you wish to restore. -3. On the Restore Cluster page, review your selections in the **Cluster Summary** and select **Restore Cluster** to begin the restore process. - When the process completes, the restored cluster is available on the [**Clusters**](https://portal.biganimal.com/clusters) page. + When the process completes, the restored cluster is available on the [Clusters](https://portal.biganimal.com/clusters) page. diff --git a/product_docs/docs/biganimal/release/using_cluster/06_analyze_with_superset.mdx b/product_docs/docs/biganimal/release/using_cluster/06_analyze_with_superset.mdx index 8a08ac1c6b6..cb1391a0591 100644 --- a/product_docs/docs/biganimal/release/using_cluster/06_analyze_with_superset.mdx +++ b/product_docs/docs/biganimal/release/using_cluster/06_analyze_with_superset.mdx @@ -2,7 +2,7 @@ title: "Analyzing your data with Apache Superset" --- You can use Apache Superset to analyze, explore, and visualize data stored in your Postgres clusters. -You can open Superset from the [BigAnimal](https://portal.biganimal.com/) portal using the **Analyze** links. +You can open Superset from the [BigAnimal portal](https://portal.biganimal.com/) using the **Analyze** links. !!!note Contact [BigAnimal Support](../overview/support) to enable the Apache Superset feature. @@ -13,9 +13,9 @@ Default permissions include the ability to view data and create dashboards. To a ## Connecting Superset to your cluster -In addition to your password, you need your user, host, port, and database name to connect to Superset. To find this information for your cluster: +To connect to Superset, in addition to your password, you need your user, host, port, and database name. To find this information for your cluster: -1. Sign in to the [BigAnimal](https://portal.biganimal.com/) portal. +1. Sign in to the [BigAnimal portal](https://portal.biganimal.com/). 3. Go to the [Clusters](https://portal.biganimal.com/clusters) page. 4. Select the name of your cluster. @@ -26,7 +26,7 @@ In addition to your password, you need your user, host, port, and database name To connect to a BigAnimal cluster: -1. Sign in to the [BigAnimal](https://portal.biganimal.com/) portal. +1. Sign in to the [BigAnimal portal](https://portal.biganimal.com/). 2. Select **Analyze > Connections**. 3. Select **+ Database**. @@ -107,9 +107,3 @@ To view all available Superset charts, select **Analyze > Charts**. ## Using Superset SQL Lab You can use Superset SQL Lab to write queries to access and modify data stored in your cluster. To access SQL Lab, select **Analyze > SQL Editor**. - - - - - - diff --git a/product_docs/docs/biganimal/release/using_cluster/06_demonstration_oracle_compatibility.mdx b/product_docs/docs/biganimal/release/using_cluster/06_demonstration_oracle_compatibility.mdx index 80ba87b518f..01d21b6b972 100644 --- a/product_docs/docs/biganimal/release/using_cluster/06_demonstration_oracle_compatibility.mdx +++ b/product_docs/docs/biganimal/release/using_cluster/06_demonstration_oracle_compatibility.mdx @@ -4,9 +4,9 @@ navTitle: "Oracle SQL compatibility" showInteractiveBadge: true --- -BigAnimal lets you run Oracle SQL queries in the cloud via [EDB Postgres Advanced Server](/epas/latest/epas_compat_ora_dev_guide/). This topic demonstrates two Oracle SQL-syntax queries running unmodified on a BigAnimal test cluster, populated with the [Chinook sample database](https://github.com/lerocha/chinook-database). +BigAnimal lets you run Oracle SQL queries in the cloud using [EDB Postgres Advanced Server](/epas/latest/epas_compat_ora_dev_guide/). This demonstration shows two Oracle SQL-syntax queries running unmodified on a BigAnimal test cluster, populated with the [Chinook sample database](https://github.com/lerocha/chinook-database). -Watch the video, or load up psql and follow along below! +Watch the video, or load up psql and follow along.