docs(pool): mention running an empty query on check in news file

refactor(pool): replace --ping with empty string

perf(pool): replace SELECT 1 with an empty query

Merge pull request #746 from ankane/copy-performance

Improve performance of copy

perf(copy): only flush at every row on copy on macOS

With some benchmark, it seems that on Linux and Windows performances are worse.
See #746 for details.

test(copy): add minimal copy benchmark framework

Improve performance of copy

fix(pool): avoid possible deadlock (until timeout) on pool closing

With the previous change to avoid finding open connections in the pool
(#784), stopping the worker was moved into the critical section. This
can create a deadlock in case a worker is in the process of obtaining a
new connection, because putting it to the pool requires the lock. The
deadlock only last for the default 5s timeout passed to _stop_workers().

Solve the problem by guarding _add_to_pool() to avoid it to try to add
the connection if the pool is closed.

However, refactor the pool closing sequence too and close the workers
and other resources that now out of the state outside the critical
section to keep the operation running under lock to a minimum.

test: fix running pool tests using Psycopg 3.1

Avoid using Capabilities at import time in the test suite.

Merge branch 'fix-734'

fix(c): solve undefined behaviour caused by unaligned access

Close #734

ci: add test to check for misaligned memory access

fix: fix handling of floating point values for connect_timeout

Merge pull request #780 from dlax/cancel-safe-timeout

feat: add a timeout parameter to Connection.cancel_safe()

refactor: set the meaningful timeout for _try_cancel() as a default

fix: avoid to swallow exceptions in public cancel methods

Only ignore errors in every internal usage, in order to cancel as a best
effort and don't clobber a likely more meaningful exception.

docs: adjust cancel_safe() docstring

docs: reword notes on cancellation

test: more uniform treatment of timeout approx check

refactor: check if cancel safe is implemented via capabilities

test(proxy): use 127.0.0.1 rather than localhost

Try to fix the flakiness shown by deaf_listen() in CI. Maybe there is a
race condition in listen()/connect() but I have also seen problems
related with localhost in the /etc/hosts file and ipv6, so let's first
try this.

feat: add a timeout parameter to Connection.cancel_safe()

This will only work for PGcancelConn, i.e. libpq >= 17, or thanks to
added waiting logic in AsyncConnection's implementation; so we add a
note about the limitation in Connection's documentation.

feat: add libpq interface for retrieving results in chunks

https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=4643a2b265e967cc5f13ffa0c7c6912dbb3466d0

fix(c): fix the goto label in the HAVE_POLL branch of wait_c_impl()

This resolves the following warning when building the extension module:

    $ python psycopg_c/setup.py build_ext -i
    [...]
    building 'psycopg_c._psycopg' extension
    x86_64-linux-gnu-gcc -Wsign-compare -DNDEBUG -g -fwrapv -O2 -Wall -g -fstack-protector-strong -Wformat -Werror=format-security -g -fwrapv -O2 -fPIC -I/home/denis/.local/pgsql/include -I/home/denis/src/psycopg3/.venv/include -I/usr/include/python3.11 -c psycopg_c/_psycopg.c -o build/temp.linux-x86_64-cpython-311/psycopg_c/_psycopg.o
    psycopg_c/_psycopg.c: In function ‘wait_c_impl’:
    psycopg_c/_psycopg.c:1649:1: warning: label ‘error’ defined but not used [-Wunused-label]
     1649 |
          | ^

Merge branch 'cancel-exceptions-swallow'

fix: avoid explicit str() call when logging exception

This was done as paranoia check for Sentry which might uses the repr of
the exception even if we asked for `%s` and therefore might leak
secrets, but frankly it's not our responsibility.

https://github.com/getsentry/sentry-python/issues/2417

refactor: clearer cancel_safe implementation

Avoid catching NotSupported, just check for the libpq version.

Also avoid the half exception handler in `_cancel_gen()`: as in the
legacy branch, warn and ignore any error happening in the outermost
method, without adding an ignore exception policy in an implementation
method.

Close #778.

refactor: drop _try_cancel internal method.

This method was useful before introducing cancel_safe, which is now the
function of choice for internal cancelling.

Also refactor the exception handling to account for possible errors in
`PGcancel.cancel()`, not only in `PGconn.get_cancel()`, to make sure to
not clobber an exception bubbling up with ours, whatever happens to the
underlying connection.

Merge branch 'capabilities'

refactor(capabilities): add caching to capabilities check

refactor(pipeline): use Capabilities to implement is_supported

docs: add capabilities documentation

feat: add psycopg.capability

Close #772

refactor: use consistently the version_pretty() function

feat: add pq.version_pretty() function

Merge branch 'async-to-sync-refactor'

refactor(async-to-sync): rename --convert-all option to --all

chore(async-to-sync): drop --all argument

Working on all inputs is a meaningful default.

refactor(async-to-sync): use pattern matching for more compact tests

refactor(async-to-sync): simpler pattern to convert string literals

fix(pool): make sure there are no connection in the pool after close()

The case has been reported in #784. While not easy to reproduce, it
seems that it might be caused by the pool being closed while a worker is
still trying to create a connection, which will be put in the _pool
state after supposedly no other operation should have been performed.

Stop the workers and then empty the pool only after they have stopped to
run.

Also refactor the cleanup of the pool and waiting queue, moving them
to close(). There is no reason why a method called "stop workers" should
empty them, and there is no other code path that use such feature.

Close #784.

test: replace deaf_port fixture with deaf_listen method on proxy

This allows to replace the listening proxy port with a port that blocks
connection and to write more easily cancel timeout tests (as in #780).

tests: fix allow to skip running the pool tests again

`pytest -m not pool` should allow to skip the pool test. However,
because of the attribute access at import time to define the test
marker, import failed as well.

Convert the marker to strings which will be used in a getattr by the
fixture. Extend async-to-sync to convert the pool classes names from the
string too.

test: add missing prepared async tests

Sync and async sides diverged because the async-to-sync check in CI was
pretty much disabled by the lack of the -B.

ci: restore async-to-sync check to check all the files

test(pool): more lenient timeout in reconnect test timings

chore: ignore spelling in html files

These files are generated by cython to display the C code generated...
and are a mess.

Merge pull request #763 from dlax/pg17/non-blocking-pqcancel

Add encrypted and non-blocking cancellation

fix: fix type signature of to_thread() compat

docs: shorten news entry about Connection.cancel_safe()

docs: improve cancel_safe documentation

feat: use non-blocking cancellation upon Copy termination

The logic of Copy termination, in finish(), is reworked so that
connection cancellation is invoked from there directly instead of from
_end_copy_out_gen() as we cannot call async code from the generator.

feat: fall back to cancel() in cancel_safe() for libpq < 17

We run this in a thread executor in the AsyncConnection.
As asyncio's to_thread() is not available in Python 3.8, so we add a
compat layer.

feat: add encrypted and non-blocking cancellation

We introduce Connection.cancel_safe() which uses the encrypted and
non-blocking libpq cancellation API available with PostgreSQL 17. As a
non-blocking entry point, cancel_safe() delegates to a generator function,
namely _cancel_gen(). If the libpq version is too old, the method raises
a NotSupportedError.

CTRL+C handling (in Connection.wait() or Cursor.stream()) also uses the
non-blocking cancellation but falls back to old method if the former is
not supported.

The behavior of cancel() method (either on Connection or
AsyncConnection) is kept unchanged to use the old cancellation API.

feat: add generators.cancel()

This is a PQGenConn generator as the socket for the PGcancelConn needs
to be retrieved after (at least) the first poll() call.

Merge pull request #773 from psycopg/pgbouncer-prepare

Make prepared statements compatible with PgBouncer

feat(prepare): allow setting connection.prepare_max to None

docs(prepare): add note about PgBouncer max prepared statements setting

docs(prepare): add notes about the PgBouncer and prepared statements

feat(prepare): send Close messages to deallocate when possible

This allows for compatibility with PgBouncer, but requires libpq v17 at
least.

refactor(prepare): queue statement names, not SQL commands

refactor(prepare): make maintenance operation a PQGen generator

This will allow us to replace the SQL commands with protocol messages.

docs(readme): fix hyperlink in bullet list

The problem was reported in #775, but the file is not wrong, and
rst2html renders correctly without warnings.

The problem is that the Github reST implementation doesn't get the
hyperlinks indented at bullet list level right.

My preference is to move the links out of the list rather than inserting
the URLs in the flow of the text and get awkward newlines or long lines.

docs: drop spurious word in readme

Close #775

test: fix test suite import on master with Python 3.1

test: fix cancel connection status test on Unix socket connection

Merge branch 'libpq-cancel-nonblocking'

docs: document the ALLOCATED ConnStatus value

fix: prevent usage of finished PGcancelConn

Similarly to PGconn, PGcancelConn must not be used after .finish(); we
raise an OperationalError to prevent segfault when the connection
pointer is NULL.

tests: simplify PGcancelConn tests

We split the previous (misnamed) test_cancel_nonblocking() into
test_cancel_conn_blocking() and test_cancel_conn_nonblocking()
respectively checking PQcancelBlocking() and
PQcancelStart()/PQcancelPoll().

The cancellable_query() is now responsible for creating the monitor_conn
and uses a PGconn value, coming from the pgconn fixture in tests.

feat: add libpq interface for encrypted and non-blocking cancellation

Encrypted and non-blocking cancellation should be part PostgreSQL 17:
- https://commitfest.postgresql.org/37/3511/
- https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=61461a300c1cb5d53955ecd792ad0ce75a104736

We here add the interface for libpq functions for this feature.

An extra test is introduced, it closely reproduces
src/test/modules/libpq_pipeline/libpq_pipeline::test_cancel() in
PostgreSQL test suite.

The error_message property of PGcancelConn is directly an str and
PGcancelConn has no encoding specified and all messages come from the
client (libpq).

tests: introduce a wait() helper function pq.PGconn tests

Merge branch 'conn-generator-refactoring'

refactor: rename wait functions 'timeout' parameter to 'interval'

refactor: handle timeout in the connection generator, not the waiting function

The waiting function is supposed to be generic, the timeout is a policy
decision of the generator.

This change aligns the semantics of the `timeout` parameter of `wait_conn()`
to the one of the other wait functions: the timeout is actually an
interval. It will be renamed to clarify that in a followup commit.

style: use literals instead of the concatenation operator for long strings

The reason we were using operators was to stop async_to_sync to generate
a line too long and incur in the flake8 ires.

MR #764 suggests to disable line length check altogether, but we can use
per-file ignore, as there will not be many cases to manage.

docs: add a note to remember why flake8 configuration is repeated

chore: regenerate _pq_ctypes.pyi

Following commit a7f280227923ccb5de8928f7335e092531eedea1.

Merge branch 'mypy-love'

refactor(c): mor compact guard for unsupported libpq versions

refactor: less verbose pattern to manage optional libpq functions

lint: avoid mypy warning in _pq_ctypes.py

I can't find how my editor is set up, but it doesn't complain on this
file, and yet calling mypy on this file only will find several error.

Having seen @dlax adding `type: ignore[no-any-return]` comments makes me
want to fix this.

docs: let the 'pq' role possibly link to "devel" PostgreSQL docs

If we now set libpq_docs_version to 'devel', the pq Sphinx role will use
the master branch when looking libpq.sgml and the 'devel' URL component
when linking to libpq online documentation.

fix: more careful stripping of error prefixes

Only strip the known prefixes, both in English and in the currently
known localizations.

Added script to generate regexp to match every backend localization. The
script was executed on PostgreSQL commit f4ad0021af (on master branch,
before v17).

Close #752.

Merge pull request #744 from dlax/async-to-sync-jobs

feat(tools): possibly run async_to_sync.py concurrently

feat(tools): check last modification times in async_to_sync.py

We now only process _async.py files with a modification time higher than
their sync counterpart. A -B,--convert-all option is added to force
conversion of all (specified) input files and skip last-modification
time check.

feat(tools): add a -L,--log-level option to async_to_sync.py

We'll use DEBUG messages in the next commit.

feat(tools): run async_to_sync.py concurrently

Multi-processing is used by default (using all available processors),
but can be disabled or limited with the -j/--jobs option.

test: add pool package to django tests

It seems needed in the current main branch.

docs: fix a typo in FinishedPGconn docstring

docs: fix missing `async` in example

Close #740.

docs(pool): reorder sections in a way that makes more sense

docs(pool): add box warning against opening async pools on init

fix(pool): make opening an async connection pool in the constructor a runtime warning

Deprecation warnings are ignored by default and easy to miss.

Close #737.

ci: skip refcount tests on scheduled jobs

fix: avoid to create reference loops in datetime adapters

Setting the reference to a bound method in the state creates a reference
loop.

The issue is minimal because the gc will be able to break these loops
anyway and because it mostly happens with exotic or unsupported
date/interval styles.

docs: fix typo in release notes

chore: bump psycopg package version to 3.1.18

fix(c): drop spurious loop break in pipeline_communicate

This makes the Python and the C implementation more similar. The
difference was unexpected but apparently harmless. See #431

tests: don't depend on ConnDict

Added in 3.2, so can't run the pool tests using Psycopg 3.1