Updated db initialization workflow, copied to 20.2, 21.2 (cockroachdb…

…#11107)

* Updated db initialization workflow, copied to 20.2, 21.2

* Updated db initialization command for windows compatibility

_includes/sidebar-data-v20.2.json

@@ -430,6 +430,12 @@
                       "/${VERSION}/hello-world-java-jdbc.html"
                     ]
                   },
+                  {
+                    "title": "JavaScript (Node.js)",
+                    "urls": [
+                      "/${VERSION}/hello-world-node-postgres.html"
+                    ]
+                  },
                   {
                     "title": "Python",
                     "urls": [

_includes/sidebar-data-v21.2.json

@@ -442,6 +442,12 @@
                       "/${VERSION}/hello-world-java-jdbc.html"
                     ]
                   },
+                  {
+                    "title": "JavaScript (Node.js)",
+                    "urls": [
+                      "/${VERSION}/hello-world-node-postgres.html"
+                    ]
+                  },
                   {
                     "title": "Python",
                     "urls": [

_includes/v20.2/app/init-bank-sample.md

@@ -0,0 +1,53 @@
+
+To initialize the example database, use the [`cockroach sql`](cockroach-sql.html) command to execute the SQL statements in the `dbinit.sql` file:
+
+{% include_cached copy-clipboard.html %}
+~~~ shell
+cat dbinit.sql | cockroach sql --url "<connection-string>"
+~~~
+
+Where `<connection-string>` is the connection string to the running cluster.
+
+<div class="filter-content" markdown="1" data-scope="cockroachcloud">
+
+{{site.data.alerts.callout_success}}
+Use the connection string you obtained earlier from the CockroachCloud Console.
+{{site.data.alerts.end}}
+
+</div>
+
+<div class="filter-content" markdown="1" data-scope="local">
+
+{{site.data.alerts.callout_success}}
+Use the connection string you obtained earlier from the `cockroach demo` welcome text.
+{{site.data.alerts.end}}
+
+</div>
+
+The SQL statements in the initialization file should execute:
+
+~~~
+SET
+
+Time: 1ms
+
+SET
+
+Time: 2ms
+
+DROP DATABASE
+
+Time: 1ms
+
+CREATE DATABASE
+
+Time: 2ms
+
+SET
+
+Time: 10ms
+
+CREATE TABLE
+
+Time: 4ms
+~~~

_includes/v21.1/app/init-bank-sample.md

@@ -0,0 +1,53 @@
+
+To initialize the example database, use the [`cockroach sql`](cockroach-sql.html) command to execute the SQL statements in the `dbinit.sql` file:
+
+{% include_cached copy-clipboard.html %}
+~~~ shell
+cat dbinit.sql | cockroach sql --url "<connection-string>"
+~~~
+
+Where `<connection-string>` is the connection string to the running cluster.
+
+<div class="filter-content" markdown="1" data-scope="cockroachcloud">
+
+{{site.data.alerts.callout_success}}
+Use the connection string you obtained earlier from the CockroachCloud Console.
+{{site.data.alerts.end}}
+
+</div>
+
+<div class="filter-content" markdown="1" data-scope="local">
+
+{{site.data.alerts.callout_success}}
+Use the connection string you obtained earlier from the `cockroach demo` welcome text.
+{{site.data.alerts.end}}
+
+</div>
+
+The SQL statements in the initialization file should execute:
+
+~~~
+SET
+
+Time: 1ms
+
+SET
+
+Time: 2ms
+
+DROP DATABASE
+
+Time: 1ms
+
+CREATE DATABASE
+
+Time: 2ms
+
+SET
+
+Time: 10ms
+
+CREATE TABLE
+
+Time: 4ms
+~~~

_includes/v21.2/app/init-bank-sample.md

@@ -0,0 +1,53 @@
+
+To initialize the example database, use the [`cockroach sql`](cockroach-sql.html) command to execute the SQL statements in the `dbinit.sql` file:
+
+{% include_cached copy-clipboard.html %}
+~~~ shell
+cat dbinit.sql | cockroach sql --url "<connection-string>"
+~~~
+
+Where `<connection-string>` is the connection string to the running cluster.
+
+<div class="filter-content" markdown="1" data-scope="cockroachcloud">
+
+{{site.data.alerts.callout_success}}
+Use the connection string you obtained earlier from the CockroachCloud Console.
+{{site.data.alerts.end}}
+
+</div>
+
+<div class="filter-content" markdown="1" data-scope="local">
+
+{{site.data.alerts.callout_success}}
+Use the connection string you obtained earlier from the `cockroach demo` welcome text.
+{{site.data.alerts.end}}
+
+</div>
+
+The SQL statements in the initialization file should execute:
+
+~~~
+SET
+
+Time: 1ms
+
+SET
+
+Time: 2ms
+
+DROP DATABASE
+
+Time: 1ms
+
+CREATE DATABASE
+
+Time: 2ms
+
+SET
+
+Time: 10ms
+
+CREATE TABLE
+
+Time: 4ms
+~~~

v20.2/build-a-nodejs-app-with-cockroachdb.md

@@ -1,104 +1,164 @@
 ---
-title: Build a Node.js App with CockroachDB and the Node.js pg Driver
-summary: Learn how to use CockroachDB from a simple Node.js application with the Node.js pg driver.
+title: Build a Simple CRUD Node.js App with CockroachDB and the node-postgres Driver
+summary: Learn how to use CockroachDB from a simple CRUD application that uses the node-postgres driver.
 toc: true
 twitter: false
 referral_id: docs_hello_world_nodejs_pg
 ---
 
 <div class="filters filters-big clearfix">
-    <a href="build-a-nodejs-app-with-cockroachdb.html"><button class="filter-button current">Use <strong>pg</strong></button></a>
+    <a href="build-a-nodejs-app-with-cockroachdb.html"><button class="filter-button current">Use <strong>node-postgres</strong></button></a>
     <a href="build-a-nodejs-app-with-cockroachdb-sequelize.html"><button class="filter-button">Use <strong>Sequelize</strong></button></a>
     <a href="build-a-typescript-app-with-cockroachdb.html"><button class="filter-button">Use <strong>TypeORM</strong></button></a>
 </div>
 
-This tutorial shows you how build a simple Node.js application with CockroachDB and the Node.js pg driver.
-
-We have tested the [Node.js pg driver](https://www.npmjs.com/package/pg) enough to claim **beta-level** support. If you encounter problems, please [open an issue](https://github.com/cockroachdb/cockroach/issues/new) with details to help us make progress toward full support.
+This tutorial shows you how build a simple Node.js application with CockroachDB and the [node-postgres driver](https://node-postgres.com/).
 
 ## Step 1. Start CockroachDB
 
-{% include {{page.version.version}}/app/start-cockroachdb.md %}
-
-## Step 2. Create a database
+<div class="filters clearfix">
+  <button class="filter-button page-level" data-scope="cockroachcloud">Use CockroachCloud</button>
+  <button class="filter-button page-level" data-scope="local">Use a Local Cluster</button>
+</div>
 
-{% include {{page.version.version}}/app/create-a-database.md %}
+<section class="filter-content" markdown="1" data-scope="cockroachcloud">
 
-## Step 3. Install client driver
+### Create a free cluster
 
-To let your application communicate with CockroachDB, install the [Node.js pg driver](https://www.npmjs.com/package/pg):
+{% include cockroachcloud/quickstart/create-a-free-cluster.md %}
 
-{% include_cached copy-clipboard.html %}
-~~~ shell
-$ npm install pg
-~~~
+### Set up your cluster connection
 
-## Step 4. Get the code
+1. Navigate to the cluster's **SQL Users** page, and create a new user, with a new password.
 
-<a href="https://raw.githubusercontent.com/cockroachlabs/example-app-node-postgres/main/app.js">Download the sample code directly</a>, or clone [the code's GitHub repository](https://github.com/cockroachlabs/example-app-node-postgres).
+1. Navigate to the **Cluster Overview page**, select **Connect**, and, under the **Connection String** tab, download the cluster certificate.
 
-## Step 5. Update the connection parameters
+1. Take note of the connection string provided. You'll use it to connect to the database later in this tutorial.
 
-Open the `app.js` file, and edit the connection configuration parameters:
+</section>
 
 <section class="filter-content" markdown="1" data-scope="local">
 
-- Replace the value for `user` with the user you created earlier.
-- Replace the value for `password` with the password you created for your user.
-- Replace the value for `port` with the port to your cluster.
+1. If you haven't already, [download the CockroachDB binary](install-cockroachdb.html).
+1. Run the [`cockroach demo`](cockroach-demo.html) command:
 
-</section>
+    {% include_cached copy-clipboard.html %}
+    ~~~ shell
+    $ cockroach demo \
+    --empty
+    ~~~
 
-<section class="filter-content" markdown="1" data-scope="cockroachcloud">
+    This starts a temporary, in-memory cluster and opens an interactive SQL shell to the cluster. Any changes to the database will not persist after the cluster is stopped.
+1. Take note of the `(sql)` connection string in the SQL shell welcome text:
 
-- At the top of the file, uncomment the `const fs = require('fs');` line.
+    ~~~
+    # Connection parameters:
+    #   (console) http://127.0.0.1:53930
+    #   (sql)     postgres://root:admin@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo777666364&port=26257
+    #   (sql/tcp) postgres://root:[email protected]:53932?sslmode=require
+    ~~~
 
-    This line imports the `fs` Node module, which enables you to read in the CA cert that you downloaded from the CockroachCloud Console.
-- Replace the value for `user` with the user you created earlier.
-- Replace the value for `password` with the password you created for your user.
-- Replace the value for `host` with the name of the CockroachCloud Free host (e.g., `host: 'free-tier.gcp-us-central1.cockroachlabs.cloud'`).
-- Replace the value for `port` with the port to your cluster.
-- Replace the value for `database` with the database that you created earlier, suffixed with the name of the cluster (e.g., `database: '{cluster_name}.bank'`).
-- Remove the existing `ssl` object and its contents.
-- Uncomment the `ssl` object with the `ca` key-value pair, and edit the `fs.readFileSync('/certs/ca.crt').toString()` call to use the path to the `cc-ca.crt` file that you downloaded from the CockroachCloud Console.
+    You'll use this connection string to connect to the database later in this tutorial.
 
 </section>
 
-## Step 6. Run the code
+## Step 2. Get the code
 
-The sample code creates a table, inserts some rows, and then reads and updates values as an atomic [transaction](transactions.html).
+Clone the code's GitHub repo:
 
-Here are the contents of `app.js`:
+{% include_cached copy-clipboard.html %}
+~~~ shell
+$ git clone https://github.com/cockroachlabs/example-app-node-postgres
+~~~
+
+The project has the following directory structure:
+
+~~~
+├── README.md
+├── app.js
+├── dbinit.sql
+└── package.json
+~~~
+
+The `dbinit.sql` file initializes the database schema that the application uses:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+{% remote_include https://raw.githubusercontent.com/cockroachlabs/example-app-node-postgres/main/dbinit.sql %}
+~~~
+
+The `app.js` file contains the code for `INSERT`, `SELECT`, `UPDATE`, and `DELETE` SQL operations:
 
 {% include_cached copy-clipboard.html %}
 ~~~ js
 {% remote_include https://raw.githubusercontent.com/cockroachlabs/example-app-node-postgres/main/app.js %}
 ~~~
 
-Note that all of the database operations are wrapped in the `retryTxn` function. This function attempts to commit statements in the context of an explicit transaction. If a [retry error](transaction-retry-error-reference.html) is thrown, the wrapper will retry committing the transaction, with [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff), until the maximum number of retries is reached (by default, 15).
+All of the database operations are wrapped in a helper function named `retryTxn`. This function attempts to commit statements in the context of an explicit transaction. If a [retry error](transaction-retry-error-reference.html) is thrown, the wrapper will retry committing the transaction, with [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff), until the maximum number of retries is reached (by default, 15).
+
+## Step 3. Initialize the database
 
-To run the code:
+{% include {{ page.version.version }}/app/init-bank-sample.md %}
+
+## Step 4. Run the code
+
+Initialize and run the app:
+
+{% include_cached copy-clipboard.html %}
+~~~ shell
+$ npm install
+~~~
 
 {% include_cached copy-clipboard.html %}
 ~~~ shell
 $ node app.js
 ~~~
 
-The output should be:
+The program will prompt you for a connection string to the database:
 
 ~~~
-Initializing table...
+prompt: connectionString:
+~~~
+
+<section class="filter-content" markdown="1" data-scope="local">
+
+Enter the `(sql)` connection URL provided in the demo cluster's SQL shell welcome text.
+
+</section>
+
+<section class="filter-content" markdown="1" data-scope="cockroachcloud">
+
+Enter the connection string provided in the **Connection info** window of the CockroachCloud Console.
+
+{{site.data.alerts.callout_info}}
+You need to provide a SQL user password in order to securely connect to a CockroachCloud cluster. The connection string should have a placeholder for the password (`<ENTER-PASSWORD>`).
+{{site.data.alerts.end}}
+
+</section>
+
+After entering the connection string, the program will execute.
+
+The output should look like this:
+
+~~~
+Initializing accounts table...
 New account balances:
-{ id: '1', balance: '1000' }
-{ id: '2', balance: '250' }
+{ id: 'aa0e9b22-0c23-469b-a9e1-b2ace079f44c', balance: '1000' }
+{ id: 'bf8b96da-2c38-4d55-89a0-b2b6ed63ff9e', balance: '0' }
+{ id: 'e43d76d6-388e-4ee6-8b73-a063a63a2138', balance: '250' }
 Transferring funds...
 New account balances:
-{ id: '1', balance: '900' }
-{ id: '2', balance: '350' }
+{ id: 'aa0e9b22-0c23-469b-a9e1-b2ace079f44c', balance: '900' }
+{ id: 'bf8b96da-2c38-4d55-89a0-b2b6ed63ff9e', balance: '0' }
+{ id: 'e43d76d6-388e-4ee6-8b73-a063a63a2138', balance: '350' }
+Deleting a row...
+New account balances:
+{ id: 'aa0e9b22-0c23-469b-a9e1-b2ace079f44c', balance: '900' }
+{ id: 'e43d76d6-388e-4ee6-8b73-a063a63a2138', balance: '350' }
 ~~~
 
 ## What's next?
 
-Read more about using the [Node.js pg driver](https://www.npmjs.com/package/pg).
+Read more about using the [node-postgres driver](https://www.npmjs.com/package/pg).
 
 {% include {{page.version.version}}/app/see-also-links.md %}