diff --git a/docs/src/piccolo/contributing/index.rst b/docs/src/piccolo/contributing/index.rst index 7c7f0af28..553895756 100644 --- a/docs/src/piccolo/contributing/index.rst +++ b/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`` ------------------------------------------------------------------------------- diff --git a/docs/src/piccolo/engines/cockroach_engine.rst b/docs/src/piccolo/engines/cockroach_engine.rst new file mode 100644 index 000000000..b6f5cd20f --- /dev/null +++ b/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 `_ +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 diff --git a/docs/src/piccolo/engines/index.rst b/docs/src/piccolo/engines/index.rst index c39777da7..fad00546c 100644 --- a/docs/src/piccolo/engines/index.rst +++ b/docs/src/piccolo/engines/index.rst @@ -126,3 +126,4 @@ Engine types ./sqlite_engine ./postgres_engine + ./cockroach_engine diff --git a/docs/src/piccolo/features/supported_databases.rst b/docs/src/piccolo/features/supported_databases.rst index 2b2ef74a4..a29868535 100644 --- a/docs/src/piccolo/features/supported_databases.rst +++ b/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 diff --git a/docs/src/piccolo/getting_started/database_support.rst b/docs/src/piccolo/getting_started/database_support.rst index 0ce384ce0..3dc192888 100644 --- a/docs/src/piccolo/getting_started/database_support.rst +++ b/docs/src/piccolo/getting_started/database_support.rst @@ -6,6 +6,8 @@ Database Support `Postgres `_ is the primary database which Piccolo was designed for. +`CockroachDB `_ is in experimental beta. + Limited `SQLite `_ support is available, mostly to enable tooling like the :ref:`playground `. Postgres is the only database we recommend for use in production with Piccolo. diff --git a/docs/src/piccolo/getting_started/index.rst b/docs/src/piccolo/getting_started/index.rst index e31ce6619..373cad786 100644 --- a/docs/src/piccolo/getting_started/index.rst +++ b/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 diff --git a/docs/src/piccolo/getting_started/installing_piccolo.rst b/docs/src/piccolo/getting_started/installing_piccolo.rst index cdc695771..ce60967c2 100644 --- a/docs/src/piccolo/getting_started/installing_piccolo.rst +++ b/docs/src/piccolo/getting_started/installing_piccolo.rst @@ -23,7 +23,7 @@ Now install Piccolo, ideally inside a `virtualenv `_. + +------------------------------------------------------------------------------- + +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 `_.