[v18] [doc] database "multi-session" MFA

docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx

@@ -199,6 +199,32 @@ $ tsh db connect prod-mysql-instance
 # mysql>
 ```
 
+Jerry can also execute a query against multiple databases with a single MFA check
+using the `tsh db exec` command:
+```code
+$ tsh db exec "select 1" --labels env=prod --db-user teleport-user --output-dir=logs
+Searching databases ...
+Found 2 database(s):
+
+Name                  Description Protocol Labels
+--------------------- ----------- -------- --------
+prod-mysql-instance-1             mysql    env=prod
+prod-mysql-instance-2             mysql    env=prod
+
+Do you want to proceed with 2 database(s)? [y/N]: y
+Executing command for "prod-mysql-instance-1". Output will be saved at "logs/prod-mysql-instance-1.output".
+MFA is required to access Database "prod-mysql-instance-1"
+Tap any security key
+Detected security key tap
+Executing command for "prod-mysql-instance-2". Output will be saved at "logs/prod-mysql-instance-2.output".
+
+Summary: 2 of 2 succeeded.
+Summary is saved at "logs/summary.json".
+```
+
+Note that each MFA check remains valid for up to 5 minutes. After the 5-minutes
+window, a new MFA check will be requested for new connections.
+
 </Admonition>
 
 ## Limitations
@@ -213,6 +239,7 @@ Current limitations for this feature are:
   [multi-port](../../../enroll-resources/application-access/guides/tcp.mdx#configuring-access-to-multiple-ports)
   TCP application through [VNet](../../../connect-your-client/vnet.mdx), the first connection over
   each port triggers an MFA check.
+- For the `tsh db exec` command, only WebAuthn devices are supported.
 
 ## Next steps
 

docs/pages/reference/agent-services/database-access-reference/cli.mdx

@@ -295,13 +295,28 @@ Removes database resource called `database-resource-name`.
 
 ## tsh db ls
 
-Lists available databases and their connection information.
+Lists the databases available to the user based on
+[RBAC](../../../enroll-resources/database-access/rbac.mdx) and their connection
+information.
 
 ```code
+# List all databases.
 $ tsh db ls
+# Search databases with keywords.
+$ tsh db ls --search foo,bar
+# Filter databases with labels.
+$ tsh db ls key1=value1,key2=value2
+# List databases from all clusters with extra fields.
+$ tsh db ls --all -v
+# Get database names using "jq".
+$ tsh db ls --format json  | jq -r '.[].metadata.name'
 ```
 
-Displays only the databases a user has access to (see [RBAC](../../../enroll-resources/database-access/rbac.mdx)).
+| Flag | Description |
+| - | - |
+| `--search` | List of comma separated search keywords or phrases enclosed in quotations (e.g. `--search=foo,bar,"some phrase"`). |
+| `--query`  | Query by predicate language enclosed in single quotes. (e.g. `--query='labels["key1"] == "value1" && labels["key2"] != "value2"')`. |
+| `--format` | Format output (`text`, `json`, `yaml`). |
 
 ## tsh db login
 
@@ -357,6 +372,36 @@ $ tsh db connect --db-user=alice --db-name=db --db-roles reader example
 
 (!docs/pages/includes/db-user-name-flags.mdx!)
 
+## tsh db exec
+
+Execute database commands on target database services.
+```code
+# Search databases with labels.
+$ tsh db exec "source my_script.sql" --db-user mysql --labels key1=value1,key2=value2
+# Search databases with keywords.
+$ tsh db exec "select 1" --db-user mysql --db-name mysql --search foo,bar
+# Execute a command on specified target databases without confirmation.
+$ tsh db exec "select @@hostname" --db-user mysql --dbs mydb1,mydb2,mydb3 --no-confirm
+# Run commands in parallel, and save outputs to files.
+$ tsh db exec "select 1" --db-user mysql --labels env=dev --parallel=5 --output-dir=exec-outputs
+```
+
+<Admonition type="note" title="Note">
+  Currently only PostgreSQL and MySQL databases are supported. Respective
+  database CLI clients (`psql`, `mysql`) should be available in PATH.
+</Admonition>
+
+| Flag | Description |
+| - | - |
+| `--db-user` | The database user to log in as. |
+| `--db-name` | The database name to log in to. |
+| `--db-roles` | List of comma separate database roles to use for auto-provisioned user. |
+| `--dbs` |  List of comma separated target database services. Mutually exclusive with `--search` or `--labels`. |
+| `--search` | List of comma separated search keywords or phrases enclosed in quotations (e.g. `--search=foo,bar,"some phrase"`). |
+| `--labels` | List of comma separated labels to filter by labels (e.g. `key1=value1,key2=value2`). |
+| `--output-dir` | Directory to store command output per target database service. A summary is saved as "summary.json". |
+| `--[no-]confirm` | Confirm selected database services before executing command. |
+
 ## tsh db env
 
 Outputs environment variables for a particular database.