Add language-specific instructions to the "Connect to the Cluster" doc #6077

What I want to do is make the "Python" section be pre-clicked and expanded by default. But as of now, the user needs to click one of the languages to expand the sections. My research says that the reason is that the previous section ("Use the CockroachDB client") also has section selectors, and only one section selector can be "active" at a time on a page. Is this something you have seen before? Any ideas on how to fix this?

jseldess · 2019-12-03T01:36:58Z

Yes, I think you’re right. We might be able to trick things by using divs for the Mac/Linux toggles and sections for the language toggles. If that doesn’t work, I’d just remove the Mac/Linux toggles and replace those with bullets. I can track down an example or two of you need.

On Mon, Dec 2, 2019 at 8:20 PM Amruta Ranade ***@***.***> wrote: @jseldess <https://github.com/jseldess> @mjibson <https://github.com/mjibson> I need help with the formatting on this page: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/a430755e5838c1703c0bb26db7ba8d735aa70cc9/cockroachcloud/stable/cockroachcloud-connect-to-your-cluster.html#use-a-postgres-driver-or-orm What I want to do is make the "Python" section be pre-clicked and expanded by default. But as of now, the user needs to click one of the languages to expand the sections. My research says that the reason is that the previous section ("Use the CockroachDB client") also has section selectors, and only one section selector can be "active" at a time on a page. Is this something you have seen before? Any ideas on how to fix this? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#6077?email_source=notifications&email_token=ADZIH4TOLA77BWFNDTJMV5DQWWX55A5CNFSM4JR6R2OKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEFXXYWA#issuecomment-560954456>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADZIH4TN3EIRN2WRTL7W46LQWWX55ANCNFSM4JR6R2OA> .

-- Jesse Seldess VP of Education, Cockroach Labs https://www.cockroachlabs.com/

Amruta-Ranade · 2019-12-03T01:48:51Z

Hmm..the divs/sections trick didn't work. I like the idea of replacing the Mac/Linux toggles with bullet points. Going with it for now. Thanks, Jesse!

cockroach-teamcity · 2019-12-03T01:57:25Z

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/9b25bc88eb6eafa0ad3a09c09b4936aa7953cab9/

Edited pages:

v19.2/cockroachcloud-connect-to-your-cluster.md

cockroach-teamcity · 2019-12-03T02:54:39Z

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/fbb085745a0dc42bf202e82d05196c519c00afe7/

Edited pages:

jseldess

Nice progress, @Amruta-Ranade. I'm a bit concerned about providing just the connection string code fragment without explicitly mentioning prerequisites, like installing the driver or ORM. I'm still wondering whether it will be more helpful to CC devs to have a full "hello world" sample from which they can easily extract the details they need. Thoughts?

If you prefer to move forward with this approach for now, I'd like you to have a developer run through this for real, pretending to be a beginner, before I give my review.

Some other issues issues:

Reading through, it's strange to me that step 3 (generating the connection string) is not in the context of step 4 (connect to the cluster). You need to choose specific options in step 3 for step 4. Can you think about this more?
I think all of the bullets nested under number steps are not rendering correctly.

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @jseldess)

laurenbarker

Everything worked as expected!
(also worth noting that this is the first time I've connected to one of my dbs)

For the "Use a Postgres driver or ORM" step I followed the "Node.js pg driver" instructions to test it out. The actual code I used:

// connect-test.js

const fs = require("fs");
const { Client } = require("pg");

// copied config from tutorial and added password
const config = {...};

const client = new Client(config);

client.connect();
console.log("connected");

client.query("SELECT NOW()", (err, res) => {
  console.log(err, res);

  client.end();
  console.log("disconnected");
});

laurenbarker · 2019-12-03T19:26:18Z

v19.2/cockroachcloud-connect-to-your-cluster.md

@@ -94,7 +94,7 @@ On the machine from which you want to connect to your cluster:

    The **Connect** tab is displayed.

-    <img src="{{ 'images/v19.1/cockroachcloud/connect-tab.png' | relative_url }}" alt="Connect to cluster" style="border:1px solid #eee;max-width:100%" />
+    <img src="{{ 'images/v19.2/cockroachcloud/connect-tab.png' | relative_url }}" alt="Connect to cluster" style="border:1px solid #eee;max-width:50%" />

 6. Select a connection option:


The order of the tabs on the connection modal has recently been updated (CockroachDB Client is the default now).

laurenbarker · 2019-12-03T19:28:10Z

v19.2/cockroachcloud-connect-to-your-cluster.md

+// Connect to the "bank" database.
+var config = {
+    user: '<username>',
+    host: '<region>.<cluster_name>',


I think my host was <cluster_name>.<region>

Oh..that's strange. Our parameter tab displays the <region_name>.<cluster_name> format.

Can you confirm what should the correct format?

Oh interesting...mine is the opposite. Maybe just <host> then?

Woah..that's weird! Let's ask on Slack if this is an issue or if it's okay to have two formats.

Confirmed: Both are correct, but differ based on version. <host> might be the safest way to go.

laurenbarker · 2019-12-03T19:33:08Z

v19.2/cockroachcloud-connect-to-your-cluster.md

+~~~ js
+// Connect to CockroachDB through Sequelize.
+var sequelize = new Sequelize('<database_name>', '<username>', '<password>', {
+    host: '<region>.<cluster_name>',


Same here --<cluster_name>.<region>

laurenbarker · 2019-12-03T19:33:29Z

v19.2/cockroachcloud-connect-to-your-cluster.md

+conn = psycopg2.connect(
+    user='<username>',
+    password='<password>',
+    host='<region>.<cluster_name>',


Same here --<cluster_name>.<region>

laurenbarker · 2019-12-03T19:34:43Z

v19.2/cockroachcloud-connect-to-your-cluster.md

-On the machine where you want to run your application:
+# Create an engine to communicate with the database. The "cockroachdb://" prefix
+# for the engine URL indicates that we are connecting to CockroachDB.
+engine = create_engine('cockroachdb://<username>:<password>@<region>.<cluster_name>:26257/<database>?sslmode=verify-full&sslrootcert=<absolute path to CA certificate>')


Same here --<cluster_name>.<region>

laurenbarker · 2019-12-03T19:34:59Z

v19.2/cockroachcloud-connect-to-your-cluster.md

+~~~ go
+
+  // Connect to the database.
+    const addr = "postgresql://<username>:<password>@<region>.<cluster_name>:26257/<database>?sslmode=verify-full&sslrootcert=<absolute path to CA certificate>"


Same here --<cluster_name>.<region>

laurenbarker · 2019-12-03T19:35:10Z

v19.2/cockroachcloud-connect-to-your-cluster.md

-    2. Run the code:
+// Configure the database connection.
+        PGSimpleDataSource ds = new PGSimpleDataSource();
+        ds.setServerName("<region>.<cluster_name>");


Same here --<cluster_name>.<region>

laurenbarker · 2019-12-03T19:35:22Z

v19.2/cockroachcloud-connect-to-your-cluster.md

+    //Database connection settings
+        <property name="hibernate.connection.driver_class">org.postgresql.Driver</property>
+         <property name="hibernate.dialect">org.hibernate.dialect.PostgreSQL95Dialect</property>
+        <property name="hibernate.connection.url"><![CDATA[jdbc:postgresql://<username>:<password>@<region>.<cluster_name>:26257/<database>?sslmode=verify-full&sslrootcert=<absolute path to CA certificate]]></property>


Same here --<cluster_name>.<region>

laurenbarker · 2019-12-03T19:36:52Z

v19.2/cockroachcloud-connect-to-your-cluster.md

-    {{site.data.alerts.callout_info}}
-    The [CockroachDB Python package](https://github.com/cockroachdb/cockroachdb-python) installed earlier is triggered by the `cockroachdb://` prefix in the engine URL. Using `postgres://` to connect to your cluster will not work.
-    {{site.data.alerts.end}}
+// Connect to the "bank" database.


What does "bank" database mean?

Ah..included it by mistake. Fixed.

laurenbarker · 2019-12-03T19:37:32Z

v19.2/cockroachcloud-connect-to-your-cluster.md

-    The [CockroachDB Python package](https://github.com/cockroachdb/cockroachdb-python) installed earlier is triggered by the `cockroachdb://` prefix in the engine URL. Using `postgres://` to connect to your cluster will not work.
-    {{site.data.alerts.end}}
+// Connect to the "bank" database.
+var config = {


I had to add password to the config to get it to connect.

Yep. Good catch. Fixed.

laurenbarker · 2019-12-03T19:52:26Z

v19.2/cockroachcloud-connect-to-your-cluster.md

    {% include copy-clipboard.html %}
    ~~~ shell
    $ sudo cp -i cockroach-{{ page.release_info.version }}.linux-amd64/cockroach /usr/local/bin/
    ~~~
-    </section>

 3. Use the `cockroach sql` command to open an interactive SQL shell, replacing placeholders in the [client connection string](#step-3-generate-the-connection-string) with the correct username, password, and path to the `ca.cert`:


Forgot one. Looks like the connection strings below missed the certs/ca.crt to <path to the CA certificate> update.

Amruta-Ranade · 2019-12-03T21:24:58Z

Excellent feedback @laurenbarker! Thank you so much!

cockroach-teamcity · 2019-12-03T22:24:29Z

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/8f5b815bdb30dbe56e10a7f00fbe21952f124b8b/

Edited pages:

cockroach-teamcity · 2019-12-10T14:48:16Z

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/e4511206d70362d85e26c3de75bb543929d520c2/

Edited pages:

cockroach-teamcity · 2019-12-11T16:04:33Z

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/6dd37a7a4c0ed365abc400b89a4dd04d149264c5/

Edited pages:

cockroach-teamcity · 2020-01-04T00:54:59Z

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/6dd37a7a4c0ed365abc400b89a4dd04d149264c5/

Edited pages:

jseldess

Sorry for the delay, @Amruta-Ranade. I didn't know you were ready for a re-review. In the future, please mention me in a comment once you're ready.

LGTM, with a few nits. I still find steps 3 and 4 a bit confusing, but let's go with this for now.

Also, you

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @Amruta-Ranade and @laurenbarker)

v19.2/cockroachcloud-connect-to-your-cluster.md, line 37 at r8 (raw file):

5. From the **Network** dropdown, select:

         - **New Network** to authorize your application server’s network or application server’s network. Enter the public IPv4 address of the machine in the **Network** field.

These bullets aren't rendering properly. Please fix.

v19.2/cockroachcloud-connect-to-your-cluster.md, line 47 at r8 (raw file):

      {{site.data.alerts.end}}

      If you need to add a range of IP addresses, use the CIDR (Classless Inter-Domain Routing) notation.

nit: If you need to add > To add. Also, no reason for this sentence to be its own paragraph. Please make it the first sentence of the following paragraph.

v19.2/cockroachcloud-connect-to-your-cluster.md, line 79 at r8 (raw file):

## Step 3. Select a connection method

On the machine from which you want to connect to your cluster:

This intro doesn't make sense for all cases. For example, you might grab the connection string on your laptop but then use it in app code running on a server. Do you think this intro is necessary?

v19.2/cockroachcloud-connect-to-your-cluster.md, line 151 at r8 (raw file):

    ~~~

3. Use the `cockroach sql` command to open an interactive SQL shell, replacing placeholders in the [client connection string](#step-3-generate-the-connection-string) with the correct username, password, and path to the `ca.cert`:

This anchor link is broken.

Amruta-Ranade

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @Amruta-Ranade, @jseldess, and @laurenbarker)

v19.2/cockroachcloud-connect-to-your-cluster.md, line 99 at r5 (raw file):

Previously, laurenbarker (Lauren Barker) wrote…

The order of the tabs on the connection modal has recently been updated (CockroachDB Client is the default now).

Done.

v19.2/cockroachcloud-connect-to-your-cluster.md, line 37 at r8 (raw file):

Previously, jseldess (Jesse Seldess) wrote…

These bullets aren't rendering properly. Please fix.

Done.

v19.2/cockroachcloud-connect-to-your-cluster.md, line 79 at r8 (raw file):

Previously, jseldess (Jesse Seldess) wrote…

This intro doesn't make sense for all cases. For example, you might grab the connection string on your laptop but then use it in app code running on a server. Do you think this intro is necessary?

Done.

v19.2/cockroachcloud-connect-to-your-cluster.md, line 151 at r8 (raw file):

Previously, jseldess (Jesse Seldess) wrote…

This anchor link is broken.

Done.

cockroach-teamcity · 2020-01-08T12:48:45Z

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/678074fb1e1beea76d038bc50a7841d30459c473/

Edited pages:

cockroach-teamcity · 2020-01-08T12:58:07Z

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/bf493488198a11fecb08b45f5831bf03ff162eca/

Edited pages:

cockroach-teamcity · 2020-01-08T13:05:42Z

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/7db3eb861786826e93f25fd7d362507a9512e3b9/

Edited pages:

Added language-specific instructions to connect to CC cluster

6fe8f33

Amruta-Ranade force-pushed the cc_connect_apps branch from c741cad to 6fe8f33 Compare November 26, 2019 22:22

Fixing broken links

ee247dc

Trying to fix formatting

a430755

Fixed formatting

9b25bc8

Amruta-Ranade requested a review from jseldess December 3, 2019 02:02

Fixing screenshots

fbb0857

jseldess suggested changes Dec 3, 2019

View reviewed changes

laurenbarker reviewed Dec 3, 2019

View reviewed changes

Worked on Lauren B.'s comments

8f5b815

Worked on Lauren's comments

e451120

Working on Jesse's comments

6dd37a7

jseldess approved these changes Jan 4, 2020

View reviewed changes

Amruta-Ranade added this to In review in Education sprint 16 (1/6 - 1/17) Jan 6, 2020

Amruta-Ranade self-assigned this Jan 7, 2020

Worked on Jesse's comments + replicated doc to 20.1

678074f

Amruta-Ranade changed the title ~~[WIP] Add language-specific instructions to the "Connect to the Cluster" doc~~ Add language-specific instructions to the "Connect to the Cluster" doc Jan 8, 2020

Amruta-Ranade commented Jan 8, 2020

View reviewed changes

Fixed broken links

bf49348

Updated 20.1 tutorial

7db3eb8

Amruta-Ranade merged commit 216b37d into master Jan 8, 2020

Amruta-Ranade deleted the cc_connect_apps branch January 8, 2020 13:08

Amruta-Ranade moved this from In review to Done in Education sprint 16 (1/6 - 1/17) Jan 8, 2020

Amruta-Ranade mentioned this pull request Mar 11, 2020

CC: Adapt CRDB app tutorials for CC #5738

Closed

Add language-specific instructions to the "Connect to the Cluster" doc #6077

Add language-specific instructions to the "Connect to the Cluster" doc #6077

Conversation

Amruta-Ranade commented Nov 26, 2019 • edited Loading

cockroach-teamcity commented Nov 26, 2019

cockroach-teamcity commented Nov 26, 2019

cockroach-teamcity commented Nov 26, 2019

cockroach-teamcity commented Nov 26, 2019

cockroach-teamcity commented Dec 3, 2019

Amruta-Ranade commented Dec 3, 2019

jseldess commented Dec 3, 2019 via email

Amruta-Ranade commented Dec 3, 2019

cockroach-teamcity commented Dec 3, 2019

cockroach-teamcity commented Dec 3, 2019

jseldess left a comment

Choose a reason for hiding this comment

laurenbarker left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Amruta-Ranade commented Dec 3, 2019

cockroach-teamcity commented Dec 3, 2019

cockroach-teamcity commented Dec 10, 2019

cockroach-teamcity commented Dec 11, 2019

cockroach-teamcity commented Jan 4, 2020

jseldess left a comment

Choose a reason for hiding this comment

Amruta-Ranade left a comment

Choose a reason for hiding this comment

cockroach-teamcity commented Jan 8, 2020

cockroach-teamcity commented Jan 8, 2020

cockroach-teamcity commented Jan 8, 2020

Amruta-Ranade commented Nov 26, 2019 •

edited

Loading

laurenbarker left a comment •

edited

Loading