Added documentation.

docs/src/piccolo/contributing/index.rst

@@ -20,6 +20,7 @@ Get the tests running
 * Setup Postgres, and make sure a database called ``piccolo`` exists (see ``tests/postgres_conf.py``).
 * Run the automated code linting/formatting tools: ``./scripts/lint.sh``
 * Run the test suite with Postgres: ``./scripts/test-postgres.sh``
+* Run the test suite with Cockroach: ``./scripts/test-cockroach.sh``
 * Run the test suite with Sqlite: ``./scripts/test-sqlite.sh``
 
 -------------------------------------------------------------------------------

docs/src/piccolo/engines/cockroach_engine.rst

@@ -0,0 +1,87 @@
+CockroachEngine
+==============
+
+Configuration
+-------------
+
+.. code-block:: python
+
+    # piccolo_conf.py
+    from piccolo.engine.cockroach import CockroachEngine
+
+
+    DB = CockroachEngine(config={
+        'host': 'localhost',
+        'database': 'piccolo',
+        'user': 'root',
+        'password': '',
+        'port': '26257',
+    })
+
+config
+~~~~~~
+
+The config dictionary is passed directly to the underlying database adapter,
+asyncpg. See the `asyncpg docs <https://magicstack.github.io/asyncpg/current/api/index.html#connection>`_
+to learn more.
+
+-------------------------------------------------------------------------------
+
+Connection pool
+---------------
+
+To use a connection pool, you need to first initialise it. The best place to do
+this is in the startup event handler of whichever web framework you are using.
+
+Here's an example using Starlette. Notice that we also close the connection
+pool in the shutdown event handler.
+
+.. code-block:: python
+
+    from piccolo.engine import engine_finder
+    from starlette.applications import Starlette
+
+
+    app = Starlette()
+
+
+    @app.on_event('startup')
+    async def open_database_connection_pool():
+        engine = engine_finder()
+        await engine.start_connection_pool()
+
+
+    @app.on_event('shutdown')
+    async def close_database_connection_pool():
+        engine = engine_finder()
+        await engine.close_connection_pool()
+
+.. hint:: Using a connection pool helps with performance, since connections
+    are reused instead of being created for each query.
+
+Once a connection pool has been started, the engine will use it for making
+queries.
+
+.. hint:: If you're running several instances of an app on the same server,
+    you may prefer an external connection pooler - like pgbouncer.
+
+Configuration
+~~~~~~~~~~~~~
+
+The connection pool uses the same configuration as your engine. You can also
+pass in additional parameters, which are passed to the underlying database
+adapter. Here's an example:
+
+.. code-block:: python
+
+    # To increase the number of connections available:
+    await engine.start_connection_pool(max_size=20)
+
+-------------------------------------------------------------------------------
+
+Source
+------
+
+.. currentmodule:: piccolo.engine.cockroach
+
+.. autoclass:: CockroachEngine

docs/src/piccolo/engines/index.rst

@@ -126,3 +126,4 @@ Engine types
 
     ./sqlite_engine
     ./postgres_engine
+    ./cockroach_engine

docs/src/piccolo/features/supported_databases.rst

@@ -8,6 +8,12 @@ will be using in production.
 
 -------------------------------------------------------------------------------
 
+Cockroach DB
+--------
+Cockroach support is in experimental beta.
+
+-------------------------------------------------------------------------------
+
 SQLite
 ------
 SQLite support is not as complete as Postgres, but it is available - mostly

docs/src/piccolo/getting_started/database_support.rst

@@ -6,6 +6,8 @@ Database Support
 `Postgres <https://www.postgresql.org/>`_ is the primary database which Piccolo
 was designed for.
 
+`CockroachDB <https://www.cockroachlabs.com/>`_ is in experimental beta.
+
 Limited `SQLite <https://www.sqlite.org/index.html>`_ support is available,
 mostly to enable tooling like the :ref:`playground <Playground>`. Postgres is the only database we
 recommend for use in production with Piccolo.

docs/src/piccolo/getting_started/index.rst

@@ -10,6 +10,7 @@ Getting Started
     ./installing_piccolo
     ./playground
     ./setup_postgres
+    ./setup_cockroach
     ./setup_sqlite
     ./example_schema
     ./sync_and_async

docs/src/piccolo/getting_started/installing_piccolo.rst

@@ -23,7 +23,7 @@ Now install Piccolo, ideally inside a `virtualenv <https://docs.python-guide.org
     # The important bit:
     pip install piccolo
 
-    # Install Piccolo with PostgreSQL driver:
+    # Install Piccolo with PostgreSQL or CockroachDB driver:
     pip install 'piccolo[postgres]'
 
     # Install Piccolo with SQLite driver:

docs/src/piccolo/getting_started/setup_cockroach.rst

@@ -0,0 +1,42 @@
+.. _setting_up_cockroach:
+
+##############
+Setup Cockroach
+##############
+
+Installation
+************
+
+Follow the  `instructions for your OS <https://www.cockroachlabs.com/docs/stable/install-cockroachdb.html>`_.
+
+-------------------------------------------------------------------------------
+
+Creating a database
+*******************
+
+cockroach sql
+-------------
+
+CockroachDB comes with its own management tooling.
+
+.. code-block:: bash
+
+    cd ~/wherever/you/installed/cockroachdb
+    cockroach sql --insecure
+
+Enter the following:
+
+.. code-block:: bash
+
+    create database piccolo;
+    use piccolo;
+
+Management GUI
+--------------
+
+CockroachDB comes with its own web-based management GUI available on localhost: http://127.0.0.1:8080/
+
+Beekeeper Studio
+----------------
+
+If you prefer a GUI, Beekeeper Studio is recommended and has an  `installer available <https://www.beekeeperstudio.io/>`_.