Update README and setup.py to reflect the current state better

Author: elprans

README.rst

@@ -14,7 +14,8 @@ framework.  You can read more about asyncpg in an introductory
 `blog post <http://magic.io/blog/asyncpg-1m-rows-from-postgres-to-python/>`_.
 
 asyncpg requires Python 3.5 or later and is supported for PostgreSQL
-versions 9.2 to 12.
+versions 9.5 to 13.  Older PostgreSQL versions or other databases implementing
+the PostgreSQL protocol *may* work, but are not being actively tested.
 
 
 Documentation
@@ -31,10 +32,11 @@ In our testing asyncpg is, on average, **3x** faster than psycopg2
 (and its asyncio variant -- aiopg).
 
 .. image:: performance.png
-    :target: http://magic.io/blog/asyncpg-1m-rows-from-postgres-to-python/
+    :target: https://gistpreview.github.io/?b8eac294ac85da177ff82f784ff2cb60
 
 The above results are a geometric mean of benchmarks obtained with PostgreSQL
-`client driver benchmarking toolbench <https://github.com/MagicStack/pgbench>`_.
+`client driver benchmarking toolbench <https://github.com/MagicStack/pgbench>`_
+in November 2020.
 
 
 Features
@@ -74,7 +76,10 @@ Basic Usage
     async def run():
         conn = await asyncpg.connect(user='user', password='password',
                                      database='database', host='127.0.0.1')
-        values = await conn.fetch('''SELECT * FROM mytable''')
+        values = await conn.fetch(
+            'SELECT * FROM mytable WHERE id = $1',
+            10,
+        )
         await conn.close()
 
     loop = asyncio.get_event_loop()

docs/faq.rst

@@ -18,18 +18,21 @@ of asyncpg at some point in the future.
 Can I use asyncpg with SQLAlchemy ORM?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Short answer: no.  asyncpg uses asynchronous execution model
-and API, which is fundamentally incompatible with SQLAlchemy.
-However, it is possible to use asyncpg and SQLAlchemy Core
-with the help of a third-party adapter, such as asyncpgsa_ or databases_.
+Yes.  SQLAlchemy version 1.4 and later supports the asyncpg dialect natively.
+Please refer to its documentation for details.  Older SQLAlchemy versions
+may be used in tandem with a third-party adapter such as
+asyncpgsa_ or databases_.
 
 
 Can I use dot-notation with :class:`asyncpg.Record`?  It looks cleaner.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We decided against making :class:`asyncpg.Record` a named tuple
 because we want to keep the ``Record`` method namespace separate
-from the column namespace.
+from the column namespace.  That said, you can provide a custom ``Record``
+class that implements dot-notation via the ``record_class`` argument to
+:func:`connect() <asyncpg.connection.connect>` or any of the Record-returning
+methods.
 
 
 Why can't I use a :ref:`cursor <asyncpg-api-cursor>` outside of a transaction?
@@ -56,15 +59,23 @@ already exists`` errors, you are most likely not connecting to the
 PostgreSQL server directly, but via
 `pgbouncer <https://pgbouncer.github.io/>`_.  pgbouncer, when
 in the ``"transaction"`` or ``"statement"`` pooling mode, does not support
-prepared statements.  You have two options:
+prepared statements.  You have several options:
 
-* if you are using pgbouncer for connection pooling to a single server,
+* if you are using pgbouncer only to reduce the cost of new connections
+  (as opposed to using pgbouncer for connection pooling from
+  a large number of clients in the interest of better scalability),
   switch to the :ref:`connection pool <asyncpg-connection-pool>`
   functionality provided by asyncpg, it is a much better option for this
   purpose;
 
-* if you have no option of avoiding the use of pgbouncer, then you need to
-  switch pgbouncer's ``pool_mode`` to ``session``.
+* disable automatic use of prepared statements by passing
+  ``statement_cache_size=0``
+  to :func:`asyncpg.connect() <asyncpg.connection.connect>` and
+  :func:`asyncpg.create_pool() <asyncpg.pool.create_pool>`
+  (and, obviously, avoid the use of
+  :meth:`Connection.prepare() <asyncpg.connection.Connection.prepare>`);
+
+* switch pgbouncer's ``pool_mode`` to ``session``.
 
 
 Why do I get ``PostgresSyntaxError`` when using ``expression IN $1``?

performance.png

@@ -25,7 +25,7 @@
 from setuptools.command import build_ext as setuptools_build_ext
 
 
-CYTHON_DEPENDENCY = 'Cython==0.29.20'
+CYTHON_DEPENDENCY = 'Cython(>=0.29.20,<0.30.0)'
 
 # Minimal dependencies required to test asyncpg.
 TEST_DEPENDENCIES = [
@@ -263,6 +263,7 @@ def finalize_options(self):
         'Programming Language :: Python :: 3.6',
         'Programming Language :: Python :: 3.7',
         'Programming Language :: Python :: 3.8',
+        'Programming Language :: Python :: 3.9',
         'Programming Language :: Python :: Implementation :: CPython',
         'Topic :: Database :: Front-Ends',
     ],