[docs] add postgresql query cancellation troubleshooting (#38600)

* add postgresql query cancellation troubleshooting

* link to psql docs

* explain how to find a query pid in redshift

* fix lint

docs/cspell.json

@@ -708,6 +708,7 @@
     "readyz",
     "realmd",
     "reauthentication",
+    "recents",
     "reco",
     "rediscluster",
     "redisinsight",
@@ -855,6 +856,7 @@
     "upgrader",
     "uqcje",
     "urandom",
+    "usename",
     "userdata",
     "userdel",
     "usermod",

docs/pages/database-access/guides/azure-postgres-mysql.mdx

@@ -424,6 +424,8 @@ $ tsh db logout azure-db
 
 (!docs/pages/includes/database-access/azure-troubleshooting.mdx!)
 
+(!docs/pages/includes/database-access/pg-cancel-request-limitation.mdx!)
+
 ## Next steps
 
 (!docs/pages/includes/database-access/guides-next-steps.mdx!)

docs/pages/database-access/guides/cockroachdb-self-hosted.mdx

@@ -269,6 +269,8 @@ If you are connecting the CockroachDB database with Teleport Connect, add the
 environment variable to your shell startup scripts and restart the Teleport
 Connect app.
 
+(!docs/pages/includes/database-access/pg-cancel-request-limitation.mdx!)
+
 ## Next steps
 
 (!docs/pages/includes/database-access/guides-next-steps.mdx!)

docs/pages/database-access/guides/postgres-cloudsql.mdx

@@ -380,3 +380,6 @@ $ tsh db logout cloudsql
 $ tsh db logout
 ```
 
+## Troubleshooting
+
+(!docs/pages/includes/database-access/pg-cancel-request-limitation.mdx!)

docs/pages/database-access/guides/postgres-redshift.mdx

@@ -175,6 +175,8 @@ $ tsh db logout my-redshift
 
 (!docs/pages/includes/database-access/aws-troubleshooting-max-policy-size.mdx!)
 
+(!docs/pages/includes/database-access/pg-cancel-request-limitation.mdx PIDQuery="SELECT pid,starttime,duration,trim(user_name) AS user,trim(query) AS query FROM stv_recents WHERE status = 'Running';"!)
+
 ## Next steps
 
 (!docs/pages/includes/database-access/guides-next-steps.mdx!)

docs/pages/database-access/guides/postgres-self-hosted.mdx

@@ -156,7 +156,11 @@ $ tsh db logout example-postgres
 $ tsh db logout
 ```
 
+## Troubleshooting
+
+(!docs/pages/includes/database-access/pg-cancel-request-limitation.mdx!)
+
 ## Next steps
 
 - Set up [automatic database user provisioning](../auto-user-provisioning/postgres.mdx).
-
+(!docs/pages/includes/database-access/guides-next-steps.mdx!)

docs/pages/database-access/guides/rds.mdx

@@ -435,6 +435,8 @@ $ tsh db logout <Var name="postgres-rds" />
 
 (!docs/pages/includes/database-access/aws-troubleshooting-max-policy-size.mdx!)
 
+(!docs/pages/includes/database-access/pg-cancel-request-limitation.mdx!)
+
 ## Next steps
 
 (!docs/pages/includes/database-access/guides-next-steps.mdx!)

docs/pages/database-access/guides/redshift-serverless.mdx

@@ -196,6 +196,8 @@ prior to logging in as this new IAM role to avoid or resolve user permission iss
 
 (!docs/pages/includes/database-access/aws-troubleshooting.mdx!)
 
+(!docs/pages/includes/database-access/pg-cancel-request-limitation.mdx PIDQuery="SELECT session_id AS pid, database_name,start_time,trim(query_text) AS query FROM SYS_QUERY_HISTORY WHERE status = 'running';"!)
+
 ## Next steps
 
 (!docs/pages/includes/database-access/guides-next-steps.mdx!)

docs/pages/includes/database-access/pg-cancel-request-limitation.mdx

@@ -0,0 +1,48 @@
+{{ PIDQuery="SELECT pid,usename,backend_start,query FROM pg_stat_activity WHERE state = 'active';" }}
+### Unable to cancel a query
+
+If you use a PostgreSQL cli client like `psql`, and you try to cancel a query
+with `ctrl+c`, but it doesn't cancel the query, then you need to connect using a
+tsh local proxy instead.
+When `psql` cancels a query, it establishes a new connection without TLS
+certificates, however Teleport requires TLS certificates not only for
+authentication, but also to route database connections.
+
+If you
+[enable TLS Routing in Teleport](../../management/operations/tls-routing.mdx)
+then `tsh db connect` will automatically start a local proxy for every
+connection.
+Alternatively, you can connect via
+[Teleport Connect](../../connect-your-client/teleport-connect.mdx)
+which also uses a local proxy.
+Otherwise, you need to start a tsh local proxy manually using `tsh proxy db`
+and connect via the local proxy.
+
+If you have already started a long-running query in a `psql` session that you
+cannot cancel with ctrl+c, you can start a new client session to cancel that
+query manually:
+
+First, find the query's process identifier (PID):
+```sql
+{{ PIDQuery }}
+```
+
+Next, gracefully cancel the query using its PID.
+This will send a SIGINT signal to the postgres backend process for that query:
+```sql
+SELECT pg_cancel_backend(<PID>);
+```
+
+You should always try to gracefully terminate a query first, but if graceful
+cancellation is taking too long, then you can forcefully terminate the query
+instead.
+This will send a SIGTERM signal to the postgres backend process for that query:
+
+```sql
+SELECT pg_terminate_backend(<PID>);
+```
+
+See the PostgreSQL documentation on
+[admin functions](https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADMIN-SIGNAL)
+for more information about the `pg_cancel_backend` and `pg_terminate_backend`
+functions.