give examples of connection strings enabling SSL

Author: abonander

sqlx-core/src/mysql/connection.rs

@@ -35,16 +35,25 @@ const COLLATE_UTF8MB4_UNICODE_CI: u8 = 224;
 /// rather than as program arguments.
 ///
 /// The same options for `--ssl-mode` are supported as the `ssl-mode` query parameter:
-/// https://dev.mysql.com/doc/refman/8.0/en/connection-options.html#option_general_ssl-mode
+/// <https://dev.mysql.com/doc/refman/8.0/en/connection-options.html#option_general_ssl-mode>
+///
+/// ```text
+/// mysql://<user>[:<password>]@<host>[:<port>]/<database>[?ssl-mode=<ssl-mode>[&ssl-ca=<path>]]
+/// ```
+/// where
+/// ```text
+/// ssl-mode = DISABLED | PREFERRED | REQUIRED | VERIFY_CA | VERIFY_IDENTITY
+/// path = percent (URL) encoded path on the local machine
+/// ```
 ///
 /// If the `tls` feature is not enabled, `ssl-mode=DISABLED` and `ssl-mode=PREFERRED` are no-ops and
 /// `ssl-mode=REQUIRED`, `ssl-mode=VERIFY_CA` and `ssl-mode=VERIFY_IDENTITY` are forbidden
 /// (attempting to connect with these will return an error).
 ///
 /// If the `tls` feature is enabled, an upgrade to TLS is attempted on every connection by default
 /// (equivalent to `ssl-mode=PREFERRED`). If the server does not support TLS (because `--ssl=0` was
-/// passed or an invalid certificate or key was used,
-/// https://dev.mysql.com/doc/refman/8.0/en/using-encrypted-connections.html)
+/// passed to the server or an invalid certificate or key was used:
+/// <https://dev.mysql.com/doc/refman/8.0/en/using-encrypted-connections.html>)
 /// then it falls back to an unsecured connection and logs a warning.
 ///
 /// Add `ssl-mode=REQUIRED` to your connection string to emit an error if the TLS upgrade fails.
@@ -56,6 +65,17 @@ const COLLATE_UTF8MB4_UNICODE_CI: u8 = 224;
 /// but is instead expected to be specified as a local path with the `ssl-ca` query parameter
 /// (percent-encoded so the URL remains valid).
 ///
+/// If you're running MySQL locally it might look something like this (for `VERIFY_CA`):
+/// ```text
+/// mysql://root:password@localhost/my_database?ssl-mode=VERIFY_CA&ssl-ca=%2Fvar%2Flib%2Fmysql%2Fca.pem
+/// ```
+///
+/// `%2F` is the percent-encoding for forward slash (`/`). In the example we give `/var/lib/mysql/ca.pem`
+/// as the CA certificate path, which is generated by the MySQL server automatically if
+/// no certificate is manually specified. Note that the path may vary based on the default `my.cnf`
+/// packaged with MySQL for your Linux distribution. Also note that unlike MySQL, MariaDB does *not*
+/// generate certificates automatically and they must always be passed in to enable TLS.
+///
 /// If `ssl-ca` is not specified or the file cannot be read, then an error is returned.
 /// `ssl-ca` implies `ssl-mode=VERIFY_CA` so you only actually need to specify the former
 /// but you may prefer having both to be more explicit.

sqlx-core/src/postgres/connection.rs

@@ -26,19 +26,33 @@ use crate::Result;
 ///
 /// ### TLS Support (requires `tls` feature)
 /// This connection type supports the same `sslmode` query parameter that `libpq` does in
-/// connection strings: https://www.postgresql.org/docs/12/libpq-ssl.html
+/// connection strings: <https://www.postgresql.org/docs/12/libpq-ssl.html>
+///
+/// ```text
+/// postgresql://<user>[:<password>]@<host>[:<port>]/<database>[?sslmode=<ssl-mode>[&sslcrootcert=<path>]]
+/// ```
+/// where
+/// ```text
+/// ssl-mode = disable | allow | prefer | require | verify-ca | verify-full
+/// path = percent (URL) encoded path on the local machine
+/// ```
 ///
 /// If the `tls` feature is not enabled, `disable`, `allow` and `prefer` are no-ops and `require`,
 /// `verify-ca` and `verify-full` are forbidden (attempting to connect with these will return
 /// an error).
 ///
 /// If the `tls` feature is enabled, an upgrade to TLS is attempted on every connection by default
 /// (equivalent to `sslmode=prefer`). If the server does not support TLS (because it was not
-/// started with a valid certificate and key, see https://www.postgresql.org/docs/12/ssl-tcp.html)
+/// started with a valid certificate and key, see <https://www.postgresql.org/docs/12/ssl-tcp.html>)
 /// then it falls back to an unsecured connection and logs a warning.
 ///
 /// Add `sslmode=require` to your connection string to emit an error if the TLS upgrade fails.
 ///
+/// If you're running Postgres locally, your connection string might look like this:
+/// ```text
+/// postgresql://root:password@localhost/my_database?sslmode=require
+/// ```
+///
 /// However, like with `libpq` the server certificate is **not** checked for validity by default.
 ///
 /// Specifying `sslmode=verify-ca` will cause the TLS upgrade to verify the server's SSL
@@ -57,7 +71,7 @@ use crate::Result;
 ///     * `$HOME/.postgresql/root.crt` on POSIX systems
 ///     * `%APPDATA%\postgresql\root.crt` on Windows
 ///
-/// These locations are documented here: https://www.postgresql.org/docs/12/libpq-ssl.html#LIBQ-SSL-CERTIFICATES
+/// These locations are documented here: <https://www.postgresql.org/docs/12/libpq-ssl.html#LIBQ-SSL-CERTIFICATES>
 /// If the root certificate cannot be found by any of these means then the TLS upgrade will fail.
 ///
 /// If `sslmode=verify-full` is specified, in addition to checking the certificate as with