From b9035a52c8df046665a0428e379c365901d426c7 Mon Sep 17 00:00:00 2001 From: Gavin Frazar Date: Mon, 26 Feb 2024 14:16:47 -0800 Subject: [PATCH] [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 --- docs/cspell.json | 27 ++++++----- .../guides/azure-postgres-mysql.mdx | 2 + .../guides/cockroachdb-self-hosted.mdx | 2 + .../guides/postgres-cloudsql.mdx | 3 ++ .../guides/postgres-redshift.mdx | 2 + .../guides/postgres-self-hosted.mdx | 6 ++- docs/pages/database-access/guides/rds.mdx | 2 + .../guides/redshift-serverless.mdx | 2 + .../pg-cancel-request-limitation.mdx | 48 +++++++++++++++++++ 9 files changed, 82 insertions(+), 12 deletions(-) create mode 100644 docs/pages/includes/database-access/pg-cancel-request-limitation.mdx diff --git a/docs/cspell.json b/docs/cspell.json index 0b3c0ff06061c..3ab7989bdd0ea 100644 --- 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,13 +112,11 @@ "Kubernetes", "Kubes", "LDAPS", - "LnaRP0xKWRI", "LOCALAPPDATA", + "LnaRP0xKWRI", "MAINPID", "MDAs", "MGET", - "Minidriver", - "Moba", "MYDNS", "MYELB", "MYIP", @@ -126,16 +124,18 @@ "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 index 75009bf09d351..284069b46404b 100644 --- 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 index 47b52206df222..6dde29c061599 100644 --- 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 index 70d9bbdc342f2..7891277465d08 100644 --- 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 index 3781084369818..d396ee2e4a6c2 100644 --- 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 index 52bcb42ed294c..3591fcd10c845 100644 --- 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 index 0a175ac61a0b7..2d267eec69771 100644 --- a/docs/pages/database-access/guides/rds.mdx +++ b/docs/pages/database-access/guides/rds.mdx @@ -465,6 +465,8 @@ $ tsh db logout (!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 index 0b9738d3f74cb..9c6077bcd2937 100644 --- 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 new file mode 100644 index 0000000000000..f014a03d90ccd --- /dev/null +++ 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(); +``` + +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(); +``` + +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.