PHP pg_cancel_query() Function: Usage and Examples

Requests cancellation of a query on a PostgreSQL connection.

The objective is to understand the behavior and operational limits, not only the method name.

What It Does

Requests cancellation of a query on a PostgreSQL connection.

Syntax and Return Value

pg_cancel_query(...)

The return value and exceptional cases depend on the call described here: Cancellation is best effort and not a substitute for statement timeouts or safe transaction recovery.

Requirements: install and enable the corresponding PHP driver or extension and configure the service before running the examples.

Example 1: Basic Use

Requires a reachable PostgreSQL server and the pgsql PHP extension; asynchronous requests must be drained with pg_get_result.

<?php
$host = getenv('DB_HOST'); $user = getenv('DB_USER'); $password = getenv('DB_PASSWORD'); $database = getenv('DB_NAME');
if (!$host || !$user || $password === false || !$database) throw new RuntimeException('Missing PostgreSQL configuration');
$pg = pg_connect('host=' . $host . ' dbname=' . $database . ' user=' . $user . ' password=' . $password);
if (!$pg) { throw new RuntimeException('PostgreSQL connection failed'); }
pg_send_query($pg, "SELECT pg_sleep(8)");
pg_cancel_query($pg);
while (($result = pg_get_result($pg)) !== false) { echo pg_result_error($result); }

Example 2: A Second Scenario

Requires a reachable PostgreSQL server and the pgsql PHP extension; asynchronous requests must be drained with pg_get_result. This additional check distinguishes the method's result from connection or statement state.

<?php
$host = getenv('DB_HOST'); $user = getenv('DB_USER'); $password = getenv('DB_PASSWORD'); $database = getenv('DB_NAME');
if (!$host || !$user || $password === false || !$database) throw new RuntimeException('Missing PostgreSQL configuration');
$pg = pg_connect('host=' . $host . ' dbname=' . $database . ' user=' . $user . ' password=' . $password);
if (!$pg) { throw new RuntimeException('PostgreSQL connection failed'); }
pg_send_query($pg, "SELECT pg_sleep(8)");
pg_cancel_query($pg);
while (($result = pg_get_result($pg)) !== false) { echo pg_result_error($result); }
echo "Post-cancellation connection status: " . pg_connection_status($pg);

Example 3: Practical Checks

Requires a reachable PostgreSQL server and the pgsql PHP extension; asynchronous requests must be drained with pg_get_result. This additional check distinguishes the method's result from connection or statement state.

<?php
$host = getenv('DB_HOST'); $user = getenv('DB_USER'); $password = getenv('DB_PASSWORD'); $database = getenv('DB_NAME');
if (!$host || !$user || $password === false || !$database) throw new RuntimeException('Missing PostgreSQL configuration');
$pg = pg_connect('host=' . $host . ' dbname=' . $database . ' user=' . $user . ' password=' . $password);
if (!$pg) { throw new RuntimeException('PostgreSQL connection failed'); }
pg_send_query($pg, "SELECT pg_sleep(8)");
pg_cancel_query($pg);
while (($result = pg_get_result($pg)) !== false) { echo pg_result_error($result); }
echo "Cancellation is only a request to the PostgreSQL server";

Important Behavior and Edge Cases

Cancellation is best effort and not a substitute for statement timeouts or safe transaction recovery.

For production use, also account for error handling, data validation, resource limits and environment-specific driver behavior.

Comparison with Related Approaches

Common Beginner Mistakes

Key Takeaways

• Requests cancellation of a query on a PostgreSQL connection.
• Cancellation is best effort and not a substitute for statement timeouts or safe transaction recovery.
• pg_connection_busy checks whether asynchronous results are still pending.

Choose this API or pattern when its exact semantics match your task, and verify the result against the database driver and runtime used by your application.