Merge pull request #2519 from EnterpriseDB/release/2022-04-4

Release: 2022-04-4

product_docs/docs/biganimal/release/free_trial/detail/connect_to_a_cluster/connect_using_dbeaver.mdx

@@ -0,0 +1,41 @@
+---
+title: "Connect to your cluster using DBeaver"
+navTitle: DBeaver
+indexCards: none
+---
+
+!!! Note
+    All of the parameters you need to connect can be found on the portal by selecting the name of your cluster on the [Clusters](https://portal.biganimal.com/clusters) page and then selecting the **Connect** tab.
+
+1. Launch [DBeaver](https://dbeaver.io/).
+2. Select the **New Database Connection** button on the toolbar to open the **Connect to a database** dialog.
+3. Select **PostgreSQL** and select **Next**.
+
+    You might be prompted to download the PostgreSQL JDBC driver.
+4. On the **Main** tab:
+
+    - Enter your cluster's hostname in the **Host** field.
+
+    - Enter `edb_admin` in the **Database** field.
+    - Enter `edb_admin` in the **Username** field.
+    - Enter your cluster's password in the **Password** field. 
+
+5. On the **SSL** tab:
+
+    - Select the **Use SSL** check box.
+    - Select **require** for the **SSL mode:** field.
+
+6. On the **PostgreSQL** tab, check the **Show all databases** check box.
+
+7. Select the **Test connection** button and verify that DBeaver can connect to your cluster.
+8. Select **Finish** to save the connection.
+
+
+## Next steps
+
+[Experiment!](../experiment)
+
+
+## Further reading
+
+[Connecting to your cluster](/biganimal/latest/using_cluster/02_connecting_your_cluster/) in the full version documentation.

product_docs/docs/biganimal/release/free_trial/detail/connect_to_a_cluster/connect_using_pgadmin.mdx

@@ -0,0 +1,33 @@
+---
+title: "Connect to your cluster using pgAdmin"
+navTitle: pgAdmin
+indexCards: none
+---
+
+!!! Note
+    All of the parameters you need to connect can be found on the portal by selecting the name of your cluster on the [Clusters](https://portal.biganimal.com/clusters) page and then selecting the **Connect** tab.
+
+
+[The pgAdmin project](https://www.pgadmin.org/download/) allows you to inspect, monitor, manage, and query your cluster's databases from a desktop or web UI. 
+
+From the welcome page, select **Add New Server**. You'll be prompted to configure the connection.
+
+Enter `BigAnimal Trial` for the name (or use the name you gave to your cluster!), and then select **Connection**.
+
+1. Enter your cluster's hostname in the **Host name/address** field. 
+2. Enter `edb_admin` in the **Maintenance database** field (this is the default database that'll be connected to by pgAdmin). 
+3. Enter `edb_admin` in the **Username** field.
+4. Enter the password you provided when configuring your cluster in the **Password** field (you might want to save this for convenience while testing).
+
+Select **SSL** and change SSL mode to **Require**.
+
+Finally, select the **Save** button. pgAdmin tries to establish a connection to your database. When successful, it displays the dashboard 
+along with the list of available databases on the left.
+
+## Next steps
+
+[Experiment!](../experiment)
+
+## Further reading
+
+[Connecting to your cluster](/biganimal/latest/using_cluster/02_connecting_your_cluster/) in the full version documentation.

product_docs/docs/biganimal/release/free_trial/detail/connect_to_a_cluster/connect_using_psql.mdx

@@ -0,0 +1,36 @@
+---
+title: "Connect to your cluster using psql"
+navTitle: psql
+indexCards: none
+---
+
+!!! Note
+    All of the parameters you need to connect can be found on the portal by selecting the name of your cluster on the [Clusters](https://portal.biganimal.com/clusters) page and then selecting the **Connect** tab.
+
+
+[psql](https://www.postgresql.org/docs/current/app-psql.html) is the standard PostgreSQL [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) 
+and an all-around useful tool for working with PostgreSQL databases. In addition to letting you submit SQL and view the results, it offers quite a few built-in commands for
+inspecting and managing the database that make light work of even complex tasks.
+
+You can find an example of connecting to a BigAnimal cluster via psql right on your cluster's **Overview** tab on the portal. For example:
+
+```shell
+psql -W "postgres://[email protected]:5432/edb_admin?sslmode=require"
+```
+
+The URI is all that's necessary for psql. While you _can_ pass each element of that URL individually 
+(pulling the information from the **Connect** tab on the portal, for instance), psql will happily parse it out for you (and prompt for the password).
+
+In case you're unfamiliar with PostgreSQL's URI format, you can find it documented [on postgresql.org](https://www.postgresql.org/docs/current/libpq-connect.html#id-1.7.3.8.3.6).
+
+
+!!! Note EDB Postgres Advanced Server enhancements
+    If your cluster is running EDB Postgres Advanced Server, you might wish to install the version of psql that ships with it; there are a few nice additions such as tab completion for Oracle database-compatible syntax. However, the standard PostgreSQL client works with EDB Postgres Advanced Server as well.
+
+## Next steps
+
+[Experiment!](../experiment)
+
+## Further reading
+
+[Connecting to your cluster](/biganimal/latest/using_cluster/02_connecting_your_cluster/) in the full version documentation.

product_docs/docs/biganimal/release/free_trial/detail/connect_to_a_cluster/index.mdx

@@ -0,0 +1,18 @@
+---
+title: "Connect to your cluster"
+description: "Connecting to a BigAnimal cluster from several common clients"
+indexCards: simple
+navigation:
+    - connect_using_psql
+    - connect_using_pgadmin
+    - connect_using_dbeaver
+---
+
+So, you've created a cluster. Now what? You probably want to connect to it!
+
+BigAnimal clusters are real, actual Postgres databases, so you can connect to them just as you would any other Postgres database. 
+
+All of the parameters you need to connect can be found on the portal by selecting the name of your cluster on the [Clusters](https://portal.biganimal.com/clusters) page and then selecting the **Connect** tab.
+
+This section provides a few examples of connecting from common clients.
+

product_docs/docs/biganimal/release/free_trial/detail/create_a_cluster/create_cluster_cli.mdx

@@ -0,0 +1,147 @@
+---
+title: Creating a cluster on the command line
+navTitle: "Using the command line" 
+indexCards: none
+---
+
+
+We'll be using the [BigAnimal command line interface](/biganimal/latest/reference/cli/), which is a convenient wrapper to the [BigAnimal API](/biganimal/latest/reference/api/). To start, download [the latest binary](/biganimal/latest/reference/cli/) and move it to wherever your system finds executable files (somewhere on your PATH). 
+
+!!! Note Linux and MacOS note
+    If you're on a Linux or MacOS system, you'll need to mark the `biganimal` file as executable by
+    running `chmod +x [/path/to/biganimal]` before you can use it.  
+
+
+Next, you need to create a credential on BigAnimal. You can pick any username you prefer.
+
+```shell
+biganimal create-credential -a portal.biganimal.com -o 443 -n newuser
+__OUTPUT__
+First, copy your one-time code: 
+         CODE-CODE
+Then visit: https://auth.biganimal.com/activate 
+press [Enter] to continue in the web browser... 
+
+Credential "newuser" is created operation succeeded
+Switched the context credential to "newuser".
+```
+
+!!! Note Linux dependencies
+    The BigAnimal CLI uses the xdg-open utility to open a browser on Linux systems.
+    On minimal systems, you may need to install this dependency before creating a credential.
+
+The command will direct you to open a webpage and copy the randomly generated, one-time code. You’ll need to log in (or already be logged in) to activate the credentials. You can see the credentials you've verified on the command line.
+
+```shell
+biganimal show-credentials
+__OUTPUT__
+┌──────────────────────────────────────────────────────┐
+│ Credentials                                          │
+├─────────┬─────────────────────────────────────┬──────┤
+│ name    │ address                             │ port │
+├─────────┼─────────────────────────────────────┼──────┤
+│ newuser │ portal.biganimal.com                │ 443  │
+└─────────┴─────────────────────────────────────┴──────┘
+```
+
+!!! caution
+If you add another credential, you’ll need to add `--credential [newuser]` to the following commands. If you only have one, the option isn't needed. You can change the default credential using `biganimal config set context_credential [name]` You can remove unneeded credentials using `biganimal delete-credential [olduser]`. Most users don't need to add multiple credentials.
+!!!
+
+In the free trial, the range of cluster options is somewhat limited but should be more than sufficient for demonstrating the capabilities of BigAnimal.
+
+Pick the region closest to you from the list provided by BigAnimal:
+
+```shell
+biganimal show-regions
+__OUTPUT__
+Use the arrow keys to navigate: ↓ ↑
+Provider ID?
+    AWS
+  ▸ Azure
+┌───────────────────────────────────┐
+│ Regions                           │
+├────────────┬──────────────────────┤
+│ Region Id  │ Region Name          │
+├────────────┼──────────────────────┤
+│ eastus2    │ (US) East US 2       │
+│ westeurope │ (Europe) West Europe │
+└────────────┴──────────────────────┘
+```
+
+Other options can be queried via the CLI, but the only value we need to set for this demo is the region Id.
+
+Edit a new file called `create_cluster.yaml`:
+
+```yaml
+clusterName: test_cluster # Pick a more meaningful name!
+password: mygoodpassword  # Please change this password!
+postgresType: epas
+postgresVersion: "14"
+provider: azure
+region: eastus2  # Select from the options given by show-regions
+instanceType: azure:Standard_E2s_v3
+volumeProperties: P1
+volumeType: azurepremiumstorage
+networking: public
+highAvailability: false
+```
+
+Use the config file to create a new cluster:
+
+```shell
+biganimal create-cluster --clusterConfigFile create_cluster.yaml
+__OUTPUT__
+Are you sure you want to create cluster "test_cluster"? [y|n]: y
+Create Cluster operation is started
+Cluster ID is "p-xxxxxxxxxx"
+To check current state, run: biganimal show-clusters --id p-xxxxxxxxxx
+```
+
+If successful, create-cluster will give you the ID of your new cluster (you'll use this to manage it) as well as
+the command you can use to check the status of your new cluster:
+
+```shell
+biganimal show-clusters --id p-xxxxxxxxxx
+__OUTPUT__
+┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
+│ Clusters                                                                                                                                             │
+├──────────────┬──────────────┬───────────────────────────────────┬──────────┬────────────────┬───────────────┬──────────────────────────────┬─────────┤
+│ ID           │ Name         │ Status                            │ Provider │ Region         │ Instance Type │ Postgres Type                │ Version │
+├──────────────┼──────────────┼───────────────────────────────────┼──────────┼────────────────┼───────────────┼──────────────────────────────┼─────────┤
+│ p-xxxxxxxxxx │ test_cluster │ Cluster creation request received │ Azure    │ (US) East US 2 │ E2s v3        │ EDB Postgres Advanced Server │ 14      │
+└──────────────┴──────────────┴───────────────────────────────────┴──────────┴────────────────┴───────────────┴──────────────────────────────┴─────────┘
+```
+
+It might take a few minutes to create your cluster. When it’s ready,
+the Status column will change to "Cluster in healthy state". 
+
+In the meantime, you can get the connection string for your cluster:
+
+```shell
+biganimal show-cluster-connection --id p-xxxxxxxxxxx
+__OUTPUT__
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│ Connection String                                                                        │
+├──────────────────────────────────────────────────────────────────────────────────────────┤
+│ postgres://[email protected]:5432/edb_admin?sslmode=require        │
+└──────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+Once the cluster is created, log in via psql. Use the password from the `config` file for edb_admin.
+
+```shell
+psql 'postgres://[email protected]:5432/edb_admin?sslmode=require'
+```
+
+!!! Note "Other options for connecting"
+    Sure, psql is great, but maybe you want to use another client. See [Connect to your cluster](../connect_to_a_cluster) for other options.
+
+## Next steps
+
+[Connect to your cluster](../connect_to_a_cluster)
+
+## Further reading
+
+[BigAnimal CLI reference](/biganimal/latest/reference/cli/) and 
+[Creating a cluster](/biganimal/latest/getting_started/creating_a_cluster/) in the full version documentation.

product_docs/docs/biganimal/release/free_trial/detail/create_a_cluster/create_cluster_portal.mdx

@@ -0,0 +1,64 @@
+---
+title: Creating a cluster using the web portal
+navTitle: "Using the portal" 
+indexCards: none
+---
+
+## Navigating to the Create Cluster page
+
+1. Navigate to the [BigAnimal portal](https://portal.biganimal.com/). (Sign in with [your account](../create_account) if you need to).
+
+2. Select the **Clusters** link on the left to navigate to the [Clusters](https://portal.biganimal.com/clusters) page.
+
+3. Select the **Create New Cluster** button.
+
+You should now find yourself at the [Create Cluster page](https://portal.biganimal.com/create-cluster).
+
+## Configuring a new cluster
+
+### The Cluster Settings tab
+
+In the free trial, the range of cluster options is somewhat limited but should be more than sufficient for demonstrating the capabilities of BigAnimal. 
+
+1. Use **Cluster Name** to describe the purpose of the cluster. For example, "Test for Advanced Server on AWS."
+2. **Password** is the admin password for the cluster, so pick a strong one! Note that this is independent of your EDB account.
+3. **Database Type** is one of:
+
+   - **EnterpriseDB PostgreSQL Advanced Server** for Oracle database compatibility
+   - **PostgreSQL** for official community builds of standard PostgreSQL
+
+    So if you're interested in EDB's enhancements to PostgreSQL for Oracle database compatibility, choose Advanced Server; otherwise, choose PostgreSQL.
+4. **Postgres Version** allows you to select from among the supported versions for either database type.
+4. **Provider** is either AWS or Azure; BigAnimal works the same on either one, so choose the one you're familiar with.
+5. **Region** options depend on the provider you chose; pick the one closest to you.
+6. **Network Connectivity** is restricted to a public IP for the trial, but you can restrict access to trusted networks by
+   selecting the **Use allowlists to restrict network access** check box and specifying one or more [CIDR blocks](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) 
+   to allow access from.
+
+For **Instance Type** and **Storage**, only one option is available for each field during the trial, so just choose that.
+
+### The DB Configuration tab
+
+This is entirely optional, but if you're curious, you can find a full set of PostgreSQL configuration options on this tab, allowing you to tune a cluster for specific needs or resource constraints.
+
+### The Availability tab
+
+This page configures high availability, but that feature isn't available in the trial. Skip this tab unless you're curious.
+
+## Provisioning 
+
+Select **Create Cluster**, and you're brought back to the Clusters page with your newly configured cluster now populating the list.
+
+Initially, the new cluster is being provisioned. This usually takes a minute or two but can take up to an hour. A progress bar is shown near the right.
+
+Once your first cluster is fully provisioned, your 14-day free trial officially starts, and a countdown appears telling you how many days are left in your trial.
+
+Select the provisioned cluster to view the parameters you'll need to connect to it.
+
+## Next steps
+
+[Connect to your cluster](../connect_to_a_cluster)
+
+## Further reading
+
+[Creating a cluster](/biganimal/latest/getting_started/creating_a_cluster/) in the full version documentation.

product_docs/docs/biganimal/release/free_trial/detail/create_a_cluster/index.mdx

@@ -0,0 +1,19 @@
+---
+title: "Create a cluster"
+description: "Creating a BigAnimal cluster from the portal or the command line"
+indexCards: none
+---
+
+The BigAnimal free trial allows one active cluster. If you want to try another configuration, you'll need to delete your active cluster. Thankfully, it's also quick and easy to [restore your deleted cluster from a backup](../experiment/backup_and_restore/) if you need to later on. Backups are automatically created as soon as a cluster is used.
+
+When you create a cluster, there are two flavors of PostgreSQL to choose from:
+
+- All supported versions of [open-source PostgreSQL](supported-open-source/postgresql/), including [PostgreSQL 14](https://www.postgresql.org/about/news/postgresql-14-released-2318/).
+- [EDB Postgres Advanced Server](/epas/latest/), which augments open-source PostgreSQL with [Oracle compatibility](/epas/latest/epas_compat_ora_dev_guide/), among other features.
+
+We'll demonstrate two methods of creating a cluster:
+
+- [Using the portal](create_cluster_portal)
+- [Using the command line](create_cluster_cli)
+
+Clusters can also be created programmatically using the [fully featured BigAnimal API](/biganimal/latest/reference/api/).