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

* add postgresql query cancellation troubleshooting * link to psql docs * explain how to find a query pid in redshift * fix lint
gravitational · Feb 26, 2024 · b9035a5 · b9035a5
1 parent e8d8d02
commit b9035a5
Show file tree

Hide file tree

Showing 9 changed files with 82 additions and 12 deletions.
diff --git a/docs/cspell.json b/docs/cspell.json
@@ -3,7 +3,6 @@
   "language": "en",
   "words": [
     "AADUSER",
-    "Aarch",
     "ABCDEFGHIJKL",
     "ADFS",
     "AICPA",
@@ -18,6 +17,7 @@
     "AUTHINFO",
     "AWSARN",
     "AWSIIDTTL",
+    "Aarch",
     "Addrs",
     "Afax",
     "Aqxs",
@@ -36,8 +36,8 @@
     "CREATEDB",
     "CTAP",
     "CXXXXXXXXX",
-    "Cygwin",
     "Cgajq",
+    "Cygwin",
     "DBSIZE",
     "DEBU",
     "DHDR",
@@ -112,30 +112,30 @@
     "Kubernetes",
     "Kubes",
     "LDAPS",
-    "LnaRP0xKWRI",
     "LOCALAPPDATA",
+    "LnaRP0xKWRI",
     "MAINPID",
     "MDAs",
     "MGET",
-    "Minidriver",
-    "Moba",
     "MYDNS",
     "MYELB",
     "MYIP",
     "MYPROJ",
     "MYTOKEN",
     "MYZONE",
     "Mailgun",
+    "Minidriver",
+    "Moba",
     "Moba",
     "Mqgcq",
     "Multifactor",
     "Multihost",
     "Mzgz",
-    "Näme",
     "NOFILE",
     "NOKEY",
     "NOPASSWD",
     "NVGJ",
+    "Näme",
     "ODBC",
     "OIDC",
     "OTLP",
@@ -191,15 +191,14 @@
     "Svhk",
     "Swic",
     "Swicm",
-    "Tatham",
     "TCPS",
-    "teleportinfra",
     "TELEPORTING",
     "TENANTID",
     "TESTDEVICE",
     "TOTP",
     "TOUCHID",
     "Tatham",
+    "Tatham",
     "Tele",
     "Templating",
     "Tmkx",
@@ -210,8 +209,10 @@
     "Upserted",
     "Upserts",
     "Uwhp",
+    "VPCID",
     "VSVZY",
     "Vhka",
+    "Vitess",
     "Vybm",
     "WWFCX",
     "WXJKZ",
@@ -314,6 +315,8 @@
     "cimg",
     "ciphersuites",
     "circleci",
+    "clickhouse",
+    "clientcert",
     "clientcmd",
     "clientid",
     "clis",
@@ -396,10 +399,10 @@
     "exampledb",
     "exampletoken",
     "exampleuser",
-    "extfile",
     "exfiltrated",
     "exfiltration",
     "externaladdress",
+    "extfile",
     "extraargs",
     "extraenv",
     "fakehost",
@@ -676,10 +679,10 @@
     "readyz",
     "realmd",
     "reauthentication",
+    "recents",
     "reco",
     "rediscluster",
     "redisinsight",
-    "reco",
     "rediss",
     "regexes",
     "relogged",
@@ -768,6 +771,7 @@
     "teleportblob",
     "teleportdemo",
     "teleporters",
+    "teleportinfra",
     "teleportproxy",
     "teleportroles",
     "teleportusers",
@@ -809,6 +813,7 @@
     "upgrader",
     "uqcje",
     "urandom",
+    "usename",
     "userdata",
     "userdel",
     "usermod",
@@ -821,7 +826,7 @@
     "vkxz",
     "vmcopy",
     "vmjm",
-    "VPCID",
+    "vtgate",
     "walkthrough",
     "watcherjob",
     "webapi",

diff --git a/docs/pages/database-access/guides/azure-postgres-mysql.mdx b/docs/pages/database-access/guides/azure-postgres-mysql.mdx
@@ -434,6 +434,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!)

diff --git a/docs/pages/database-access/guides/cockroachdb-self-hosted.mdx b/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!)

diff --git a/docs/pages/database-access/guides/postgres-cloudsql.mdx b/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!)
diff --git a/docs/pages/database-access/guides/postgres-redshift.mdx b/docs/pages/database-access/guides/postgres-redshift.mdx
@@ -159,6 +159,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
 
 - Learn more about [using IAM authentication to generate database user

diff --git a/docs/pages/database-access/guides/postgres-self-hosted.mdx b/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](../rbac/configuring-auto-user-provisioning.mdx).
-
+(!docs/pages/includes/database-access/guides-next-steps.mdx!)
diff --git a/docs/pages/database-access/guides/rds.mdx b/docs/pages/database-access/guides/rds.mdx
@@ -465,6 +465,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!)

diff --git a/docs/pages/database-access/guides/redshift-serverless.mdx b/docs/pages/database-access/guides/redshift-serverless.mdx
@@ -353,6 +353,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
 
 - Learn more about [using IAM authentication to generate database user

diff --git a/docs/pages/includes/database-access/pg-cancel-request-limitation.mdx b/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.