v1.0.2 – async-safe PgPool recycling, COPY streaming, cursor chunking

Added

• High-volume COPY support:

  • copy_in_start, copy_in_send_chunk, copy_in_finish
  • copy_out_start, copy_out_read_chunk
  • New PgCopyResult type with rows_affected and structured error info

• Server-side cursor streaming:

  • cursor_declare, cursor_fetch_chunk, cursor_close
  • New PgCursorChunk type for incremental FETCH FORWARD
  • Supports chunked iteration over large result sets without loading them fully

• Async connection return path:

  • PgPool::release_connection_async() drains pending libpq results before reusing a connection
  • PgTransaction now always uses the async release path on commit(), rollback(), finish(), abort()

Changed

• PgPool::release_connection() now enforces "idle or die":

  • a connection is only recycled if it is fully idle (no pending PGresult / no busy libpq state)
  • if not idle, the connection is retired and live_count_ is decremented
  • this prevents the classic libpq race "another command is already in progress" when multiple coroutines reuse the same physical PGconn

• Connection lifecycle is now explicit:

  • dirty connections are not put back into the idle queue
  • the pool transparently creates a fresh connection later when needed

Docs

• pool.md updated with:

  • connection lifecycle
  • dirty connection retirement
  • async vs sync release semantics
  • COPY / cursor overview

• transaction.md updated with:

  • transaction lifecycle
  • safe handoff back to the pool via release_connection_async
  • subtransaction behavior

• results.md updated with:

  • PgCopyResult
  • PgCursorChunk
  • structured error reporting for COPY and cursor streaming

• quickstart.md updated with:

  • COPY IN / COPY OUT examples
  • cursor-based chunked fetch example
  • transaction usage with coroutines

Impact

• Safer concurrent use of the pool across many coroutines/threads
• No more "in-progress" libpq errors leaking between unrelated tasks
• First-class bulk data ingest/export and incremental result streaming