diff --git a/asyncpg/connection.py b/asyncpg/connection.py index 71fb04f8..a496eb3b 100644 --- a/asyncpg/connection.py +++ b/asyncpg/connection.py @@ -341,6 +341,23 @@ async def execute( :param float timeout: Optional timeout value in seconds. :return str: Status of the last SQL command. + When query arguments are provided, the command is executed as a + prepared statement and is eligible for the connection's LRU + statement cache. + + The status string for an ``INSERT`` has the form + ``INSERT ``. A result such as ``INSERT 0 0`` is a + legitimate outcome for queries that insert zero rows (for example, + ``INSERT ... SELECT ... WHERE false``), and does not indicate a + failure. To confirm that a single row was inserted, check the + status string: + + .. code-block:: pycon + + >>> result = await con.execute( + ... 'INSERT INTO mytab (a) VALUES ($1)', 1) + >>> assert result == 'INSERT 0 1' + .. versionchanged:: 0.5.4 Made it possible to pass query arguments. """ diff --git a/docs/api/index.rst b/docs/api/index.rst index c0fa8d1b..7e7f9f1f 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -50,7 +50,20 @@ a need to run the same query again. asyncpg automatically maintains a small LRU cache for queries executed during calls to the :meth:`~Connection.fetch`, :meth:`~Connection.fetchrow`, - or :meth:`~Connection.fetchval` methods. + or :meth:`~Connection.fetchval` methods. :meth:`~Connection.execute` + also uses the cache when query arguments are provided. + + To confirm that an ``INSERT`` succeeded, inspect the command status string + returned by :meth:`~Connection.execute`: + + .. code-block:: pycon + + >>> result = await con.execute( + ... 'INSERT INTO mytab (a) VALUES ($1)', 1) + >>> assert result == 'INSERT 0 1' + + An ``INSERT 0 0`` status is a legitimate result for queries that insert + zero rows (for example, ``INSERT INTO foo (SELECT * WHERE false)``). .. warning::