update --db-user and --db-name docs (#32523)

docs/pages/database-access/reference/audit.mdx

@@ -41,7 +41,7 @@ Access denied event:
   "db_protocol": "postgres", // Database protocol.
   "db_service": "local", // Database service name.
   "db_uri": "localhost:5432", // Database server endpoint.
-  "db_user": "superuser", // Database account name user attempted to connect as.
+  "db_user": "superuser", // Database account name user attempted to log in as.
   "ei": 0, // Event index within the session.
   "error": "access to database denied", // Connection error.
   "event": "db.session.start", // Event name.

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

@@ -295,8 +295,10 @@ $ tsh db login --db-user=postgres --db-name=postgres example
 
 | Flag | Description |
 | - | - |
-| `--db-user` | Optionally, set default database account name to connect as. |
-| `--db-name` | Optionally, set default database name to connect to. |
+| `--db-user` | The database user to log in as. |
+| `--db-name` | The database name to log in to. |
+
+(!docs/pages/includes/db-user-name-flags.mdx!)
 
 ## tsh db logout
 
@@ -327,8 +329,10 @@ $ tsh db connect --db-user=alice --db-name=db example
 
 | Flag | Description |
 | - | - |
-| `--db-user` | Optionally, set database user name to connect as. |
-| `--db-name` | Optionally, set database name to connect to. |
+| `--db-user` | The database user to log in as. |
+| `--db-name` | The database name to log in to. |
+
+(!docs/pages/includes/db-user-name-flags.mdx!)
 
 ## tsh db env
 

docs/pages/includes/db-user-name-flags.mdx

@@ -0,0 +1,6 @@
+If `--db-user` or `--db-name` are required, then default settings
+are chosen from either an active database certificate obtained via a prior use
+of `tsh db login` or from the user's allowed `db_users` or `db_names`.
+
+The database user is always required.
+The database name is required for PostgreSQL, MongoDB, and Oracle databases.

docs/pages/reference/cli/tsh.mdx

@@ -437,11 +437,13 @@ $ tsh proxy db [<flags>] <db>
 | Name | Default Value(s) | Allowed Value(s) | Description |
 | - | - | - | - |
 | `--cluster` | none | string | The name of the Teleport cluster to connect to. |
-| `--db-name` | none | string | Optional database name to log in to. |
-| `--db-user` | none | string | Optional database user to log in as. |
+| `--db-name` | see below | string | The database name to log in to. |
+| `--db-user` | see below | string | The database user to log in as. |
 | `--port` | none | string | Source port used by the local proxy.|
 | `--tunnel` | none | Boolean | Open an authenticated tunnel using a database's client certificate so clients don't need to authenticate. |
 
+(!docs/pages/includes/db-user-name-flags.mdx!)
+
 ### [Global Flags](#tsh-global-flags)
 
 These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`.

tool/tsh/common/tsh.go

@@ -799,8 +799,8 @@ func Run(ctx context.Context, args []string, opts ...CliOption) error {
 	proxyDB.Arg("db", "The name of the database to start local proxy for").StringVar(&cf.DatabaseService)
 	proxyDB.Flag("port", "Specifies the source port used by proxy db listener").Short('p').StringVar(&cf.LocalProxyPort)
 	proxyDB.Flag("tunnel", "Open authenticated tunnel using database's client certificate so clients don't need to authenticate").BoolVar(&cf.LocalProxyTunnel)
-	proxyDB.Flag("db-user", "Optional database user to log in as.").StringVar(&cf.DatabaseUser)
-	proxyDB.Flag("db-name", "Optional database name to log in to.").StringVar(&cf.DatabaseName)
+	proxyDB.Flag("db-user", "Database user to log in as.").StringVar(&cf.DatabaseUser)
+	proxyDB.Flag("db-name", "Database name to log in to.").StringVar(&cf.DatabaseName)
 	proxyDB.Flag("cluster", clusterHelp).Short('c').StringVar(&cf.SiteName)
 	proxyDB.Flag("labels", labelHelp).StringVar(&cf.Labels)
 	proxyDB.Flag("query", queryHelp).StringVar(&cf.PredicateExpression)
@@ -844,8 +844,8 @@ func Run(ctx context.Context, args []string, opts ...CliOption) error {
 	dbLogin.Arg("db", "Database to retrieve credentials for. Can be obtained from 'tsh db ls' output.").StringVar(&cf.DatabaseService)
 	dbLogin.Flag("labels", labelHelp).StringVar(&cf.Labels)
 	dbLogin.Flag("query", queryHelp).StringVar(&cf.PredicateExpression)
-	dbLogin.Flag("db-user", "Optional database user to configure as default.").StringVar(&cf.DatabaseUser)
-	dbLogin.Flag("db-name", "Optional database name to configure as default.").StringVar(&cf.DatabaseName)
+	dbLogin.Flag("db-user", "Database user to configure as default.").StringVar(&cf.DatabaseUser)
+	dbLogin.Flag("db-name", "Database name to configure as default.").StringVar(&cf.DatabaseName)
 	dbLogout := db.Command("logout", "Remove database credentials.")
 	dbLogout.Arg("db", "Database to remove credentials for.").StringVar(&cf.DatabaseService)
 	dbLogout.Flag("labels", labelHelp).StringVar(&cf.Labels)
@@ -867,8 +867,8 @@ func Run(ctx context.Context, args []string, opts ...CliOption) error {
 		dbFormatText, dbFormatCommand, dbFormatJSON, dbFormatYAML)).Short('f').EnumVar(&cf.Format, dbFormatText, dbFormatCommand, dbFormatJSON, dbFormatYAML)
 	dbConnect := db.Command("connect", "Connect to a database.")
 	dbConnect.Arg("db", "Database service name to connect to.").StringVar(&cf.DatabaseService)
-	dbConnect.Flag("db-user", "Optional database user to log in as.").StringVar(&cf.DatabaseUser)
-	dbConnect.Flag("db-name", "Optional database name to log in to.").StringVar(&cf.DatabaseName)
+	dbConnect.Flag("db-user", "Database user to log in as.").StringVar(&cf.DatabaseUser)
+	dbConnect.Flag("db-name", "Database name to log in to.").StringVar(&cf.DatabaseName)
 	dbConnect.Flag("labels", labelHelp).StringVar(&cf.Labels)
 	dbConnect.Flag("query", queryHelp).StringVar(&cf.PredicateExpression)