Merge branch 'master' into version-0.6.0

Author: aminalaee

README.md

@@ -29,21 +29,22 @@ Databases is suitable for integrating against any async Web framework, such as [
 $ pip install databases
 ```
 
-You can install the required database drivers with:
-
-```shell
-$ pip install databases[postgresql]
-$ pip install databases[mysql]
-$ pip install databases[sqlite]
-```
+Database drivers supported are:
 
-Default driver support is provided using one of [asyncpg][asyncpg], [aiomysql][aiomysql], or [aiosqlite][aiosqlite].
+* [asyncpg][asyncpg]
+* [aiopg][aiopg]
+* [aiomysql][aiomysql]
+* [asyncmy][asyncmy]
+* [aiosqlite][aiosqlite]
 
-You can also use other database drivers supported by `databases`:
+You can install the required database drivers with:
 
-```shel
-$ pip install databases[postgresql+aiopg]
-$ pip install databases[mysql+asyncmy]
+```shell
+$ pip install databases[asyncpg]
+$ pip install databases[aiopg]
+$ pip install databases[aiomysql]
+$ pip install databases[asyncmy]
+$ pip install databases[aiosqlite]
 ```
 
 Note that if you are using any synchronous SQLAlchemy functions such as `engine.create_all()` or [alembic][alembic] migrations then you still have to install a synchronous DB driver: [psycopg2][psycopg2] for PostgreSQL and [pymysql][pymysql] for MySQL.
@@ -56,7 +57,7 @@ For this example we'll create a very simple SQLite database to run some
 queries against.
 
 ```shell
-$ pip install databases[sqlite]
+$ pip install databases[aiosqlite]
 $ pip install ipython
 ```
 
@@ -68,7 +69,7 @@ expressions directly from the console.
 ```python
 # Create a database instance, and connect to it.
 from databases import Database
-database = Database('sqlite:///example.db')
+database = Database('sqlite+aiosqlite:///example.db')
 await database.connect()
 
 # Create a table.
@@ -103,8 +104,10 @@ for examples of how to start using databases together with SQLAlchemy core expre
 [psycopg2]: https://www.psycopg.org/
 [pymysql]: https://github.com/PyMySQL/PyMySQL
 [asyncpg]: https://github.com/MagicStack/asyncpg
+[aiopg]: https://github.com/aio-libs/aiopg
 [aiomysql]: https://github.com/aio-libs/aiomysql
-[aiosqlite]: https://github.com/jreese/aiosqlite
+[asyncmy]: https://github.com/long2ice/asyncmy
+[aiosqlite]: https://github.com/omnilib/aiosqlite
 
 [starlette]: https://github.com/encode/starlette
 [sanic]: https://github.com/huge-success/sanic

databases/backends/aiopg.py

@@ -14,7 +14,12 @@
 from sqlalchemy.sql.ddl import DDLElement
 
 from databases.core import DatabaseURL
-from databases.interfaces import ConnectionBackend, DatabaseBackend, TransactionBackend
+from databases.interfaces import (
+    ConnectionBackend,
+    DatabaseBackend,
+    Record,
+    TransactionBackend,
+)
 
 logger = logging.getLogger("databases")
 
@@ -112,7 +117,7 @@ async def release(self) -> None:
         await self._database._pool.release(self._connection)
         self._connection = None
 
-    async def fetch_all(self, query: ClauseElement) -> typing.List[typing.Sequence]:
+    async def fetch_all(self, query: ClauseElement) -> typing.List[Record]:
         assert self._connection is not None, "Connection is not acquired"
         query_str, args, context = self._compile(query)
         cursor = await self._connection.cursor()
@@ -133,7 +138,7 @@ async def fetch_all(self, query: ClauseElement) -> typing.List[typing.Sequence]:
         finally:
             cursor.close()
 
-    async def fetch_one(self, query: ClauseElement) -> typing.Optional[typing.Sequence]:
+    async def fetch_one(self, query: ClauseElement) -> typing.Optional[Record]:
         assert self._connection is not None, "Connection is not acquired"
         query_str, args, context = self._compile(query)
         cursor = await self._connection.cursor()

databases/backends/asyncmy.py

@@ -12,7 +12,12 @@
 from sqlalchemy.sql.ddl import DDLElement
 
 from databases.core import LOG_EXTRA, DatabaseURL
-from databases.interfaces import ConnectionBackend, DatabaseBackend, TransactionBackend
+from databases.interfaces import (
+    ConnectionBackend,
+    DatabaseBackend,
+    Record,
+    TransactionBackend,
+)
 
 logger = logging.getLogger("databases")
 
@@ -100,7 +105,7 @@ async def release(self) -> None:
         await self._database._pool.release(self._connection)
         self._connection = None
 
-    async def fetch_all(self, query: ClauseElement) -> typing.List[typing.Sequence]:
+    async def fetch_all(self, query: ClauseElement) -> typing.List[Record]:
         assert self._connection is not None, "Connection is not acquired"
         query_str, args, context = self._compile(query)
         async with self._connection.cursor() as cursor:
@@ -121,7 +126,7 @@ async def fetch_all(self, query: ClauseElement) -> typing.List[typing.Sequence]:
             finally:
                 await cursor.close()
 
-    async def fetch_one(self, query: ClauseElement) -> typing.Optional[typing.Sequence]:
+    async def fetch_one(self, query: ClauseElement) -> typing.Optional[Record]:
         assert self._connection is not None, "Connection is not acquired"
         query_str, args, context = self._compile(query)
         async with self._connection.cursor() as cursor:

databases/backends/mysql.py

@@ -12,7 +12,12 @@
 from sqlalchemy.sql.ddl import DDLElement
 
 from databases.core import LOG_EXTRA, DatabaseURL
-from databases.interfaces import ConnectionBackend, DatabaseBackend, TransactionBackend
+from databases.interfaces import (
+    ConnectionBackend,
+    DatabaseBackend,
+    Record,
+    TransactionBackend,
+)
 
 logger = logging.getLogger("databases")
 
@@ -100,7 +105,7 @@ async def release(self) -> None:
         await self._database._pool.release(self._connection)
         self._connection = None
 
-    async def fetch_all(self, query: ClauseElement) -> typing.List[typing.Sequence]:
+    async def fetch_all(self, query: ClauseElement) -> typing.List[Record]:
         assert self._connection is not None, "Connection is not acquired"
         query_str, args, context = self._compile(query)
         cursor = await self._connection.cursor()
@@ -121,7 +126,7 @@ async def fetch_all(self, query: ClauseElement) -> typing.List[typing.Sequence]:
         finally:
             await cursor.close()
 
-    async def fetch_one(self, query: ClauseElement) -> typing.Optional[typing.Sequence]:
+    async def fetch_one(self, query: ClauseElement) -> typing.Optional[Record]:
         assert self._connection is not None, "Connection is not acquired"
         query_str, args, context = self._compile(query)
         cursor = await self._connection.cursor()

databases/backends/postgres.py

@@ -11,7 +11,12 @@
 from sqlalchemy.types import TypeEngine
 
 from databases.core import LOG_EXTRA, DatabaseURL
-from databases.interfaces import ConnectionBackend, DatabaseBackend, TransactionBackend
+from databases.interfaces import (
+    ConnectionBackend,
+    DatabaseBackend,
+    Record as RecordInterface,
+    TransactionBackend,
+)
 
 logger = logging.getLogger("databases")
 
@@ -78,7 +83,7 @@ def connection(self) -> "PostgresConnection":
         return PostgresConnection(self, self._dialect)
 
 
-class Record(Sequence):
+class Record(RecordInterface):
     __slots__ = (
         "_row",
         "_result_columns",
@@ -105,7 +110,7 @@ def __init__(
         self._column_map, self._column_map_int, self._column_map_full = column_maps
 
     @property
-    def _mapping(self) -> asyncpg.Record:
+    def _mapping(self) -> typing.Mapping:
         return self._row
 
     def keys(self) -> typing.KeysView:
@@ -150,6 +155,9 @@ def __iter__(self) -> typing.Iterator:
     def __len__(self) -> int:
         return len(self._row)
 
+    def __getattr__(self, name: str) -> typing.Any:
+        return self._mapping.get(name)
+
 
 class PostgresConnection(ConnectionBackend):
     def __init__(self, database: PostgresBackend, dialect: Dialect):
@@ -168,15 +176,15 @@ async def release(self) -> None:
         self._connection = await self._database._pool.release(self._connection)
         self._connection = None
 
-    async def fetch_all(self, query: ClauseElement) -> typing.List[typing.Sequence]:
+    async def fetch_all(self, query: ClauseElement) -> typing.List[RecordInterface]:
         assert self._connection is not None, "Connection is not acquired"
         query_str, args, result_columns = self._compile(query)
         rows = await self._connection.fetch(query_str, *args)
         dialect = self._dialect
         column_maps = self._create_column_maps(result_columns)
         return [Record(row, result_columns, dialect, column_maps) for row in rows]
 
-    async def fetch_one(self, query: ClauseElement) -> typing.Optional[typing.Sequence]:
+    async def fetch_one(self, query: ClauseElement) -> typing.Optional[RecordInterface]:
         assert self._connection is not None, "Connection is not acquired"
         query_str, args, result_columns = self._compile(query)
         row = await self._connection.fetchrow(query_str, *args)

databases/backends/sqlite.py

@@ -11,7 +11,12 @@
 from sqlalchemy.sql.ddl import DDLElement
 
 from databases.core import LOG_EXTRA, DatabaseURL
-from databases.interfaces import ConnectionBackend, DatabaseBackend, TransactionBackend
+from databases.interfaces import (
+    ConnectionBackend,
+    DatabaseBackend,
+    Record,
+    TransactionBackend,
+)
 
 logger = logging.getLogger("databases")
 
@@ -86,7 +91,7 @@ async def release(self) -> None:
         await self._pool.release(self._connection)
         self._connection = None
 
-    async def fetch_all(self, query: ClauseElement) -> typing.List[typing.Sequence]:
+    async def fetch_all(self, query: ClauseElement) -> typing.List[Record]:
         assert self._connection is not None, "Connection is not acquired"
         query_str, args, context = self._compile(query)
 
@@ -104,7 +109,7 @@ async def fetch_all(self, query: ClauseElement) -> typing.List[typing.Sequence]:
                 for row in rows
             ]
 
-    async def fetch_one(self, query: ClauseElement) -> typing.Optional[typing.Sequence]:
+    async def fetch_one(self, query: ClauseElement) -> typing.Optional[Record]:
         assert self._connection is not None, "Connection is not acquired"
         query_str, args, context = self._compile(query)
 

databases/core.py

@@ -11,7 +11,12 @@
 from sqlalchemy.sql import ClauseElement
 
 from databases.importer import import_from_string
-from databases.interfaces import ConnectionBackend, DatabaseBackend, TransactionBackend
+from databases.interfaces import (
+    ConnectionBackend,
+    DatabaseBackend,
+    Record,
+    TransactionBackend,
+)
 
 if sys.version_info >= (3, 7):  # pragma: no cover
     import contextvars as contextvars
@@ -144,13 +149,13 @@ async def __aexit__(
 
     async def fetch_all(
         self, query: typing.Union[ClauseElement, str], values: dict = None
-    ) -> typing.List[typing.Sequence]:
+    ) -> typing.List[Record]:
         async with self.connection() as connection:
             return await connection.fetch_all(query, values)
 
     async def fetch_one(
         self, query: typing.Union[ClauseElement, str], values: dict = None
-    ) -> typing.Optional[typing.Sequence]:
+    ) -> typing.Optional[Record]:
         async with self.connection() as connection:
             return await connection.fetch_one(query, values)
 
@@ -265,14 +270,14 @@ async def __aexit__(
 
     async def fetch_all(
         self, query: typing.Union[ClauseElement, str], values: dict = None
-    ) -> typing.List[typing.Sequence]:
+    ) -> typing.List[Record]:
         built_query = self._build_query(query, values)
         async with self._query_lock:
             return await self._connection.fetch_all(built_query)
 
     async def fetch_one(
         self, query: typing.Union[ClauseElement, str], values: dict = None
-    ) -> typing.Optional[typing.Sequence]:
+    ) -> typing.Optional[Record]:
         built_query = self._build_query(query, values)
         async with self._query_lock:
             return await self._connection.fetch_one(built_query)

databases/interfaces.py

@@ -1,4 +1,5 @@
 import typing
+from collections.abc import Sequence
 
 from sqlalchemy.sql import ClauseElement
 
@@ -21,10 +22,10 @@ async def acquire(self) -> None:
     async def release(self) -> None:
         raise NotImplementedError()  # pragma: no cover
 
-    async def fetch_all(self, query: ClauseElement) -> typing.List[typing.Sequence]:
+    async def fetch_all(self, query: ClauseElement) -> typing.List["Record"]:
         raise NotImplementedError()  # pragma: no cover
 
-    async def fetch_one(self, query: ClauseElement) -> typing.Optional[typing.Sequence]:
+    async def fetch_one(self, query: ClauseElement) -> typing.Optional["Record"]:
         raise NotImplementedError()  # pragma: no cover
 
     async def fetch_val(
@@ -66,3 +67,9 @@ async def commit(self) -> None:
 
     async def rollback(self) -> None:
         raise NotImplementedError()  # pragma: no cover
+
+
+class Record(Sequence):
+    @property
+    def _mapping(self) -> typing.Mapping:
+        raise NotImplementedError()  # pragma: no cover

docs/connections_and_transactions.md

@@ -44,17 +44,17 @@ and for configuring the connection pool.
 
 ```python
 # Use an SSL connection.
-database = Database('postgresql://localhost/example?ssl=true')
+database = Database('postgresql+asyncpg://localhost/example?ssl=true')
 
 # Use a connection pool of between 5-20 connections.
-database = Database('mysql://localhost/example?min_size=5&max_size=20')
+database = Database('mysql+aiomysql://localhost/example?min_size=5&max_size=20')
 ```
 
 You can also use keyword arguments to pass in any connection options.
 Available keyword arguments may differ between database backends.
 
 ```python
-database = Database('postgresql://localhost/example', ssl=True, min_size=5, max_size=20)
+database = Database('postgresql+asyncpg://localhost/example', ssl=True, min_size=5, max_size=20)
 ```
 
 ## Transactions

docs/database_queries.md

@@ -34,7 +34,7 @@ You can now use any [SQLAlchemy core][sqlalchemy-core] queries ([official tutori
 ```python
 from databases import Database
 
-database = Database('postgresql://localhost/example')
+database = Database('postgresql+asyncpg://localhost/example')
 
 
 # Establish the connection pool
@@ -108,3 +108,20 @@ Note that query arguments should follow the `:query_arg` style.
 
 [sqlalchemy-core]: https://docs.sqlalchemy.org/en/latest/core/
 [sqlalchemy-core-tutorial]: https://docs.sqlalchemy.org/en/latest/core/tutorial.html
+
+## Query result
+
+To keep in line with [SQLAlchemy 1.4 changes][sqlalchemy-mapping-changes] 
+query result object no longer implements a mapping interface. 
+To access query result as a mapping you should use the `_mapping` property. 
+That way you can process both SQLAlchemy Rows and databases Records from raw queries 
+with the same function without any instance checks.
+
+```python
+query = "SELECT * FROM notes WHERE id = :id"
+result = await database.fetch_one(query=query, values={"id": 1})
+result.id  # access field via attribute
+result._mapping['id']  # access field via mapping
+```
+
+[sqlalchemy-mapping-changes]: https://docs.sqlalchemy.org/en/14/changelog/migration_14.html#rowproxy-is-no-longer-a-proxy-is-now-called-row-and-behaves-like-an-enhanced-named-tuple