Connect: Fix and improve connection strings

docs/connect/index.md

@@ -29,6 +29,19 @@ In order to connect to CrateDB, your application or driver needs to be
 configured with corresponding connection properties. Please note that different
 applications and drivers may obtain connection properties in different formats.
 
+<style>
+/* Code blocks need to be slimmer */
+.driver-slim div.highlight-default {
+  margin-top: 0.2em;
+}
+.driver-slim pre {
+  padding: 0.4em;
+}
+.driver-slim p {
+  margin-bottom: 0;
+}
+</style>
+
 ::::::{tab-set}
 
 :::::{tab-item} CrateDB and CrateDB Cloud
@@ -38,34 +51,52 @@ applications and drivers may obtain connection properties in different formats.
 :padding: 0
 
 :::{grid-item}
-:columns: 5
+:columns: 4
 :margin: 0
 :padding: 0
 
 **Connection properties**
 
-:Host: `<clustername>`.cratedb.net
-:Port: 5432 (PostgreSQL) or 4200 (HTTP)
-:User: `<username>`
+:Host: `<cluster>`.cratedb.net
+:Port: 5432 (PostgreSQL) or<br>4200 (HTTP)
+:User: `<user>`
 :Pass: `<password>`
 
 :::
 
 :::{grid-item}
-:columns: 7
+:columns: 8
 :margin: 0
 :padding: 0
+:class: driver-slim
 
 **Connection-string examples**
+<br><br>
 
-A native PostgreSQL connection string.
-`postgresql://<username>@<clustername>.cratedb.net/crate`
+**Native PostgreSQL, psql**
+```
+postgresql://<user>:<password>@<cluster>.cratedb.net:5432/doc
+```
 
-A connection string for SQLAlchemy or Apache Flink.
-`crate://<username>@<clustername>.cratedb.net/crate`
+**JDBC: PostgreSQL pgJDBC**
+```
+jdbc:postgresql://<user>:<password>@<cluster>.cratedb.net:5432/doc
+```
 
-An HTTP URL to visit Admin UI.
-`https://<username>@<clustername>.cratedb.net:4200/`
+**JDBC: CrateDB JDBC, e.g. Apache Flink**
+```
+jdbc:crate://<user>:<password>@<cluster>.cratedb.net:5432/doc
+```
+
+**HTTP: Admin UI, CLI, CrateDB drivers**
+```
+https://<user>:<password>@<cluster>.cratedb.net:4200/
+```
+
+**SQLAlchemy**
+```
+crate://<user>:<password>@<cluster>.cratedb.net:4200/?schema=doc&ssl=true
+```
 
 :::
 
@@ -80,34 +111,52 @@ An HTTP URL to visit Admin UI.
 :padding: 0
 
 :::{grid-item}
-:columns: 5
+:columns: 4
 :margin: 0
 :padding: 0
 
 **Connection properties**
 
 :Host: localhost
-:Port: 5432 (PostgreSQL) or 4200 (HTTP)
+:Port: 5432 (PostgreSQL) or<br>4200 (HTTP)
 :User: `crate`
 :Pass: (empty)
 
 :::
 
 :::{grid-item}
-:columns: 7
+:columns: 8
 :margin: 0
 :padding: 0
+:class: driver-slim
 
 **Connection-string examples**
+<br><br>
 
-A native PostgreSQL connection string.
-`postgresql://crate@localhost:5432/crate`
+**Native PostgreSQL, psql**
+```
+postgresql://crate@localhost:5432/doc
+```
+
+**JDBC: PostgreSQL pgJDBC**
+```
+jdbc:crate://crate@localhost:5432/doc
+```
+
+**JDBC: CrateDB JDBC, e.g. Apache Flink**
+```
+jdbc:crate://<user>:<password>@localhost:5432/doc
+```
 
-A connection string for SQLAlchemy or Apache Flink.
-`crate://crate@localhost/crate`
+**HTTP: Admin UI, CLI, CrateDB drivers**
+```
+http://crate@localhost:4200/
+```
 
-An HTTP URL to visit Admin UI.
-`http://crate@localhost:4200/`
+**SQLAlchemy**
+```
+crate://crate@localhost:4200/?schema=doc
+```
 
 :::
 
@@ -118,11 +167,17 @@ An HTTP URL to visit Admin UI.
 
 
 ```{tip}
-- Specify the [schema] name `doc`, if you are asked for a *database name*.
-- The default [superuser] on a vanilla CrateDB cluster is called `crate`,
-  without a password.
-- When aiming to authenticate properly, please learn about the available
-  [authentication] options. 
+- CrateDB's fixed catalog name is `crate`, the default schema name is `doc`.
+- CrateDB does not implement the notion of a database,
+  however tables can be created in different [schemas].
+- When asked for a *database name*, specifying a schema name (any),
+  or the fixed catalog name `crate` may be applicable.
+- If a database-/schema-name is omitted while connecting,
+  the PostgreSQL drivers may default to the "username".
+- The predefined [superuser] on an unconfigured CrateDB cluster is
+  called `crate`, defined without a password.
+- For authenticating properly, please learn about the available
+  [authentication] options.
 ```
 
 
@@ -513,4 +568,5 @@ ruby
 [python-dbapi-by-example]: inv:crate-python:*:label#by-example
 [python-sqlalchemy-by-example]: inv:sqlalchemy-cratedb:*:label#by-example
 [schema]: inv:crate-reference:*:label#ddl-create-table-schemas
+[schemas]: inv:crate-reference:*:label#ddl-create-table-schemas
 [superuser]: inv:crate-reference:*:label#administration_user_management