Add query timeout option to cancel long-running queries

[Copilot]

This PR adds a new query_timeout configuration option that automatically cancels queries that exceed a specified duration, helping prevent runaway queries from consuming resources indefinitely.

Overview

The query_timeout option accepts a value in seconds (including fractional values) or null/undefined to disable timeouts. When a query exceeds the timeout duration, it's automatically cancelled with a PostgreSQL error code 57014.

Usage

const sql = postgres({
  host: 'localhost',
  database: 'mydb',
  query_timeout: 30  // Cancel queries after 30 seconds
})

try {
  const result = await sql`SELECT * FROM large_table WHERE expensive_operation = true`
  console.log('Query completed successfully')
} catch (error) {
  if (error.code === '57014') {
    console.log('Query was cancelled due to timeout')
  }
}

Implementation Details

• Timer Management: Timeout timers are started when query execution begins and cleared when queries complete normally
• Error Handling: Timeout cancellations use error code '57014' with message "canceling statement due to timeout" (distinguishable from manual cancellation)
• Memory Safety: Timers are properly cleared on query completion, manual cancellation, or connection cleanup
• API Compatibility: Fully backward compatible - existing code continues to work unchanged

Configuration Options

• query_timeout: null - No timeout (default behavior)
• query_timeout: 30 - 30 second timeout
• query_timeout: 0.5 - 500ms timeout for fast queries
• query_timeout: undefined - Same as null

TypeScript Support

Full TypeScript definitions are included:

interface Options {
  query_timeout?: number | null | undefined;
}

Testing

Added comprehensive tests covering:

• Long-running queries are cancelled after timeout
• Quick queries complete normally within timeout period
• Proper error codes and messages for timeout scenarios
• Integration with existing cancellation mechanisms

This feature addresses the common need for query timeout protection in production applications while maintaining full compatibility with existing postgres.js usage patterns.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• nonexistent
  • Triggering command: node /tmp/test_timeout_timing.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.