diff --git a/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx b/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx index d22683be7adcb..9c3f8f6a219b6 100644 --- a/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx +++ b/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. + ## 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 diff --git a/docs/pages/reference/agent-services/database-access-reference/cli.mdx b/docs/pages/reference/agent-services/database-access-reference/cli.mdx index f35f791ad0c70..860aee6538f3d 100644 --- a/docs/pages/reference/agent-services/database-access-reference/cli.mdx +++ b/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 +``` + + + Currently only PostgreSQL and MySQL databases are supported. Respective + database CLI clients (`psql`, `mysql`) should be available in PATH. + + +| 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.