piccolo 1.27.1__py3-none-any.whl → 1.29.0__py3-none-any.whl

piccolo/columns/column_types.py

@@ -29,11 +29,21 @@ from __future__ import annotations
 import copy
 import decimal
 import inspect
-import typing as t
 import uuid
+from collections.abc import Callable
 from dataclasses import dataclass
 from datetime import date, datetime, time, timedelta
 from enum import Enum
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    Literal,
+    Optional,
+    Union,
+    cast,
+    overload,
+)
 
 from typing_extensions import Unpack
 
@@ -71,8 +81,9 @@ from piccolo.querystring import QueryString
 from piccolo.utils.encoding import dump_json
 from piccolo.utils.warnings import colored_warning
 
-if t.TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:  # pragma: no cover
     from piccolo.columns.base import ColumnMeta
+    from piccolo.query.functions.array import ArrayItemType, ArrayType
     from piccolo.query.operators.json import (
         GetChildElement,
         GetElementFromPath,
@@ -94,7 +105,7 @@ class ConcatDelegate:
     def get_querystring(
         self,
         column: Column,
-        value: t.Union[str, Column, QueryString],
+        value: Union[str, Column, QueryString],
         reverse: bool = False,
     ) -> QueryString:
         """
@@ -137,8 +148,8 @@ class MathDelegate:
     def get_querystring(
         self,
         column_name: str,
-        operator: t.Literal["+", "-", "/", "*"],
-        value: t.Union[int, float, Integer],
+        operator: Literal["+", "-", "/", "*"],
+        value: Union[int, float, Integer],
         reverse: bool = False,
     ) -> QueryString:
         if isinstance(value, Integer):
@@ -147,8 +158,8 @@ class MathDelegate:
                 raise ValueError(
                     "Adding values across joins isn't currently supported."
                 )
-            column_name = column._meta.db_column_name
-            return QueryString(f"{column_name} {operator} {column_name}")
+            other_column_name = value._meta.db_column_name
+            return QueryString(f"{column_name} {operator} {other_column_name}")
         elif isinstance(value, (int, float)):
             if reverse:
                 return QueryString(f"{{}} {operator} {column_name}", value)
@@ -184,7 +195,7 @@ class TimedeltaDelegate:
 
     # Maps the attribute name in Python's timedelta to what it's called in
     # Postgres.
-    postgres_attr_map: t.Dict[str, str] = {
+    postgres_attr_map: dict[str, str] = {
         "days": "DAYS",
         "seconds": "SECONDS",
         "microseconds": "MICROSECONDS",
@@ -233,7 +244,7 @@ class TimedeltaDelegate:
     def get_querystring(
         self,
         column: Column,
-        operator: t.Literal["+", "-"],
+        operator: Literal["+", "-"],
         value: timedelta,
         engine_type: str,
     ) -> QueryString:
@@ -318,8 +329,8 @@ class Varchar(Column):
 
     def __init__(
         self,
-        length: t.Optional[int] = 255,
-        default: t.Union[str, Enum, t.Callable[[], str], None] = "",
+        length: Optional[int] = 255,
+        default: Union[str, Enum, Callable[[], str], None] = "",
         **kwargs: Unpack[ColumnKwargs],
     ) -> None:
         self._validate_default(default, (str, None))
@@ -335,13 +346,13 @@ class Varchar(Column):
     ###########################################################################
     # For update queries
 
-    def __add__(self, value: t.Union[str, Varchar, Text]) -> QueryString:
+    def __add__(self, value: Union[str, Varchar, Text]) -> QueryString:
         return self.concat_delegate.get_querystring(
             column=self,
             value=value,
         )
 
-    def __radd__(self, value: t.Union[str, Varchar, Text]) -> QueryString:
+    def __radd__(self, value: Union[str, Varchar, Text]) -> QueryString:
         return self.concat_delegate.get_querystring(
             column=self,
             value=value,
@@ -351,16 +362,16 @@ class Varchar(Column):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> str: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Varchar: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[str, None]):
+    def __set__(self, obj, value: Union[str, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -388,16 +399,16 @@ class Secret(Varchar):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> str: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Secret: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[str, None]):
+    def __set__(self, obj, value: Union[str, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -427,7 +438,7 @@ class Text(Column):
 
     def __init__(
         self,
-        default: t.Union[str, Enum, None, t.Callable[[], str]] = "",
+        default: Union[str, Enum, None, Callable[[], str]] = "",
         **kwargs: Unpack[ColumnKwargs],
     ) -> None:
         self._validate_default(default, (str, None))
@@ -437,13 +448,13 @@ class Text(Column):
     ###########################################################################
     # For update queries
 
-    def __add__(self, value: t.Union[str, Varchar, Text]) -> QueryString:
+    def __add__(self, value: Union[str, Varchar, Text]) -> QueryString:
         return self.concat_delegate.get_querystring(
             column=self,
             value=value,
         )
 
-    def __radd__(self, value: t.Union[str, Varchar, Text]) -> QueryString:
+    def __radd__(self, value: Union[str, Varchar, Text]) -> QueryString:
         return self.concat_delegate.get_querystring(
             column=self,
             value=value,
@@ -453,16 +464,16 @@ class Text(Column):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> str: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Text: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[str, None]):
+    def __set__(self, obj, value: Union[str, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -519,16 +530,16 @@ class UUID(Column):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> uuid.UUID: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> UUID: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[uuid.UUID, None]):
+    def __set__(self, obj, value: Union[uuid.UUID, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -556,7 +567,7 @@ class Integer(Column):
 
     def __init__(
         self,
-        default: t.Union[int, Enum, t.Callable[[], int], None] = 0,
+        default: Union[int, Enum, Callable[[], int], None] = 0,
         **kwargs: Unpack[ColumnKwargs],
     ) -> None:
         self._validate_default(default, (int, None))
@@ -566,12 +577,12 @@ class Integer(Column):
     ###########################################################################
     # For update queries
 
-    def __add__(self, value: t.Union[int, float, Integer]) -> QueryString:
+    def __add__(self, value: Union[int, float, Integer]) -> QueryString:
         return self.math_delegate.get_querystring(
             column_name=self._meta.db_column_name, operator="+", value=value
         )
 
-    def __radd__(self, value: t.Union[int, float, Integer]) -> QueryString:
+    def __radd__(self, value: Union[int, float, Integer]) -> QueryString:
         return self.math_delegate.get_querystring(
             column_name=self._meta.db_column_name,
             operator="+",
@@ -579,12 +590,12 @@ class Integer(Column):
             reverse=True,
         )
 
-    def __sub__(self, value: t.Union[int, float, Integer]) -> QueryString:
+    def __sub__(self, value: Union[int, float, Integer]) -> QueryString:
         return self.math_delegate.get_querystring(
             column_name=self._meta.db_column_name, operator="-", value=value
         )
 
-    def __rsub__(self, value: t.Union[int, float, Integer]) -> QueryString:
+    def __rsub__(self, value: Union[int, float, Integer]) -> QueryString:
         return self.math_delegate.get_querystring(
             column_name=self._meta.db_column_name,
             operator="-",
@@ -592,12 +603,12 @@ class Integer(Column):
             reverse=True,
         )
 
-    def __mul__(self, value: t.Union[int, float, Integer]) -> QueryString:
+    def __mul__(self, value: Union[int, float, Integer]) -> QueryString:
         return self.math_delegate.get_querystring(
             column_name=self._meta.db_column_name, operator="*", value=value
         )
 
-    def __rmul__(self, value: t.Union[int, float, Integer]) -> QueryString:
+    def __rmul__(self, value: Union[int, float, Integer]) -> QueryString:
         return self.math_delegate.get_querystring(
             column_name=self._meta.db_column_name,
             operator="*",
@@ -605,12 +616,12 @@ class Integer(Column):
             reverse=True,
         )
 
-    def __truediv__(self, value: t.Union[int, float, Integer]) -> QueryString:
+    def __truediv__(self, value: Union[int, float, Integer]) -> QueryString:
         return self.math_delegate.get_querystring(
             column_name=self._meta.db_column_name, operator="/", value=value
         )
 
-    def __rtruediv__(self, value: t.Union[int, float, Integer]) -> QueryString:
+    def __rtruediv__(self, value: Union[int, float, Integer]) -> QueryString:
         return self.math_delegate.get_querystring(
             column_name=self._meta.db_column_name,
             operator="/",
@@ -618,14 +629,12 @@ class Integer(Column):
             reverse=True,
         )
 
-    def __floordiv__(self, value: t.Union[int, float, Integer]) -> QueryString:
+    def __floordiv__(self, value: Union[int, float, Integer]) -> QueryString:
         return self.math_delegate.get_querystring(
             column_name=self._meta.db_column_name, operator="/", value=value
         )
 
-    def __rfloordiv__(
-        self, value: t.Union[int, float, Integer]
-    ) -> QueryString:
+    def __rfloordiv__(self, value: Union[int, float, Integer]) -> QueryString:
         return self.math_delegate.get_querystring(
             column_name=self._meta.db_column_name,
             operator="/",
@@ -636,16 +645,16 @@ class Integer(Column):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> int: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Integer: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[int, None]):
+    def __set__(self, obj, value: Union[int, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -692,16 +701,16 @@ class BigInt(Integer):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> int: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> BigInt: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[int, None]):
+    def __set__(self, obj, value: Union[int, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -740,16 +749,16 @@ class SmallInt(Integer):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> int: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> SmallInt: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[int, None]):
+    def __set__(self, obj, value: Union[int, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -790,16 +799,16 @@ class Serial(Column):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> int: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Serial: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[int, None]):
+    def __set__(self, obj, value: Union[int, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -822,16 +831,16 @@ class BigSerial(Serial):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> int: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> BigSerial: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[int, None]):
+    def __set__(self, obj, value: Union[int, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -858,16 +867,16 @@ class PrimaryKey(Serial):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> int: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> PrimaryKey: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[int, None]):
+    def __set__(self, obj, value: Union[int, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -947,16 +956,16 @@ class Timestamp(Column):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> datetime: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Timestamp: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[datetime, None]):
+    def __set__(self, obj, value: Union[datetime, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -1043,16 +1052,16 @@ class Timestamptz(Column):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> datetime: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Timestamptz: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[datetime, None]):
+    def __set__(self, obj, value: Union[datetime, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -1124,16 +1133,16 @@ class Date(Column):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> date: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Date: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[date, None]):
+    def __set__(self, obj, value: Union[date, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -1202,16 +1211,16 @@ class Time(Column):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> time: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Time: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[time, None]):
+    def __set__(self, obj, value: Union[time, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -1292,16 +1301,16 @@ class Interval(Column):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> timedelta: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Interval: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[timedelta, None]):
+    def __set__(self, obj, value: Union[timedelta, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -1333,7 +1342,7 @@ class Boolean(Column):
 
     def __init__(
         self,
-        default: t.Union[bool, Enum, t.Callable[[], bool], None] = False,
+        default: Union[bool, Enum, Callable[[], bool], None] = False,
         **kwargs: Unpack[ColumnKwargs],
     ) -> None:
         self._validate_default(default, (bool, None))
@@ -1383,16 +1392,16 @@ class Boolean(Column):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> bool: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Boolean: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[bool, None]):
+    def __set__(self, obj, value: Union[bool, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -1443,14 +1452,14 @@ class Numeric(Column):
             return "NUMERIC"
 
     @property
-    def precision(self) -> t.Optional[int]:
+    def precision(self) -> Optional[int]:
         """
         The total number of digits allowed.
         """
         return self.digits[0] if self.digits is not None else None
 
     @property
-    def scale(self) -> t.Optional[int]:
+    def scale(self) -> Optional[int]:
         """
         The number of digits after the decimal point.
         """
@@ -1458,9 +1467,9 @@ class Numeric(Column):
 
     def __init__(
         self,
-        digits: t.Optional[t.Tuple[int, int]] = None,
-        default: t.Union[
-            decimal.Decimal, Enum, t.Callable[[], decimal.Decimal], None
+        digits: Optional[tuple[int, int]] = None,
+        default: Union[
+            decimal.Decimal, Enum, Callable[[], decimal.Decimal], None
         ] = decimal.Decimal(0.0),
         **kwargs: Unpack[ColumnKwargs],
     ) -> None:
@@ -1483,16 +1492,16 @@ class Numeric(Column):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> decimal.Decimal: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Numeric: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[decimal.Decimal, None]):
+    def __set__(self, obj, value: Union[decimal.Decimal, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -1504,16 +1513,16 @@ class Decimal(Numeric):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> decimal.Decimal: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Decimal: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[decimal.Decimal, None]):
+    def __set__(self, obj, value: Union[decimal.Decimal, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -1542,9 +1551,13 @@ class Real(Column):
 
     def __init__(
         self,
-        default: t.Union[float, Enum, t.Callable[[], float], None] = 0.0,
+        default: Union[float, Enum, Callable[[], float], None] = 0.0,
         **kwargs: Unpack[ColumnKwargs],
     ) -> None:
+        if isinstance(default, int):
+            # For example, allow `0` as a valid default.
+            default = float(default)
+
         self._validate_default(default, (float, None))
         self.default = default
         super().__init__(default=default, **kwargs)
@@ -1552,16 +1565,16 @@ class Real(Column):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> float: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Real: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[float, None]):
+    def __set__(self, obj, value: Union[float, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -1573,16 +1586,16 @@ class Float(Real):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> float: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Float: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[float, None]):
+    def __set__(self, obj, value: Union[float, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -1598,16 +1611,16 @@ class DoublePrecision(Real):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> float: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> DoublePrecision: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[float, None]):
+    def __set__(self, obj, value: Union[float, None]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -1619,7 +1632,7 @@ class ForeignKeySetupResponse:
     is_lazy: bool
 
 
-class ForeignKey(Column, t.Generic[ReferencedTable]):
+class ForeignKey(Column, Generic[ReferencedTable]):
     """
     Used to reference another table. Uses the same type as the primary key
     column on the table it references.
@@ -1832,50 +1845,50 @@ class ForeignKey(Column, t.Generic[ReferencedTable]):
         target_column = self._foreign_key_meta.resolved_target_column
         return target_column.value_type
 
-    @t.overload
+    @overload
     def __init__(
         self,
-        references: t.Type[ReferencedTable],
-        default: t.Any = None,
+        references: type[ReferencedTable],
+        default: Any = None,
         null: bool = True,
         on_delete: OnDelete = OnDelete.cascade,
         on_update: OnUpdate = OnUpdate.cascade,
-        target_column: t.Union[str, Column, None] = None,
+        target_column: Union[str, Column, None] = None,
         **kwargs,
     ) -> None: ...
 
-    @t.overload
+    @overload
     def __init__(
         self,
         references: LazyTableReference,
-        default: t.Any = None,
+        default: Any = None,
         null: bool = True,
         on_delete: OnDelete = OnDelete.cascade,
         on_update: OnUpdate = OnUpdate.cascade,
-        target_column: t.Union[str, Column, None] = None,
+        target_column: Union[str, Column, None] = None,
         **kwargs,
     ) -> None: ...
 
-    @t.overload
+    @overload
     def __init__(
         self,
         references: str,
-        default: t.Any = None,
+        default: Any = None,
         null: bool = True,
         on_delete: OnDelete = OnDelete.cascade,
         on_update: OnUpdate = OnUpdate.cascade,
-        target_column: t.Union[str, Column, None] = None,
+        target_column: Union[str, Column, None] = None,
         **kwargs,
     ) -> None: ...
 
     def __init__(
         self,
-        references: t.Union[t.Type[ReferencedTable], LazyTableReference, str],
-        default: t.Any = None,
+        references: Union[type[ReferencedTable], LazyTableReference, str],
+        default: Any = None,
         null: bool = True,
         on_delete: OnDelete = OnDelete.cascade,
         on_update: OnUpdate = OnUpdate.cascade,
-        target_column: t.Union[str, Column, None] = None,
+        target_column: Union[str, Column, None] = None,
         **kwargs,
     ) -> None:
         from piccolo.table import Table
@@ -1914,7 +1927,7 @@ class ForeignKey(Column, t.Generic[ReferencedTable]):
             target_column=target_column,
         )
 
-    def _setup(self, table_class: t.Type[Table]) -> ForeignKeySetupResponse:
+    def _setup(self, table_class: type[Table]) -> ForeignKeySetupResponse:
         """
         This is called by the ``TableMetaclass``. A ``ForeignKey`` column can
         only be completely setup once it's parent ``Table`` is known.
@@ -1965,9 +1978,9 @@ class ForeignKey(Column, t.Generic[ReferencedTable]):
 
         if is_table_class:
             # Record the reverse relationship on the target table.
-            t.cast(
-                t.Type[Table], references
-            )._meta._foreign_key_references.append(self)
+            cast(type[Table], references)._meta._foreign_key_references.append(
+                self
+            )
 
             # Allow columns on the referenced table to be accessed via
             # auto completion.
@@ -1982,8 +1995,8 @@ class ForeignKey(Column, t.Generic[ReferencedTable]):
         return column
 
     def all_columns(
-        self, exclude: t.Optional[t.List[t.Union[Column, str]]] = None
-    ) -> t.List[Column]:
+        self, exclude: Optional[list[Union[Column, str]]] = None
+    ) -> list[Column]:
         """
         Allow a user to access all of the columns on the related table. This is
         intended for use with ``select`` queries, and saves the user from
@@ -2088,8 +2101,8 @@ class ForeignKey(Column, t.Generic[ReferencedTable]):
         return foreign_key
 
     def all_related(
-        self, exclude: t.Optional[t.List[t.Union[ForeignKey, str]]] = None
-    ) -> t.List[ForeignKey]:
+        self, exclude: Optional[list[Union[ForeignKey, str]]] = None
+    ) -> list[ForeignKey]:
         """
         Returns each ``ForeignKey`` column on the related table. This is
         intended for use with ``objects`` queries, where you want to return
@@ -2157,7 +2170,7 @@ class ForeignKey(Column, t.Generic[ReferencedTable]):
             _fk_meta.proxy_columns.append(_column)
 
     @property
-    def _(self) -> t.Type[ReferencedTable]:
+    def _(self) -> type[ReferencedTable]:
         """
         This allows us specify joins in a way which is friendly to static type
         checkers like Mypy and Pyright.
@@ -2188,9 +2201,9 @@ class ForeignKey(Column, t.Generic[ReferencedTable]):
         easily know if any of your joins contain typos.
 
         """
-        return t.cast(t.Type[ReferencedTable], self)
+        return cast(type[ReferencedTable], self)
 
-    def __getattribute__(self, name: str) -> t.Union[Column, t.Any]:
+    def __getattribute__(self, name: str) -> Union[Column, Any]:
         """
         Returns attributes unmodified unless they're Column instances, in which
         case a copy is returned with an updated call_chain (which records the
@@ -2217,7 +2230,7 @@ class ForeignKey(Column, t.Generic[ReferencedTable]):
         if name.startswith("_"):
             return value
 
-        foreignkey_class: t.Type[ForeignKey] = object.__getattribute__(
+        foreignkey_class: type[ForeignKey] = object.__getattribute__(
             self, "__class__"
         )
 
@@ -2270,21 +2283,21 @@ class ForeignKey(Column, t.Generic[ReferencedTable]):
     ###########################################################################
     # Descriptors
 
-    @t.overload
-    def __get__(self, obj: Table, objtype=None) -> t.Any: ...
+    @overload
+    def __get__(self, obj: Table, objtype=None) -> Any: ...
 
-    @t.overload
+    @overload
     def __get__(
         self, obj: None, objtype=None
     ) -> ForeignKey[ReferencedTable]: ...
 
-    @t.overload
-    def __get__(self, obj: t.Any, objtype=None) -> t.Any: ...
+    @overload
+    def __get__(self, obj: Any, objtype=None) -> Any: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Any):
+    def __set__(self, obj, value: Any):
         obj.__dict__[self._meta.name] = value
 
 
@@ -2307,11 +2320,11 @@ class JSON(Column):
 
     def __init__(
         self,
-        default: t.Union[
+        default: Union[
             str,
-            t.List,
-            t.Dict,
-            t.Callable[[], t.Union[str, t.List, t.Dict]],
+            list,
+            dict,
+            Callable[[], Union[str, list, dict]],
             None,
         ] = "{}",
         **kwargs: Unpack[ColumnKwargs],
@@ -2324,7 +2337,7 @@ class JSON(Column):
         self.default = default
         super().__init__(default=default, **kwargs)
 
-        self.json_operator: t.Optional[str] = None
+        self.json_operator: Optional[str] = None
 
     @property
     def column_type(self):
@@ -2336,7 +2349,7 @@ class JSON(Column):
 
     ###########################################################################
 
-    def arrow(self, key: t.Union[str, int, QueryString]) -> GetChildElement:
+    def arrow(self, key: Union[str, int, QueryString]) -> GetChildElement:
         """
         Allows a child element of the JSON structure to be returned - for
         example::
@@ -2352,7 +2365,7 @@ class JSON(Column):
         return GetChildElement(identifier=self, key=key, alias=alias)
 
     def __getitem__(
-        self, value: t.Union[str, int, QueryString]
+        self, value: Union[str, int, QueryString]
     ) -> GetChildElement:
         """
         A shortcut for the ``arrow`` method, used for retrieving a child
@@ -2371,7 +2384,7 @@ class JSON(Column):
 
     def from_path(
         self,
-        path: t.List[t.Union[str, int]],
+        path: list[Union[str, int]],
     ) -> GetElementFromPath:
         """
         Allows an element of the JSON structure to be returned, which can be
@@ -2407,16 +2420,16 @@ class JSON(Column):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> str: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> JSON: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[str, t.Dict]):
+    def __set__(self, obj, value: Union[str, dict]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -2440,16 +2453,16 @@ class JSONB(JSON):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> str: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> JSONB: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.Union[str, t.Dict]):
+    def __set__(self, obj, value: Union[str, dict]):
         obj.__dict__[self._meta.name] = value
 
 
@@ -2489,12 +2502,12 @@ class Bytea(Column):
 
     def __init__(
         self,
-        default: t.Union[
+        default: Union[
             bytes,
             bytearray,
             Enum,
-            t.Callable[[], bytes],
-            t.Callable[[], bytearray],
+            Callable[[], bytes],
+            Callable[[], bytearray],
             None,
         ] = b"",
         **kwargs: Unpack[ColumnKwargs],
@@ -2510,10 +2523,10 @@ class Bytea(Column):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> bytes: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Bytea: ...
 
     def __get__(self, obj, objtype=None):
@@ -2531,10 +2544,10 @@ class Blob(Bytea):
     ###########################################################################
     # Descriptors
 
-    @t.overload
+    @overload
     def __get__(self, obj: Table, objtype=None) -> bytes: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Blob: ...
 
     def __get__(self, obj, objtype=None):
@@ -2594,9 +2607,7 @@ class Array(Column):
     def __init__(
         self,
         base_column: Column,
-        default: t.Union[
-            t.List, Enum, t.Callable[[], t.List], None
-        ] = ListProxy(),
+        default: Union[list, Enum, Callable[[], list], None] = ListProxy(),
         **kwargs: Unpack[ColumnKwargs],
     ) -> None:
         if isinstance(base_column, ForeignKey):
@@ -2622,7 +2633,7 @@ class Array(Column):
 
         self.base_column = base_column
         self.default = default
-        self.index: t.Optional[int] = None
+        self.index: Optional[int] = None
         super().__init__(default=default, base_column=base_column, **kwargs)
 
     @property
@@ -2641,7 +2652,7 @@ class Array(Column):
             )
         raise Exception("Unrecognized engine type")
 
-    def _setup_base_column(self, table_class: t.Type[Table]):
+    def _setup_base_column(self, table_class: type[Table]):
         """
         Called from the ``Table.__init_subclass__`` - makes sure
         that the ``base_column`` has a reference to the parent table.
@@ -2687,7 +2698,7 @@ class Array(Column):
         else:
             return self.base_column
 
-    def _get_inner_value_type(self) -> t.Type:
+    def _get_inner_value_type(self) -> type:
         """
         A helper function to get the innermost value type for the array. For
         example::
@@ -2728,7 +2739,7 @@ class Array(Column):
             if value < 0:
                 raise ValueError("Only positive integers are allowed.")
 
-            instance = t.cast(Array, self.copy())
+            instance = cast(Array, self.copy())
 
             # We deliberately add 1, as Postgres treats the first array element
             # as index 1.
@@ -2751,7 +2762,7 @@ class Array(Column):
 
         return QueryString(select_string)
 
-    def any(self, value: t.Any) -> Where:
+    def any(self, value: Any) -> Where:
         """
         Check if any of the items in the array match the given value.
 
@@ -2769,7 +2780,7 @@ class Array(Column):
         else:
             raise ValueError("Unrecognised engine type")
 
-    def not_any(self, value: t.Any) -> Where:
+    def not_any(self, value: Any) -> Where:
         """
         Check if the given value isn't in the array.
 
@@ -2787,7 +2798,7 @@ class Array(Column):
         else:
             raise ValueError("Unrecognised engine type")
 
-    def all(self, value: t.Any) -> Where:
+    def all(self, value: Any) -> Where:
         """
         Check if all of the items in the array match the given value.
 
@@ -2805,9 +2816,12 @@ class Array(Column):
         else:
             raise ValueError("Unrecognised engine type")
 
-    def cat(self, value: t.Union[t.Any, t.List[t.Any]]) -> QueryString:
+    def cat(self, value: ArrayType) -> QueryString:
         """
-        Used in an ``update`` query to append items to an array.
+        A convenient way of accessing the
+        :class:`ArrayCat <piccolo.query.functions.array.ArrayCat>` function.
+
+        Used in an ``update`` query to concatenate two arrays.
 
         .. code-block:: python
 
@@ -2815,7 +2829,8 @@ class Array(Column):
             ...     Ticket.seat_numbers: Ticket.seat_numbers.cat([1000])
             ... }).where(Ticket.id == 1)
 
-        You can also use the ``+`` symbol if you prefer:
+        You can also use the ``+`` symbol if you prefer. To concatenate to
+        the end:
 
         .. code-block:: python
 
@@ -2823,33 +2838,140 @@ class Array(Column):
             ...     Ticket.seat_numbers: Ticket.seat_numbers + [1000]
             ... }).where(Ticket.id == 1)
 
+        To concatenate to the start:
+
+        .. code-block:: python
+
+            >>> await Ticket.update({
+            ...     Ticket.seat_numbers: [1000] + Ticket.seat_numbers
+            ... }).where(Ticket.id == 1)
+
+        You can concatenate multiple arrays in one go:
+
+        .. code-block:: python
+
+            >>> await Ticket.update({
+            ...     Ticket.seat_numbers: [1000] + Ticket.seat_numbers + [2000]
+            ... }).where(Ticket.id == 1)
+
+        .. note:: Postgres / CockroachDB only
+
         """
-        engine_type = self._meta.engine_type
-        if engine_type != "postgres" and engine_type != "cockroach":
-            raise ValueError(
-                "Only Postgres and Cockroach support array appending."
-            )
+        from piccolo.query.functions.array import ArrayCat
 
+        # Keep this for backwards compatibility - we had this as a convenience
+        # for users, but it would be nice to remove it in the future.
         if not isinstance(value, list):
             value = [value]
 
-        db_column_name = self._meta.db_column_name
-        return QueryString(f'array_cat("{db_column_name}", {{}})', value)
+        return ArrayCat(array_1=self, array_2=value)
+
+    def remove(self, value: ArrayItemType) -> QueryString:
+        """
+        A convenient way of accessing the
+        :class:`ArrayRemove <piccolo.query.functions.array.ArrayRemove>`
+        function.
+
+        Used in an ``update`` query to remove an item from an array.
+
+        .. code-block:: python
+
+            >>> await Ticket.update({
+            ...     Ticket.seat_numbers: Ticket.seat_numbers.remove(1000)
+            ... }).where(Ticket.id == 1)
+
+        .. note:: Postgres / CockroachDB only
+
+        """
+        from piccolo.query.functions.array import ArrayRemove
+
+        return ArrayRemove(array=self, value=value)
+
+    def prepend(self, value: ArrayItemType) -> QueryString:
+        """
+        A convenient way of accessing the
+        :class:`ArrayPrepend <piccolo.query.functions.array.ArrayPrepend>`
+        function.
+
+        Used in an ``update`` query to prepend an item to an array.
 
-    def __add__(self, value: t.Union[t.Any, t.List[t.Any]]) -> QueryString:
+        .. code-block:: python
+
+            >>> await Ticket.update({
+            ...     Ticket.seat_numbers: Ticket.seat_numbers.prepend(1000)
+            ... }).where(Ticket.id == 1)
+
+        .. note:: Postgres / CockroachDB only
+
+        """
+        from piccolo.query.functions.array import ArrayPrepend
+
+        return ArrayPrepend(array=self, value=value)
+
+    def append(self, value: ArrayItemType) -> QueryString:
+        """
+        A convenient way of accessing the
+        :class:`ArrayAppend <piccolo.query.functions.array.ArrayAppend>`
+        function.
+
+        Used in an ``update`` query to append an item to an array.
+
+        .. code-block:: python
+
+            >>> await Ticket.update({
+            ...     Ticket.seat_numbers: Ticket.seat_numbers.append(1000)
+            ... }).where(Ticket.id == 1)
+
+        .. note:: Postgres / CockroachDB only
+
+        """
+        from piccolo.query.functions.array import ArrayAppend
+
+        return ArrayAppend(array=self, value=value)
+
+    def replace(
+        self, old_value: ArrayItemType, new_value: ArrayItemType
+    ) -> QueryString:
+        """
+        A convenient way of accessing the
+        :class:`ArrayReplace <piccolo.query.functions.array.ArrayReplace>`
+        function.
+
+        Used in an ``update`` query to replace each array item
+        equal to the given value with a new value.
+
+        .. code-block:: python
+
+            >>> await Ticket.update({
+            ...     Ticket.seat_numbers: Ticket.seat_numbers.replace(1000, 500)
+            ... }).where(Ticket.id == 1)
+
+        .. note:: Postgres / CockroachDB only
+
+        """
+        from piccolo.query.functions.array import ArrayReplace
+
+        return ArrayReplace(self, old_value=old_value, new_value=new_value)
+
+    def __add__(self, value: ArrayType) -> QueryString:
         return self.cat(value)
 
+    def __radd__(self, value: ArrayType) -> QueryString:
+        from piccolo.query.functions.array import ArrayCat
+
+        return ArrayCat(array_1=value, array_2=self)
+
     ###########################################################################
     # Descriptors
 
-    @t.overload
-    def __get__(self, obj: Table, objtype=None) -> t.List[t.Any]: ...
+    @overload
+    def __get__(self, obj: Table, objtype=None) -> list[Any]: ...
 
-    @t.overload
+    @overload
     def __get__(self, obj: None, objtype=None) -> Array: ...
 
     def __get__(self, obj, objtype=None):
         return obj.__dict__[self._meta.name] if obj else self
 
-    def __set__(self, obj, value: t.List[t.Any]):
+    def __set__(self, obj, value: list[Any]):
         obj.__dict__[self._meta.name] = value