Merge branch 'piccolo-orm:master' into composite_index

Author: sinisaos

docs/src/piccolo/api_reference/index.rst

@@ -106,6 +106,13 @@ Date
 .. autoclass:: DateOffset
     :members:
 
+
+UUID
+~~~~
+
+.. autoclass:: UUID4
+    :members:
+
 -------------------------------------------------------------------------------
 
 Testing

docs/src/piccolo/engines/cockroach_engine.rst

@@ -27,55 +27,10 @@ to learn more.
 
 -------------------------------------------------------------------------------
 
-Connection pool
+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)
+See :ref:`ConnectionPool`.
 
 -------------------------------------------------------------------------------
 

docs/src/piccolo/engines/connection_pool.rst

@@ -0,0 +1,80 @@
+.. _ConnectionPool:
+
+Connection Pool
+===============
+
+.. hint:: Connection pools can be used with Postgres and CockroachDB.
+
+Setup
+~~~~~
+
+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.
+We also want to close the connection pool in the shutdown event handler.
+
+The recommended way for Starlette and FastAPI apps is to use the ``lifespan``
+parameter:
+
+.. code-block:: python
+
+    from contextlib import asynccontextmanager
+    from piccolo.engine import engine_finder
+    from starlette.applications import Starlette
+
+
+    @asynccontextmanager
+    async def lifespan(app: Starlette):
+        engine = engine_finder()
+        assert engine
+        await engine.start_connection_pool()
+        yield
+        await engine.close_connection_pool()
+
+
+    app = Starlette(lifespan=lifespan)
+
+In older versions of Starlette and FastAPI, you may need event handlers
+instead:
+
+.. 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)

docs/src/piccolo/engines/index.rst

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

docs/src/piccolo/engines/postgres_engine.rst

@@ -26,55 +26,10 @@ to learn more.
 
 -------------------------------------------------------------------------------
 
-Connection pool
+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)
+See :ref:`ConnectionPool`.
 
 -------------------------------------------------------------------------------
 

piccolo/columns/defaults/uuid.py

@@ -7,6 +7,14 @@
 
 
 class UUID4(Default):
+    """
+    This makes the default value for a
+    :class:`UUID <piccolo.columns.column_types.UUID>` column a randomly
+    generated UUID v4 value. The advantage over using :func:`uuid.uuid4` from
+    the standard library, is the default is set on the column definition in the
+    database too.
+    """
+
     @property
     def postgres(self):
         return "uuid_generate_v4()"

piccolo/columns/m2m.py

@@ -311,11 +311,8 @@ async def run(self):
         transaction, or wrapped in a new transaction.
         """
         engine = self.rows[0]._meta.db
-        if engine.transaction_exists():
-            await self._run()
-        else:
-            async with engine.transaction():
-                await self._run()
+        async with engine.transaction():
+            return await self._run()
 
     def run_sync(self):
         return run_sync(self.run())