Merge pull request #114 from encode/docs

Documentation

Author: tomchristie

README.md

@@ -18,10 +18,11 @@ It allows you to make queries using the powerful [SQLAlchemy Core][sqlalchemy-co
 expression language, and provides support for PostgreSQL, MySQL, and SQLite.
 
 Databases is suitable for integrating against any async Web framework, such as [Starlette][starlette],
-[Sanic][sanic], [Responder][responder], [Quart][quart], [aiohttp][aiohttp], [Tornado][tornado], [FastAPI][fastapi],
-or [Bocadillo][bocadillo].
+[Sanic][sanic], [Responder][responder], [Quart][quart], [aiohttp][aiohttp], [Tornado][tornado], [FastAPI][fastapi], or [Bocadillo][bocadillo].
 
-**Community**: https://discuss.encode.io/c/databases
+**Documentation**: [https://www.encode.io/databases/](https://www.encode.io/databases/)
+
+**Community**: [https://discuss.encode.io/c/databases](https://discuss.encode.io/c/databases)
 
 **Requirements**: Python 3.6+
 
@@ -43,278 +44,51 @@ $ pip install databases[sqlite]
 
 Driver support is providing using one of [asyncpg][asyncpg], [aiomysql][aiomysql], or [aiosqlite][aiosqlite].
 
-## Getting started
-
-**Note**: Use `ipython` to try these example from the console, since it supports `await`.
-
-Declare your tables using SQLAlchemy:
-
-```python
-import sqlalchemy
+---
 
+## Quickstart
 
-metadata = sqlalchemy.MetaData()
+For this example we'll create a very simple SQLite database to run some
+queries against.
 
-notes = sqlalchemy.Table(
-    "notes",
-    metadata,
-    sqlalchemy.Column("id", sqlalchemy.Integer, primary_key=True),
-    sqlalchemy.Column("text", sqlalchemy.String(length=100)),
-    sqlalchemy.Column("completed", sqlalchemy.Boolean),
-)
+```shell
+$ pip install databases[sqlite]
+$ pip install ipython
 ```
 
+We can now run a simple example from the console.
 
-You can use any of the sqlalchemy column types such as `sqlalchemy.JSON`, or
-custom column types.
-
-## Queries
-
-You can now use any [SQLAlchemy core][sqlalchemy-core] queries ([official tutorial][sqlalchemy-core-tutorial]).
+Note that we want to use `ipython` here, because it supports using `await`
+expressions directly from the console.
 
 ```python
+# Create a database instance, and connect to it.
 from databases import Database
-
-database = Database('postgresql://localhost/example')
-
-
-# Establish the connection pool
+database = Database('sqlite:///example.db')
 await database.connect()
 
-# Execute
-query = notes.insert()
-values = {"text": "example1", "completed": True}
-await database.execute(query=query, values=values)
+# Create a table.
+query = """CREATE TABLE HighScores (id INTEGER PRIMARY KEY, name VARCHAR(100), score INTEGER)"""
+await database.execute(query=query)
 
-# Execute many
-query = notes.insert()
+# Insert some data.
+query = "INSERT INTO HighScores(name, score) VALUES (:name, :score)"
 values = [
-    {"text": "example2", "completed": False},
-    {"text": "example3", "completed": True},
+    {"name": "Daisy", "score": 92},
+    {"name": "Neil", "score": 87},
+    {"name": "Carol", "score": 43},
 ]
 await database.execute_many(query=query, values=values)
 
-# Fetch multiple rows
-query = notes.select()
+# Run a database query.
+query = "SELECT * FROM HighScores"
 rows = await database.fetch_all(query=query)
-
-# Fetch single row
-query = notes.select()
-row = await database.fetch_one(query=query)
-
-# Fetch single value, defaults to `column=0`.
-query = notes.select()
-value = await database.fetch_val(query=query)
-
-# Fetch multiple rows without loading them all into memory at once
-query = notes.select()
-async for row in database.iterate(query=query):
-    ...
-
-# Close all connection in the connection pool
-await database.disconnect()
-```
-
-Connections are managed as task-local state, with driver implementations
-transparently using connection pooling behind the scenes.
-
-## Raw queries
-
-In addition to SQLAlchemy core queries, you can also perform raw SQL queries:
-
-```python
-# Execute
-query = "INSERT INTO notes(text, completed) VALUES (:text, :completed)"
-values = {"text": "example1", "completed": True}
-await database.execute(query=query, values=values)
-
-# Execute many
-query = "INSERT INTO notes(text, completed) VALUES (:text, :completed)"
-values = [
-    {"text": "example2", "completed": False},
-    {"text": "example3", "completed": True},
-]
-await database.execute_many(query=query, values=values)
-
-# Fetch multiple rows
-query = "SELECT * FROM notes WHERE completed = :completed"
-rows = await database.fetch_all(query=query, values={"completed": True})
-
-# Fetch single row
-query = "SELECT * FROM notes WHERE id = :id"
-result = await database.fetch_one(query=query, values={"id": 1})
-```
-
-Note that query arguments should follow the `:query_arg` style.
-
-## Transactions
-
-Transactions are managed by async context blocks:
-
-```python
-async with database.transaction():
-    ...
-```
-
-For a lower-level transaction API:
-
-```python
-transaction = await database.transaction()
-try:
-    ...
-except:
-    transaction.rollback()
-else:
-    transaction.commit()
-```
-
-You can also use `.transaction()` as a function decorator on any async function:
-
-```python
-@database.transaction()
-async def create_users(request):
-    ...
-```
-
-Transaction blocks are managed as task-local state. Nested transactions
-are fully supported, and are implemented using database savepoints.
-
-## Connecting and disconnecting
-
-You can control the database connect/disconnect, by using it as a async context manager.
-
-```python
-async with Database(DATABASE_URL) as database:
-    ...
-```
-
-Or by using explicit connection and disconnection:
-
-```python
-database = Database(DATABASE_URL)
-await database.connect()
-...
-await database.disconnect()
-```
-
-If you're integrating against a web framework, then you'll probably want
-to hook into framework startup or shutdown events. For example, with
-[Starlette][starlette] you would use the following:
-
-```python
-@app.on_event("startup")
-async def startup():
-    await database.connect()
-
-@app.on_event("shutdown")
-async def shutdown():
-    await database.disconnect()
-```
-
-## Connection options
-
-The PostgreSQL and MySQL backends provide a few connection options for SSL
-and for configuring the connection pool.
-
-```python
-# Use an SSL connection.
-database = Database('postgresql://localhost/example?ssl=true')
-
-# Use a connection pool of between 5-20 connections.
-database = Database('mysql://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)
-```
-
-## Test isolation
-
-For strict test isolation you will always want to rollback the test database
-to a clean state between each test case:
-
-```python
-database = Database(DATABASE_URL, force_rollback=True)
-```
-
-This will ensure that all database connections are run within a transaction
-that rollbacks once the database is disconnected.
-
-If you're integrating against a web framework you'll typically want to
-use something like the following pattern:
-
-```python
-if TESTING:
-    database = Database(TEST_DATABASE_URL, force_rollback=True)
-else:
-    database = Database(DATABASE_URL)
-```
-
-This will give you test cases that run against a different database to
-the development database, with strict test isolation so long as you make sure
-to connect and disconnect to the database between test cases.
-
-For a lower level API you can explicitly create force-rollback transactions:
-
-```python
-async with database.transaction(force_rollback=True):
-    ...
-```
-
-## Migrations
-
-Because `databases` uses SQLAlchemy core, you can integrate with [Alembic][alembic]
-for database migration support.
-
-```shell
-$ pip install alembic
-$ alembic init migrations
-```
-
-You'll want to set things up so that Alembic references the configured
-`DATABASE_URL`, and uses your table metadata.
-
-In `alembic.ini` remove the following line:
-
-```shell
-sqlalchemy.url = driver://user:pass@localhost/dbname
+print('High Scores:', rows)
 ```
 
-In `migrations/env.py`, you need to set the ``'sqlalchemy.url'`` configuration key,
-and the `target_metadata` variable. You'll want something like this:
-
-```python
-# The Alembic Config object.
-config = context.config
-
-# Configure Alembic to use our DATABASE_URL and our table definitions.
-# These are just examples - the exact setup will depend on whatever
-# framework you're integrating against.
-from myapp.settings import DATABASE_URL
-from myapp.tables import metadata
-
-config.set_main_option('sqlalchemy.url', str(DATABASE_URL))
-target_metadata = metadata
-
-...
-```
-
-Note that migrations will use a standard synchronous database driver,
-rather than using the async drivers that `databases` provides support for.
-
-This will also be the case if you're using SQLAlchemy's standard tooling, such
-as using `metadata.create_all(engine)` to setup the database tables.
-
-**Note for MySQL**:
-
-For MySQL you'll probably need to explicitly specify the `pymysql` dialect when
-using Alembic since the default MySQL dialect does not support Python 3.
+Check out the documentation on [making database queries](database_queries.md)
+for examples of how to start using databases together with SQLAlchemy core expressions.
 
-If you're using the `databases.DatabaseURL` datatype, you can obtain this using
-`DATABASE_URL.replace(dialect="pymysql")`
 
 <p align="center">&mdash; ⭐️ &mdash;</p>
 <p align="center"><i>Databases is <a href="https://github.com/encode/databases/blob/master/LICENSE.md">BSD licensed</a> code. Designed & built in Brighton, England.</i></p>