:caption: Contents:
../adaptation
+ ../prepared
../copy
../async
.. note:: You can use :ref:`with conn.cursor(): ...<usage>`
to close the cursor automatically when the block is exited.
- .. automethod:: execute(query: Query, params: Optional[Args]=None) -> Cursor
+ .. automethod:: execute(query, params=None, prepare=None) -> Cursor
- :param query: The query to execute
+ :param query: The query to execute.
:type query: `!str`, `!bytes`, or `sql.Composable`
- :param params: The parameters to pass to the query, if any
+ :param params: The parameters to pass to the query, if any.
:type params: Sequence or Mapping
+ :param prepare: Force (`!True`) or disallow (`!False`) preparation of
+ the query. By default (`!None`) prepare automatically. See
+ :ref:`prepared-statements`.
+ :type prepare: `!bool`
- The cursor is what returned calling `cursor()` without parameters. See
- :ref:`query-parameters` for all the details about executing queries.
+ The cursor is what returned calling `cursor()` without parameters. The
+ parameters are passed to its `~Cursor.execute()` and the cursor is
+ returned.
+
+ See :ref:`query-parameters` for all the details about executing
+ queries.
.. rubric:: Transaction management methods
.. __: https://www.postgresql.org/docs/current/multibyte.html
+
.. attribute:: info
TODO
+
+ .. autoattribute:: prepare_threshold
+
+ Number of times a query is executed before it is prepared.
+
+ If it is set to 0, every query is prepared the first time is executed.
+ If it is set to `!None`, prepared statements are disabled on the
+ connection.
+
+ See :ref:`prepared-statements` for details.
+
+
+ .. autoattribute:: prepared_max
+
+ Maximum number of prepared statements on the connection.
+
+ If more queries need to be prepared, old ones are deallocated__.
+
+ .. __: https://www.postgresql.org/docs/current/sql-deallocate.html
+
+
.. rubric:: Methods you can use to do something cool
.. automethod:: notifies
automatically when the block is exited, but be careful about
the async quirkness: see :ref:`async-with` for details.
- .. automethod:: execute(query: Query, params: Optional[Args]=None) -> AsyncCursor
+ .. automethod:: execute(query, params=None, prepare=None) -> AsyncCursor
.. automethod:: commit
.. automethod:: rollback
.. rubric:: Methods to send commands
- .. automethod:: execute(query: Query, params: Optional[Args]=None) -> Cursor
+ .. automethod:: execute(query, params=None, prepare=None) -> Cursor
- :param query: The query to execute
+ :param query: The query to execute.
:type query: `!str`, `!bytes`, or `sql.Composable`
- :param params: The parameters to pass to the query, if any
+ :param params: The parameters to pass to the query, if any.
:type params: Sequence or Mapping
+ :param prepare: Force (`!True`) or disallow (`!False`) preparation of
+ the query. By default (`!None`) prepare automatically. See
+ :ref:`prepared-statements`.
Return the cursor itself, so that it will be possible to chain a fetch
operation after the call.
automatically when the block is exited, but be careful about
the async quirkness: see :ref:`async-with` for details.
- .. automethod:: execute(query: Query, params: Optional[Args]=None) -> AsyncCursor
+ .. automethod:: execute(query, params=None, prepare=None) -> AsyncCursor
.. automethod:: executemany(query: Query, params_seq: Sequence[Args])
.. automethod:: copy(statement: Query) -> AsyncCopy
* :ref:`genindex`
* :ref:`modindex`
-* :ref:`search`
"""
Patch autodoc in order to use information found by `recover_defined_module`.
"""
- from sphinx.ext.autodoc import Documenter
+ from sphinx.ext.autodoc import Documenter, AttributeDocumenter
- orig_get_real_modname = Documenter.get_real_modname
+ orig_doc_get_real_modname = Documenter.get_real_modname
+ orig_attr_get_real_modname = AttributeDocumenter.get_real_modname
- def fixed_get_real_modname(self):
+ def fixed_doc_get_real_modname(self):
if self.object in recovered_classes:
return recovered_classes[self.object]
- return orig_get_real_modname(self)
+ return orig_doc_get_real_modname(self)
- Documenter.get_real_modname = fixed_get_real_modname
+ def fixed_attr_get_real_modname(self):
+ if self.parent in recovered_classes:
+ return recovered_classes[self.parent]
+ return orig_attr_get_real_modname(self)
+
+ Documenter.get_real_modname = fixed_doc_get_real_modname
+ AttributeDocumenter.get_real_modname = fixed_attr_get_real_modname
def walk_modules(d):
--- /dev/null
+.. currentmodule:: psycopg3
+
+.. index::
+ single: Prepared statements
+
+.. _prepared-statements:
+
+Prepared statements
+===================
+
+`!psycopg3` uses an automatic system to manage *prepared statements*. When a
+query is prepared, its parsing and planning is stored in the server session,
+so that further executions of the same query on the same connection (even with
+different parameters) are optimised.
+
+A query is prepared automatically after it is executed more than
+`~Connection.prepare_threshold` times on a connection. `!psycopg3` will make
+sure that no more than `~Connection.prepared_max` statements are planned: if
+further queries are executed, the least recently used ones are deallocated and
+the associated resources freed.
+
+Statement preparation can be controlled in several ways:
+
+- You can decide to prepare a query immediately by passing ``prepare=True`` to
+ `Connection.execute()` or `Cursor.execute()`. The query is prepared, if it
+ wasn't already, and executed as prepared from its first use.
+
+- Conversely, passing ``prepare=False`` to `!execute()` will avoid to prepare
+ the query, regardless of the number of times it is executed. The default of
+ the parameter is `!None`, meaning that the query is prepared if the
+ conditions described above are met.
+
+- You can disable the use of prepared statements on a connection by setting
+ its `~Connection.prepare_threshold` attribute to `!None`.
+
+.. seealso::
+
+ The `PREPARE`__ PostgreSQL documentation contains plenty of details about
+ prepared statements in PostgreSQL.
+
+ Note however that `!psycopg3` doesn't use SQL statements such as
+ :sql:`PREPARE` and :sql:`EXECUTE`, but protocol level commands such as the
+ ones exposed by :pq:`PQsendPrepare`, :pq:`PQsendQueryPrepared`.
+
+ .. __: https://www.postgresql.org/docs/current/sql-prepare.html
cursor_factory: Type["BaseCursor[Any]"]
+ # Number of times a query is executed before it is prepared.
prepare_threshold: Optional[int] = 5
- """
- Number of times a query is executed before it is prepared.
-
- `!None` to disable preparing queries automatically.
- """
+ # Maximum number of prepared statements on the connection.
prepared_max = 100
- """
- Maximum number of prepared statements on the connection.
-
- If more are prepared, the least used are deallocated.
- """
def __init__(self, pgconn: "PGconn"):
self.pgconn = pgconn # TODO: document this
projects / thirdparty / psycopg.git / commitdiff
