1280 UUID 3.14 only (#1364)

* initial prototype

* fix docstring

* fix test

* simplify backport

* add basic test

* don't run test for cockroachdb

* add `UUID7` to api reference

* load script for older versions of Postgres / CockroachDB

* add tutorial

* Update uuid_v7_support.rst

* add polyfills

* try fixing cockroachdb test

* disable uuid7 for cockroachdb for now

* update docs

* just support python 3.14

* tweaks

* fix linter error

* add docstring

* update `python_version_gte`

* Update test_uuid.py

* make defaults None so it is possible to use on cockroach and sqlite - just with nullable columns

* mention extension for older pg versions

* Update index.rst

* fix `python_version_gte`

Author: dantownsend

docs/src/piccolo/api_reference/index.rst

@@ -111,42 +111,31 @@ UUID
 ~~~~
 
 .. autoclass:: UUID4
-    :members:
+
+.. autoclass:: UUID7
 
 
-TimestampCustom
-~~~~~~~~~~~~~~~
+Timestamp
+~~~~~~~~~
 
 .. autoclass:: TimestampCustom
     :members:
 
-TimestampOffset
-~~~~~~~~~~~~~~~
-
 .. autoclass:: TimestampOffset
     :members:
 
-TimestampNow
-~~~~~~~~~~~~
-
 .. autoclass:: TimestampNow
     :members:
 
-TimestamptzCustom
-~~~~~~~~~~~~~~~~~
+Timestamptz
+~~~~~~~~~~~
 
 .. autoclass:: TimestamptzCustom
     :members:
 
-TimestamptzOffset
-~~~~~~~~~~~~~~~~~
-
 .. autoclass:: TimestamptzOffset
     :members:
 
-TimestamptzNow
-~~~~~~~~~~~~~~
-
 .. autoclass:: TimestamptzNow
     :members:
 

docs/src/piccolo/contributing/index.rst

@@ -22,8 +22,8 @@ Make sure the test database exists:
 .. code-block:: console
 
     cockroach sql --insecure
-    >>> create database piccolo
-    >>> use piccolo
+    >>> create database piccolo;
+    >>> use piccolo;
 
 -------------------------------------------------------------------------------
 

piccolo/columns/defaults/uuid.py

@@ -3,6 +3,8 @@
 from enum import Enum
 from typing import Union
 
+from piccolo.utils.uuid import uuid7
+
 from .base import Default
 
 
@@ -17,6 +19,18 @@ class UUID4(Default):
 
     @property
     def postgres(self):
+        """
+        Historically we had to use `uuid_generate_v4()` from the `uuid-ossp`
+        extension.
+
+        Since Postgres 13 there is a built-in `gen_random_uuid` function which
+        generates UUID v4 values.
+
+        In Postgres 18, `uuidv4` was added, which is the same as
+        `gen_random_uuid`, but more precisely named. We will move to this at
+        some point in the future.
+
+        """
         return "gen_random_uuid()"
 
     @property
@@ -25,13 +39,55 @@ def cockroach(self):
 
     @property
     def sqlite(self):
-        return "''"
+        return None
 
     def python(self):
         return uuid.uuid4()
 
 
-UUIDArg = Union[UUID4, uuid.UUID, str, Enum, None, Callable[[], uuid.UUID]]
+class UUID7(Default):
+    """
+    This makes the default value for a
+    :class:`UUID <piccolo.columns.column_types.UUID>` column a randomly
+    generated UUID v7 value. Postgres >= 18 and Python >= 3.14 only. UUID7 can
+    be more efficiently indexed than UUID, and inserts can be faster.
+
+    For this to work in older versions of Postgres, register an extension such
+    as `pg_uuidv7 <https://github.com/fboulnois/pg_uuidv7>`_.
+
+    """  # noqa: E501
+
+    @property
+    def postgres(self):
+        """
+        Supported in Postgres 18 and above.
+        """
+        return "uuidv7()"
+
+    @property
+    def cockroach(self):
+        """
+        CockroachDB doesn't currently have a uuidv7 function.
+        """
+        return None
+
+    @property
+    def sqlite(self):
+        return None
+
+    def python(self):
+        return uuid7()
+
+
+UUIDArg = Union[
+    UUID4,
+    UUID7,
+    uuid.UUID,
+    str,
+    Enum,
+    None,
+    Callable[[], uuid.UUID],
+]
 
 
-__all__ = ["UUIDArg", "UUID4"]
+__all__ = ["UUIDArg", "UUID4", "UUID7"]

piccolo/utils/uuid.py

@@ -0,0 +1,4 @@
+def uuid7():
+    from uuid import uuid7 as _uuid7
+
+    return _uuid7()

tests/base.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import decimal
 import sys
 from typing import Optional
 from unittest import TestCase
@@ -28,6 +29,17 @@ def engine_version_lt(version: float) -> bool:
     return ENGINE is not None and run_sync(ENGINE.get_version()) < version
 
 
+def engine_version_gte(version: float) -> bool:
+    return ENGINE is not None and run_sync(ENGINE.get_version()) > version
+
+
+def python_version_gte(version: decimal.Decimal) -> bool:
+    return (
+        decimal.Decimal(f"{sys.version_info.major}.{sys.version_info.minor}")
+        >= version
+    )
+
+
 def is_running_postgres() -> bool:
     return type(ENGINE) is PostgresEngine
 

tests/columns/test_uuid.py

@@ -1,19 +1,50 @@
+import decimal
 import uuid
 
+import pytest
+
 from piccolo.columns.column_types import UUID
+from piccolo.columns.defaults.uuid import UUID7
 from piccolo.table import Table
-from piccolo.testing.test_case import TableTest
+from piccolo.testing.test_case import AsyncTableTest
+from tests.base import (
+    engine_version_gte,
+    is_running_postgres,
+    python_version_gte,
+)
 
 
-class MyTable(Table):
+class UUIDTable(Table):
     uuid = UUID()
 
 
-class TestUUID(TableTest):
-    tables = [MyTable]
+class TestUUID(AsyncTableTest):
+    tables = [UUIDTable]
 
-    def test_return_type(self):
-        row = MyTable()
-        row.save().run_sync()
+    async def test_return_type(self):
+        row = UUIDTable()
+        await row.save()
 
         self.assertIsInstance(row.uuid, uuid.UUID)
+
+
+class UUID7Table(Table):
+    uuid_7 = UUID(default=UUID7())
+
+
+@pytest.mark.skipif(
+    not (
+        python_version_gte(decimal.Decimal("3.14"))
+        and is_running_postgres()
+        and engine_version_gte(18)
+    ),
+    reason="Only Python >= 3.14 and Postgres >= 18 are supported.",
+)
+class TestUUID7(AsyncTableTest):
+    tables = [UUID7Table]
+
+    async def test_return_type(self):
+        row = UUID7Table()
+        await row.save()
+
+        self.assertIsInstance(row.uuid_7, uuid.UUID)