Connection pool docs inconsistency?

[elliotwaite]

What happens to a connection's prepared statements when a connection is released?

The Connection Pool docs say prepared statements become invalid once a connection is released:

Prepared statements and cursors returned by Connection.prepare() and Connection.cursor() become invalid once the connection is released.

But the Pool docs say that prepared statements are not reset when a connection is released:

Once a connection is released, it’s reset to close all open cursors and other resources except prepared statements.

Is there a difference between a prepared statement becoming invalid and being reset, or are the docs incorrect in one of these places, or am I misunderstanding something?

[elprans]

The former point refers to prepared statement objects returned explicitly from Connection.prepare(). Automatic prepared statements created and managed by asyncpg are not deallocated when a connection is released.

[elliotwaite]

Oh, I see. Thanks for the explanation. I also read through more of the code to try to improve my understanding, and my current understanding is:

• Prepared statements created by Connection.prepare() are not stored in the connection's cache and are closed when the connection is closed or when all references to that prepared statement are garbage collected.
• On the other hand, when using the Connection methods .execute(), .executemany(), .fetch(), fetchrow(), .fetchval(), or .cursor(), an implicit prepared statement is created, and if the connection's cache is enabled, that prepared statement is stored in the connection's cache, otherwise the prepared statement will not be stored in the cache and it will be an unnamed prepared statement, which is by definition is single-use only and is invalidated upon use.

Please let me know if any of that is incorrect.

Also, I'll close this issue since I was just misunderstanding the docs.