From a24eee0e5d69d805a5433da19da6b71213a6e839 Mon Sep 17 00:00:00 2001 From: Gavin Frazar Date: Mon, 26 Feb 2024 11:32:53 -0800 Subject: [PATCH] [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 | 2 + .../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, 68 insertions(+), 1 deletion(-) create mode 100644 docs/pages/includes/database-access/pg-cancel-request-limitation.mdx diff --git a/docs/cspell.json b/docs/cspell.json index b55487e76b181..e424598cbe001 100644 --- a/docs/cspell.json +++ b/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", diff --git a/docs/pages/database-access/guides/azure-postgres-mysql.mdx b/docs/pages/database-access/guides/azure-postgres-mysql.mdx index 9cb07d9e8ace9..d48f5e616c8c1 100644 --- a/docs/pages/database-access/guides/azure-postgres-mysql.mdx +++ b/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!) 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 20195f3f19563..2979295a07cad 100644 --- a/docs/pages/database-access/guides/postgres-redshift.mdx +++ b/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!) diff --git a/docs/pages/database-access/guides/postgres-self-hosted.mdx b/docs/pages/database-access/guides/postgres-self-hosted.mdx index 9cf6758b89c26..988b4bb93716e 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](../auto-user-provisioning/postgres.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 2943f4af24e5e..a67a1fc735a58 100644 --- a/docs/pages/database-access/guides/rds.mdx +++ b/docs/pages/database-access/guides/rds.mdx @@ -435,6 +435,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 0470205cd9b82..41e7c61f80002 100644 --- a/docs/pages/database-access/guides/redshift-serverless.mdx +++ b/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!) 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.