Update simple CRUD examples with ccloud option (cockroachdb#14496)

* Update simple CRUD examples with ccloud option * Apply suggestions from Gemma's review Co-authored-by: Gemma Shay <[email protected]> * Changing beta to Preview.
dhartunian · Jul 27, 2022 · 27d13bb · 27d13bb
1 parent b6fed84
commit 27d13bb
Show file tree

Hide file tree

Showing 18 changed files with 367 additions and 89 deletions.
diff --git a/_includes/cockroachcloud/ccloud/quickstart.md b/_includes/cockroachcloud/ccloud/quickstart.md
@@ -5,7 +5,7 @@ The easiest way of getting started with CockroachDB Cloud is to use `ccloud quic
 ccloud quickstart
 ~~~
 
-The `ccloud quickstart` command will open a browser window to log you in to CockroachDB Cloud. If you are new to CockroachDB Cloud, you can register using one of the single sign-on(SSO) options, or create a new account using an email address.
+The `ccloud quickstart` command will open a browser window to log you in to CockroachDB Cloud. If you are new to CockroachDB Cloud, you can register using one of the single sign-on (SSO) options, or create a new account using an email address.
 
 The `ccloud quickstart` command will prompt you for the cluster name, cloud provider, and cloud provider region, then ask if you want to connect to the cluster. Each prompt has default values that you can select, or change if you want a different option.
 
diff --git a/_includes/v22.1/setup/init-bank-sample.md b/_includes/v22.1/setup/init-bank-sample.md
@@ -16,7 +16,7 @@
     export DATABASE_URL="{connection-string}"
     ~~~
 
-    Where `{connection-string}` is the connection string you obtained from the {{ site.data.products.db }} Console.
+    Where `{connection-string}` is the connection string you copied earlier.
 
     </section>
 

diff --git a/_includes/v22.1/setup/sample-setup-certs.md b/_includes/v22.1/setup/sample-setup-certs.md
@@ -4,7 +4,19 @@
   <button class="filter-button page-level" data-scope="local">Use a Local Cluster</button>
 </div>
 
-<section class="filter-content" markdown="1" data-scope="cockroachcloud">
+<div class="filter-content" markdown="1" data-scope="cockroachcloud">
+
+
+<h3>Choose your installation method</h3>
+
+You can create a {{ site.data.products.serverless }} cluster using either the CockroachDB Cloud Console, a web-based graphical user interface (GUI) tool, or <code>ccloud</code>, a command-line interface (CLI) tool.
+
+<div class="filters clearfix">
+    <button class="filter-button page-level" data-scope="console">Use the Cloud Console (GUI)<strong></strong></button>
+    <button class="filter-button page-level" data-scope="ccloud"><strong>Use <code>ccloud</code> (CLI)</strong></button>
+</div>
+
+<div class="filter-content" markdown="1" data-scope="console">
 
 ### Create a free cluster
 
@@ -29,7 +41,35 @@ Open the **General connection string** section, then copy the connection string
 The connection string is pre-populated with your username, password, cluster name, and other details. Your password, in particular, will be provided *only once*. Save it in a secure place (Cockroach Labs recommends a password manager) to connect to your cluster in the future. If you forget your password, you can reset it by going to the [**SQL Users** page](../cockroachcloud/user-authorization.html).
 {{site.data.alerts.end}}
 
-</section>
+</div>
+
+<div class="filter-content" markdown="1" data-scope="ccloud">
+
+Follow these steps to create a {{ site.data.products.serverless }} cluster using the <code>ccloud</code> CLI tool.
+
+{{site.data.alerts.callout_info}}
+The <code>ccloud</code> CLI tool is in Preview.
+{{site.data.alerts.end}}
+
+<h3>Install <code>ccloud</code></h3>
+
+{% include cockroachcloud/ccloud/install-ccloud.md %}
+
+### Run `ccloud quickstart` to create a new cluster, create a SQL user, and retrieve the connection string.
+
+{% include cockroachcloud/ccloud/quickstart.md %}
+
+Select **General connection string**, then copy the connection string displayed and save it in a secure location. The connection string is the line starting `postgresql://`.
+
+~~~
+? How would you like to connect? General connection string
+Retrieving cluster info: succeeded
+ Downloading cluster cert to /Users/maxroach/.postgresql/root.crt: succeeded
+postgresql://maxroach:ThisIsNotAGoodPassword@free-tier4.aws-us-west-2.cockroachlabs.cloud:26257/defaultdb?options=--cluster%3Ddim-dog-147&sslmode=verify-full&sslrootcert=%2FUsers%2Fmaxroach%2F.postgresql%2Froot.crt
+~~~
+</div>
+
+</div>
 
 <section class="filter-content" markdown="1" data-scope="local">
 

diff --git a/_includes/v22.1/setup/sample-setup-jdbc.md b/_includes/v22.1/setup/sample-setup-jdbc.md
@@ -0,0 +1,74 @@
+
+<div class="filters clearfix">
+  <button class="filter-button page-level" data-scope="cockroachcloud">Use {{ site.data.products.serverless }}</button>
+  <button class="filter-button page-level" data-scope="local">Use a Local Cluster</button>
+</div>
+
+<div class="filter-content" markdown="1" data-scope="cockroachcloud">
+
+<h3>Choose your installation method</h3>
+
+You can create a {{ site.data.products.serverless }} cluster using either the CockroachDB Cloud Console, a web-based graphical user interface (GUI) tool, or <code>ccloud</code>, a command-line interface (CLI) tool.
+
+<div class="filters clearfix">
+    <button class="filter-button page-level" data-scope="console">Use the Cloud Console (GUI)<strong></strong></button>
+    <button class="filter-button page-level" data-scope="ccloud"><strong>Use <code>ccloud</code> (CLI)</strong></button>
+</div>
+
+<div class="filter-content" markdown="1" data-scope="console">
+
+### Create a free cluster
+
+{% include {{ page.version.version }}/setup/create-a-free-cluster.md %}
+
+### Create a SQL user
+
+{% include {{ page.version.version }}/setup/create-first-sql-user.md %}
+
+### Get the connection string
+
+The **Connect to cluster** dialog shows information about how to connect to your cluster.
+
+1. Select **Java** from the **Select option/language** dropdown.
+1. Select **JDBC** from the **Select tool** dropdown.
+1. Copy the command provided to set the `JDBC_DATABASE_URL` environment variable.
+
+    {{site.data.alerts.callout_info}}
+    The JDBC connection URL is pre-populated with your username, password, cluster name, and other details. Your password, in particular, will be provided *only once*. Save it in a secure place (Cockroach Labs recommends a password manager) to connect to your cluster in the future. If you forget your password, you can reset it by going to the [**SQL Users** page](../cockroachcloud/user-authorization.html).
+    {{site.data.alerts.end}}
+
+</div>
+
+<div class="filter-content" markdown="1" data-scope="ccloud">
+
+Follow these steps to create a {{ site.data.products.serverless }} cluster using the <code>ccloud</code> CLI tool.
+
+{{site.data.alerts.callout_info}}
+The <code>ccloud</code> CLI tool is in Preview.
+{{site.data.alerts.end}}
+
+<h3>Install <code>ccloud</code></h3>
+
+{% include cockroachcloud/ccloud/install-ccloud.md %}
+
+### Run `ccloud quickstart` to create a new cluster, create a SQL user, and retrieve the connection string.
+
+{% include cockroachcloud/ccloud/quickstart.md %}
+
+Select **General connection string**, then copy the connection string displayed and save it in a secure location. The connection string is the line starting `postgresql://`.
+
+~~~
+? How would you like to connect? General connection string
+Retrieving cluster info: succeeded
+ Downloading cluster cert to /Users/maxroach/.postgresql/root.crt: succeeded
+postgresql://maxroach:ThisIsNotAGoodPassword@free-tier4.aws-us-west-2.cockroachlabs.cloud:26257/defaultdb?options=--cluster%3Ddim-dog-147&sslmode=verify-full&sslrootcert=%2FUsers%2Fmaxroach%2F.postgresql%2Froot.crt
+~~~
+</div>
+
+</div>
+
+<section class="filter-content" markdown="1" data-scope="local">
+
+{% include {{ page.version.version }}/setup/start-single-node-insecure.md %}
+
+</section>
diff --git a/_includes/v22.1/setup/sample-setup-parameters-certs.md b/_includes/v22.1/setup/sample-setup-parameters-certs.md
@@ -4,7 +4,19 @@
   <button class="filter-button page-level" data-scope="local">Use a Local Cluster</button>
 </div>
 
-<section class="filter-content" markdown="1" data-scope="cockroachcloud">
+<div class="filter-content" markdown="1" data-scope="cockroachcloud">
+
+
+<h3>Choose your installation method</h3>
+
+You can install a {{ site.data.products.serverless }} cluster using either the CockroachDB Cloud Console, a web-based graphical user interface (GUI) tool, or <code>ccloud</code>, a command-line interface (CLI) tool.
+
+<div class="filters clearfix">
+    <button class="filter-button page-level" data-scope="console">Use the Cloud Console (GUI)<strong></strong></button>
+    <button class="filter-button page-level" data-scope="ccloud"><strong>Use <code>ccloud</code> (CLI)</strong></button>
+</div>
+
+<div class="filter-content" markdown="1" data-scope="console">
 
 ### Create a free cluster
 
@@ -26,7 +38,46 @@ The **Connect to cluster** dialog shows information about how to connect to your
 1. Select **Parameters only** from the **Select option** dropdown.
 1. Copy the connection information for each parameter displayed and save it in a secure location.
 
-</section>
+</div>
+
+<div class="filter-content" markdown="1" data-scope="ccloud">
+
+Follow these steps to create a {{ site.data.products.serverless }} cluster using the <code>ccloud</code> CLI tool.
+
+{{site.data.alerts.callout_info}}
+The <code>ccloud</code> CLI tool is in Preview.
+{{site.data.alerts.end}}
+
+<h3>Install <code>ccloud</code></h3>
+
+{% include cockroachcloud/ccloud/install-ccloud.md %}
+
+### Run `ccloud quickstart` to create a new cluster, create a SQL user, and retrieve the connection string.
+
+{% include cockroachcloud/ccloud/quickstart.md %}
+
+Select **Parameters only** then copy the connection parameters displayed and save them in a secure location.
+
+~~~
+? How would you like to connect? Parameters only
+Looking up cluster ID: succeeded
+Creating SQL user: succeeded
+Success! Created SQL user
+ name: maxroach
+ cluster: 37174250-b944-461f-b1c1-3a99edb6af32
+Retrieving cluster info: succeeded
+Connection parameters
+ Database:  defaultdb
+ Host:      free-tier4.aws-us-west-2.cockroachlabs.cloud
+ Options:   --cluster=dim-dog-147
+ Password:  ThisIsNotAGoodPassword
+ Port:      26257
+ Username:  maxroach
+~~~
+
+</div>
+
+</div>
 
 <section class="filter-content" markdown="1" data-scope="local">
 

diff --git a/_includes/v22.1/setup/sample-setup-parameters.md b/_includes/v22.1/setup/sample-setup-parameters.md
@@ -4,7 +4,18 @@
   <button class="filter-button page-level" data-scope="local">Use a Local Cluster</button>
 </div>
 
-<section class="filter-content" markdown="1" data-scope="cockroachcloud">
+<div class="filter-content" markdown="1" data-scope="cockroachcloud">
+
+<h3>Choose your installation method</h3>
+
+You can install a {{ site.data.products.serverless }} cluster using either the CockroachDB Cloud Console, a web-based graphical user interface (GUI) tool, or <code>ccloud</code>, a command-line interface (CLI) tool.
+
+<div class="filters clearfix">
+    <button class="filter-button page-level" data-scope="console">Use the Cloud Console (GUI)<strong></strong></button>
+    <button class="filter-button page-level" data-scope="ccloud"><strong>Use <code>ccloud</code> (CLI)</strong></button>
+</div>
+
+<div class="filter-content" markdown="1" data-scope="console">
 
 ### Create a free cluster
 
@@ -21,7 +32,46 @@ The **Connect to cluster** dialog shows information about how to connect to your
 1. Select **Parameters only** from the **Select option** dropdown.
 1. Copy the connection information for each parameter displayed and save it in a secure location.
 
-</section>
+</div>
+
+<div class="filter-content" markdown="1" data-scope="ccloud">
+
+Follow these steps to create a {{ site.data.products.serverless }} cluster using the <code>ccloud</code> CLI tool.
+
+{{site.data.alerts.callout_info}}
+The <code>ccloud</code> CLI tool is in Preview.
+{{site.data.alerts.end}}
+
+<h3>Install <code>ccloud</code></h3>
+
+{% include cockroachcloud/ccloud/install-ccloud.md %}
+
+### Run `ccloud quickstart` to create a new cluster, create a SQL user, and retrieve the connection string.
+
+{% include cockroachcloud/ccloud/quickstart.md %}
+
+Select **Parameters only** then copy the connection parameters displayed and save them in a secure location.
+
+~~~
+? How would you like to connect? Parameters only
+Looking up cluster ID: succeeded
+Creating SQL user: succeeded
+Success! Created SQL user
+ name: maxroach
+ cluster: 37174250-b944-461f-b1c1-3a99edb6af32
+Retrieving cluster info: succeeded
+Connection parameters
+ Database:  defaultdb
+ Host:      free-tier4.aws-us-west-2.cockroachlabs.cloud
+ Options:   --cluster=dim-dog-147
+ Password:  ThisIsNotAGoodPassword
+ Port:      26257
+ Username:  maxroach
+~~~
+
+</div>
+
+</div>
 
 <section class="filter-content" markdown="1" data-scope="local">
 

diff --git a/_includes/v22.1/setup/sample-setup.md b/_includes/v22.1/setup/sample-setup.md
@@ -4,7 +4,18 @@
   <button class="filter-button page-level" data-scope="local">Use a Local Cluster</button>
 </div>
 
-<section class="filter-content" markdown="1" data-scope="cockroachcloud">
+<div class="filter-content" markdown="1" data-scope="cockroachcloud">
+
+<h3>Choose your installation method</h3>
+
+You can install a {{ site.data.products.serverless }} cluster using either the CockroachDB Cloud Console, a web-based graphical user interface (GUI) tool, or <code>ccloud</code>, a command-line interface (CLI) tool.
+
+<div class="filters clearfix">
+    <button class="filter-button page-level" data-scope="console">Use the Cloud Console (GUI)<strong></strong></button>
+    <button class="filter-button page-level" data-scope="ccloud"><strong>Use <code>ccloud</code> (CLI)</strong></button>
+</div>
+
+<div class="filter-content" markdown="1" data-scope="console">
 
 ### Create a free cluster
 
@@ -27,7 +38,35 @@ The **Connect to cluster** dialog shows information about how to connect to your
     The connection string is pre-populated with your username, password, cluster name, and other details. Your password, in particular, will be provided *only once*. Save it in a secure place (Cockroach Labs recommends a password manager) to connect to your cluster in the future. If you forget your password, you can reset it by going to the [**SQL Users** page](../cockroachcloud/user-authorization.html).
     {{site.data.alerts.end}}
 
-</section>
+</div>
+
+<div class="filter-content" markdown="1" data-scope="ccloud">
+
+Follow these steps to create a {{ site.data.products.serverless }} cluster using the <code>ccloud</code> CLI tool.
+
+{{site.data.alerts.callout_info}}
+The <code>ccloud</code> CLI tool is in Preview.
+{{site.data.alerts.end}}
+
+<h3>Install <code>ccloud</code></h3>
+
+{% include cockroachcloud/ccloud/install-ccloud.md %}
+
+### Run `ccloud quickstart` to create a new cluster, create a SQL user, and retrieve the connection string.
+
+{% include cockroachcloud/ccloud/quickstart.md %}
+
+Select **General connection string**, then copy the connection string displayed and save it in a secure location. The connection string is the line starting `postgresql://`.
+
+~~~
+? How would you like to connect? General connection string
+Retrieving cluster info: succeeded
+ Downloading cluster cert to /Users/maxroach/.postgresql/root.crt: succeeded
+postgresql://maxroach:ThisIsNotAGoodPassword@free-tier4.aws-us-west-2.cockroachlabs.cloud:26257/defaultdb?options=--cluster%3Ddim-dog-147&sslmode=verify-full&sslrootcert=%2FUsers%2Fmaxroach%2F.postgresql%2Froot.crt
+~~~
+</div>
+
+</div>
 
 <section class="filter-content" markdown="1" data-scope="local">
 

diff --git a/cockroachcloud/quickstart.md b/cockroachcloud/quickstart.md
@@ -61,7 +61,7 @@ Follow these steps to create a {{ site.data.products.serverless }} cluster using
 Follow these steps to create a {{ site.data.products.serverless }} cluster using the <code>ccloud</code> CLI tool.
 
 {{site.data.alerts.callout_info}}
-The <code>ccloud</code> CLI tool is in beta.
+The <code>ccloud</code> CLI tool is in Preview.
 {{site.data.alerts.end}}
 
 <h2>Install <code>ccloud</code></h2>

diff --git a/v22.1/build-a-go-app-with-cockroachdb-gorm.md b/v22.1/build-a-go-app-with-cockroachdb-gorm.md
@@ -49,7 +49,36 @@ The `main.go` file defines an `Account` struct that maps to a new `accounts` tab
 CockroachDB may require the [client to retry a transaction](transactions.html#transaction-retries) in the case of read/write contention. The [CockroachDB Go client](https://github.com/cockroachdb/cockroach-go) includes a generic **retry function** (`ExecuteTx()`) that runs inside a transaction and retries it as needed. The code sample shows how you can use this function to wrap SQL statements.
 {{site.data.alerts.end}}
 
-## Step 3. Run the code
+## Step 3. Initialize the database
+
+1. Navigate to the `example-app-go-gorm` directory:
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ shell
+    $ cd example-app-go-pgx
+    ~~~
+
+1. Set the `DATABASE_URL` environment variable to the connection string for your cluster:
+
+    <section class="filter-content" markdown="1" data-scope="local">
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ shell
+    export DATABASE_URL="postgresql://root@localhost:26257?sslmode=disable"
+    ~~~
+
+    </section>
+
+    <section class="filter-content" markdown="1" data-scope="cockroachcloud">
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ shell
+    export DATABASE_URL="{connection-string}"
+    ~~~
+
+    Where `{connection-string}` is the connection string you copied earlier.
+
+## Step 4. Run the code
 
 1. Initialize the module: