Replace cockroach encode-uri with convert-url in v26.2 (#23218)

Author: mikeCRL

src/current/v26.2/connection-parameters.md

@@ -128,24 +128,89 @@ SQL driver to determine whether these options are supported.
 
 ### Convert a URL for different drivers
 
- The subcommand `cockroach convert-url` converts a connection URL, such as those printed out by [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}) or included in the online documentation, to the syntax recognized by various [client drivers]({% link {{ page.version.version }}/third-party-database-tools.md %}#drivers). For example:
+The subcommand `cockroach convert-url` converts a connection URL, such as those printed out by [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}) or included in the online documentation, to the syntax recognized by various [client drivers]({% link {{ page.version.version }}/third-party-database-tools.md %}#drivers).
+
+{{site.data.alerts.callout_info}}
+The `cockroach encode-uri` command has been deprecated and merged into `cockroach convert-url`. Use `cockroach convert-url --format crdb` instead. The `encode-uri` command will be removed in a future release.
+{{site.data.alerts.end}}
+
+#### Basic usage
+
+By default, `convert-url` outputs the URL in multiple formats:
 
 {% include_cached copy-clipboard.html %}
 ~~~
 $ ./cockroach convert-url --url "postgres://foo/bar"
 ~~~
 
 ~~~
-# Connection URL for libpq (C/C++), psycopg (Python), lib/pq & pgx (Go),node-postgres (JS)
-and most pq-compatible drivers:
-  postgresql://root@foo:26257/bar
-# Connection DSN (Data Source Name) for Postgres drivers that accept DSNs - most drivers
-and also ODBC:
-  database=bar user=root host=foo port=26257
+# Connection URL for libpq (C/C++), psycopg (Python), lib/pq & pgx (Go), node-postgres (JS) and most pq-compatible drivers:
+postgresql://root@foo:26257/bar
+
+# Connection DSN (Data Source Name) for Postgres drivers that accept DSNs - most drivers and also ODBC:
+database=bar user=root host=foo port=26257
+
 # Connection URL for JDBC (Java and JVM-based languages):
-  jdbc:postgresql://foo:26257/bar?user=root
+jdbc:postgresql://foo:26257/bar?user=root
+
+# Direct URL to CockroachDB:
+postgresql://root@foo:26257/bar
+~~~
+
+#### Specify output format
+
+Use the `--format` flag to output a specific format:
+
+{% include_cached copy-clipboard.html %}
+~~~ shell
+cockroach convert-url --url "postgres://foo/bar" --format jdbc
+~~~
+
+~~~
+jdbc:postgresql://foo:26257/bar?user=root
+~~~
+
+Supported formats:
+
+Format | Description
+-------|------------
+`pq` | Connection URL for libpq (C/C++), psycopg (Python), lib/pq & pgx (Go), node-postgres (JS), and most pq-compatible drivers
+`dsn` | Data Source Name for Postgres drivers that accept DSNs and ODBC
+`jdbc` | Connection URL for JDBC (Java and JVM-based languages)
+`crdb` | CockroachDB-specific URL format with inlined certificates for [Physical Cluster Replication]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}) and [Logical Data Replication]({% link {{ page.version.version }}/logical-data-replication-overview.md %})
+
+#### Generate URLs for replication
+
+To generate a connection URL for [Physical Cluster Replication]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}) or [Logical Data Replication]({% link {{ page.version.version }}/logical-data-replication-overview.md %}), use the `--format crdb` flag with the `--inline` flag to inline certificates directly into the URL:
+
+{% include_cached copy-clipboard.html %}
+~~~ shell
+cockroach convert-url --url "postgresql://{user}:{password}@{node IP}:26257" --format crdb --ca-cert {path to CA certificate} --inline
 ~~~
 
+The `--inline` flag automatically sets `--format crdb`, so you can also use:
+
+{% include_cached copy-clipboard.html %}
+~~~ shell
+cockroach convert-url --url "postgresql://{user}:{password}@{node IP}:26257" --ca-cert {path to CA certificate} --inline
+~~~
+
+#### Additional flags
+
+Flag | Description
+-----|------------
+`--url` | Connection URL to convert (required)
+`--format` | Output format: `pq`, `dsn`, `jdbc`, or `crdb`
+`--inline` | Inline certificates into the URL (automatically sets `--format crdb`)
+`--database` | Database name
+`--user` | Username
+`--password` | Password
+`--cluster` | Cluster name (sets `options=-ccluster=<name>`)
+`--certs-dir` | Path to certificates directory
+`--ca-cert` | Path to CA certificate
+`--cert` | Path to client certificate
+`--key` | Path to client private key
+
 ### Example URL for an insecure connection
 
 The following URL is suitable to connect to a CockroachDB node using an insecure connection:

src/current/v26.2/failover-replication.md

@@ -207,11 +207,11 @@ This section illustrates the steps to fail back to the original primary cluster
     ALTER VIRTUAL CLUSTER {cluster_a} STOP SERVICE;
     ~~~
 
-1. Open another terminal window and generate a connection string for **Cluster B** using [`cockroach encode-uri`]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#step-3-manage-cluster-certificates-and-generate-connection-strings):
+1. Open another terminal window and generate a connection string for **Cluster B** using [`cockroach convert-url`]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#step-3-manage-cluster-certificates-and-generate-connection-strings):
 
     {% include_cached copy-clipboard.html %}
     ~~~ shell
-    cockroach encode-uri {replication user}:{password}@{cluster B node IP or hostname}:26257 --ca-cert certs/ca.crt --inline
+    cockroach convert-url --url "postgresql://{replication user}:{password}@{cluster B node IP or hostname}:26257" --format crdb --ca-cert certs/ca.crt --inline
     ~~~
 
     Copy the output ready for starting the PCR stream, which requires the connection string to **Cluster B**:

src/current/v26.2/set-up-logical-data-replication.md

@@ -181,13 +181,13 @@ To change the password later, refer to [`ALTER USER`]({% link {{ page.version.ve
 
 In this step, you'll set up [external connection(s)]({% link {{ page.version.version }}/create-external-connection.md %}) to store the connection string for one or both clusters. Depending on how you manage certificates, you must ensure that all nodes between the clusters have access to the certificate of the other cluster.
 
-You can use the `cockroach encode-uri` command to generate a connection string containing a cluster's certificate.
+You can use the `cockroach convert-url` command to generate a connection string containing a cluster's certificate.
 
-1. On the **source** cluster in a new terminal window, generate a connection string, by passing the replication user, node IP, and port, along with the directory to the source cluster's CA certificate:
+1. On the **source** cluster in a new terminal window, generate a connection string by passing the connection URL for the replication user, along with the path to the source cluster's CA certificate:
 
     {% include_cached copy-clipboard.html %}
     ~~~ shell
-    cockroach encode-uri postgresql://{user}:{password}@{node IP}:26257 --ca-cert {path to CA certificate} --inline
+    cockroach convert-url --url "postgresql://{user}:{password}@{node IP}:26257" --format crdb --ca-cert {path to CA certificate} --inline
     ~~~
 
     The connection string output contains the source cluster's certificate:
@@ -224,7 +224,7 @@ Once the source cluster has made a connection to the destination cluster, the de
 
     {% include_cached copy-clipboard.html %}
     ~~~ shell
-    cockroach encode-uri postgresql://{user}:{password}@{node IP}:26257 --ca-cert {path to CA certificate} --inline
+    cockroach convert-url --url "postgresql://{user}:{password}@{node IP}:26257" --format crdb --ca-cert {path to CA certificate} --inline
     ~~~
 
     The connection string output contains the source cluster's certificate:

src/current/v26.2/set-up-physical-cluster-replication.md

@@ -253,11 +253,11 @@ To create certificates signed by an external certificate authority, refer to [Cr
 
 At this point, the primary and standby clusters are both running. The next step creates a connection URI with the certifications needed to connect the two clusters. In most cases, we recommend ensuring that all nodes on the primary cluster have access to the certificate of the standby cluster, and vice versa. This ensures that PCR is able to parallelize the work.
 
-Use the `cockroach encode-uri` command to generate a connection string containing a cluster's certificate for any [PCR statements]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}#manage-replication-in-the-sql-shell) that require a connection string. Pass the replication user, IP and port, along with the path to the certificate for the **primary cluster**, into the `encode-uri` command:
+Use the `cockroach convert-url` command to generate a connection string containing a cluster's certificate for any [PCR statements]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}#manage-replication-in-the-sql-shell) that require a connection string. Pass the connection URL for the replication user, along with the path to the certificate for the **primary cluster**, into the `convert-url` command:
 
 {% include_cached copy-clipboard.html %}
 ~~~ shell
-cockroach encode-uri {replication user}:{password}@{node IP or hostname}:26257 --ca-cert {path to certs directory}/certs/ca.crt --inline
+cockroach convert-url --url "postgresql://{replication user}:{password}@{node IP or hostname}:26257" --format crdb --ca-cert {path to certs directory}/certs/ca.crt --inline
 ~~~
 
 The connection string output contains the primary cluster's certificate:
@@ -404,7 +404,7 @@ Before you begin, you will need:
     (1 row)
     ~~~
 
-1. To create the replication job, you will need a connection string for the **primary cluster** containing its CA certificate. For steps to generate a connection string with `cockroach encode-uri`, refer to [Step 3. Manage cluster certificates and generate connection strings](#step-3-manage-cluster-certificates-and-generate-connection-strings).
+1. To create the replication job, you will need a connection string for the **primary cluster** containing its CA certificate. For steps to generate a connection string with `cockroach convert-url`, refer to [Step 3. Manage cluster certificates and generate connection strings](#step-3-manage-cluster-certificates-and-generate-connection-strings).
 
 1. If you would like to run a test workload on your existing **primary cluster**, you can use [`cockroach workload`]({% link {{ page.version.version }}/cockroach-workload.md %}) like the following:
 
@@ -468,8 +468,8 @@ Cluster | Virtual Cluster | Usage | URL and Parameters
 Primary | System | Set up a replication user and view running virtual clusters. Connect with [`cockroach sql`]({% link {{ page.version.version }}/cockroach-sql.md %}). | `"postgresql://root@{node IP or hostname}:{26257}?options=-ccluster=system&sslmode=verify-full"`<ul><li>`options=-ccluster=system`</li><li>`sslmode=verify-full`</li></ul>Use the `--certs-dir` flag to specify the path to your certificate.
 Primary | Main | Add and run a workload with [`cockroach workload`]({% link {{ page.version.version }}/cockroach-workload.md %}). | `"postgresql://root@{node IP or hostname}:{26257}?options=-ccluster=main&sslmode=verify-full&sslrootcert=certs/ca.crt&sslcert=certs/client.root.crt&sslkey=certs/client.root.key"`<br><br>{% include {{ page.version.version }}/connect/cockroach-workload-parameters.md %} As a result, for the example in this tutorial, you will need:<ul><li>`options=-ccluster={virtual_cluster_name}`</li><li>`sslmode=verify-full`</li><li>`sslrootcert={path}/certs/ca.crt`</li><li>`sslcert={path}/certs/client.root.crt`</li><li>`sslkey={path}/certs/client.root.key`</li></ul>
 Standby | System | Manage the replication stream. Connect with [`cockroach sql`]({% link {{ page.version.version }}/cockroach-sql.md %}). | `"postgresql://root@{node IP or hostname}:{26257}?options=-ccluster=system&sslmode=verify-full"`<ul><li>`options=-ccluster=system`</li><li>`sslmode=verify-full`</li></ul>Use the `--certs-dir` flag to specify the path to your certificate.
-Standby/Primary | System | Connect to the other cluster. | `"postgresql://{replication user}:{password}@{node IP or hostname}:{26257}/defaultdb?options=-ccluster%3Dsystem&sslinline=true&sslmode=verify-full&sslrootcert=-----BEGIN+CERTIFICATE-----{encoded_cert}-----END+CERTIFICATE-----%0A"`<br><br>Generate the connection string with [`cockroach encode-uri`](#step-3-manage-cluster-certificates-and-generate-connection-strings). Use the generated connection string in:<ul><li>`CREATE VIRTUAL CLUSTER` statements to [start the replication stream](#step-4-start-replication).</li><li>`ALTER VIRTUAL CLUSTER` statements to [fail back to the primary cluster]({% link {{ page.version.version }}/failover-replication.md %}#failback).</li></ul>
-Standby/Primary | System | Connect to the other cluster through its load balancer | `"postgresql://{replication user}:{password}@{node IP or hostname}:{26257}/defaultdb?options=-ccluster%3Dsystem&crdb_route=gateway&sslinline=true&sslmode=verify-full&sslrootcert=-----BEGIN+CERTIFICATE-----{encoded_cert}-----END+CERTIFICATE-----%0A"`<br><br>Generate the connection string with [`cockroach encode-uri`](#step-3-manage-cluster-certificates-and-generate-connection-strings) and manually add the `&crdb_route=gateway` parameter. Recommended only when nodes do not share the same network. Use the generated connection string in:<ul><li>`CREATE VIRTUAL CLUSTER` statements to [start the replication stream](#step-4-start-replication).</li><li>`ALTER VIRTUAL CLUSTER` statements to [fail back to the primary cluster]({% link {{ page.version.version }}/failover-replication.md %}#failback).</li></ul>
+Standby/Primary | System | Connect to the other cluster. | `"postgresql://{replication user}:{password}@{node IP or hostname}:{26257}/defaultdb?options=-ccluster%3Dsystem&sslinline=true&sslmode=verify-full&sslrootcert=-----BEGIN+CERTIFICATE-----{encoded_cert}-----END+CERTIFICATE-----%0A"`<br><br>Generate the connection string with [`cockroach convert-url`](#step-3-manage-cluster-certificates-and-generate-connection-strings). Use the generated connection string in:<ul><li>`CREATE VIRTUAL CLUSTER` statements to [start the replication stream](#step-4-start-replication).</li><li>`ALTER VIRTUAL CLUSTER` statements to [fail back to the primary cluster]({% link {{ page.version.version }}/failover-replication.md %}#failback).</li></ul>
+Standby/Primary | System | Connect to the other cluster through its load balancer | `"postgresql://{replication user}:{password}@{node IP or hostname}:{26257}/defaultdb?options=-ccluster%3Dsystem&crdb_route=gateway&sslinline=true&sslmode=verify-full&sslrootcert=-----BEGIN+CERTIFICATE-----{encoded_cert}-----END+CERTIFICATE-----%0A"`<br><br>Generate the connection string with [`cockroach convert-url`](#step-3-manage-cluster-certificates-and-generate-connection-strings) and manually add the `&crdb_route=gateway` parameter. Recommended only when nodes do not share the same network. Use the generated connection string in:<ul><li>`CREATE VIRTUAL CLUSTER` statements to [start the replication stream](#step-4-start-replication).</li><li>`ALTER VIRTUAL CLUSTER` statements to [fail back to the primary cluster]({% link {{ page.version.version }}/failover-replication.md %}#failback).</li></ul>
 Standby | Read only | Run read queries on the standby's replicating virtual cluster | `"postgresql://root@{node IP or hostname}:{26257}?options=-ccluster=main-readonly&sslmode=verify-full"`<ul><li>`options=-ccluster=main-readonly`</li><li>`sslmode=verify-full`</li></ul>Use the `--certs-dir` flag to specify the path to your certificate.
 
 ## What's next