Deprecate Pool.acquire() and Pool.release()

docs/api/asyncio_con.rst

@@ -351,10 +351,16 @@ Connection Pools
         Max number of connections in the pool.
 
     :param on_acquire:
+        **Deprecated**. Use the qurery methods on :py:class:`Pool` instead
+        of acquiring a connection.
+
         A coroutine to prepare a connection right before it is returned
         from :py:meth:`Pool.acquire() <edgedb.AsyncIOPool.acquire>`.
 
     :param on_release:
+        **Deprecated**. Use the qurery methods on :py:class:`Pool` instead
+        of acquiring a connection.
+
         A coroutine called when a connection is about to be released
         to the pool.
 
@@ -389,40 +395,22 @@ Connection Pools
                 async with tx:
                     await tx.query('SELECT {1, 2, 3}')
 
-    To hold on to a specific connection object, use the ``pool.acquire()`` API:
-
-    .. code-block:: python
-
-        async with edgedb.create_async_pool(user='edgedb') as pool:
-            async with pool.acquire() as con:
-                await con.query('SELECT {1, 2, 3}')
-
-    Or directly ``await``:
-
-    .. code-block:: python
-
-        pool = await edgedb.create_async_pool(user='edgedb')
-        con = await pool.acquire()
-        try:
-            await con.query('SELECT {1, 2, 3}')
-        finally:
-            await pool.release(con)
-
 
 .. py:class:: AsyncIOPool()
 
     A connection pool.
 
-    A connection pool can be used to manage a set of connections to the database.
-    Connections are first acquired from the pool, then used, and then released
-    back to the pool.  Once a connection is released, it's reset to close all
-    open cursors and other resources *except* prepared statements.
+    A connection pool can be used in a similar manner as a single connection
+    except that the pool is safe for concurrent use.
 
     Pools are created by calling
     :py:func:`~edgedb.create_async_pool`.
 
     .. py:coroutinemethod:: acquire()
 
+        **Deprecated**. Use the qurery methods on :py:class:`Pool` instead
+        of acquiring a connection.
+
         Acquire a database connection from the pool.
 
         :return: An instance of :py:class:`AsyncIOConnection`.
@@ -446,6 +434,9 @@ Connection Pools
 
     .. py:coroutinemethod:: release(connection)
 
+        **Deprecated**. Use the qurery methods on :py:class:`Pool` instead
+        of acquiring a connection.
+
         Release a database connection back to the pool.
 
         :param AsyncIOConnection connection:

docs/usage.rst

@@ -176,17 +176,6 @@ Below is an example of a connection pool usage:
     app = loop.run_until_complete(init_app())
     web.run_app(app)
 
-You can also acquire connection from the pool:
-
-.. code-block:: python
-
-    async with pool.acquire() as conn:
-        result = await conn.query_single_json(
-            '''
-                SELECT User {first_name, email, bio}
-                FILTER .name = <str>$username
-            ''', username=username)
-
 But if you have a bunch of tightly related queries it's better to use
 transactions.
 

edgedb/asyncio_pool.py

@@ -685,6 +685,10 @@ def acquire(self):
             finally:
                 await pool.release(con)
         """
+        warnings.warn(
+            'The "acquire()" method is deprecated and is scheduled to be '
+            'removed. Use the query methods on AsyncIOPool instead.',
+            DeprecationWarning, 2)
         return PoolAcquireContext(self, timeout=None, options=self._options)
 
     async def release(self, connection):
@@ -694,6 +698,10 @@ async def release(self, connection):
             A :class:`~edgedb.asyncio_con.AsyncIOConnection` object
             to release.
         """
+        warnings.warn(
+            'The "release()" method is deprecated and is scheduled to be '
+            'removed. Use the query methods on AsyncIOPool instead.',
+            DeprecationWarning, 2)
         await self._impl.release(connection)
 
     async def aclose(self):