pg.ddx.io psycopg/psycopg GitHub issues and pull requests
help / color / mirror / Atom feedFrom: dvarrazzo (@dvarrazzo) <noreply+dvarrazzo@github.com>
To: psycopg/psycopg <noreply+psycopg-psycopg@github.com>
Subject: [psycopg/psycopg] PR #1322: Add pg_lsn adapter
Date: Thu, 11 Jun 2026 01:29:20 +0000
Message-ID: <gh-psycopg-psycopg-1322@github.com> (raw)
This adapters comes from a work in progress from another project but it will be useful in psycopg too.
Because a few MR are already addressing adding catalog type (#1285, #1316), I am sharing here an example. We may compare this approach with others' and create an uniform family of objects.
Missing: docs
cc @DylanYoung.
inline patch 1: psycopg/psycopg/_struct.py, psycopg/psycopg/crdb/_types.py, psycopg/psycopg/postgres.py and 4 more (+265/-4 lines) download inline-1.patch
diff --git a/psycopg/psycopg/_struct.py b/psycopg/psycopg/_struct.py
index 08e1e5ba1..083cd1304 100644
--- a/psycopg/psycopg/_struct.py
+++ b/psycopg/psycopg/_struct.py
@@ -28,6 +28,7 @@ def __call__(self, data: Buffer, start: int | None) -> tuple[int]: ...
pack_int4 = cast(PackInt, struct.Struct("!i").pack)
pack_uint4 = cast(PackInt, struct.Struct("!I").pack)
pack_int8 = cast(PackInt, struct.Struct("!q").pack)
+pack_uint8 = cast(PackInt, struct.Struct("!Q").pack)
pack_float4 = cast(PackFloat, struct.Struct("!f").pack)
pack_float8 = cast(PackFloat, struct.Struct("!d").pack)
@@ -36,6 +37,7 @@ def __call__(self, data: Buffer, start: int | None) -> tuple[int]: ...
unpack_int4 = cast(UnpackInt, struct.Struct("!i").unpack)
unpack_uint4 = cast(UnpackInt, struct.Struct("!I").unpack)
unpack_int8 = cast(UnpackInt, struct.Struct("!q").unpack)
+unpack_uint8 = cast(UnpackInt, struct.Struct("!Q").unpack)
unpack_float4 = cast(UnpackFloat, struct.Struct("!f").unpack)
unpack_float8 = cast(UnpackFloat, struct.Struct("!d").unpack)
diff --git a/psycopg/psycopg/crdb/_types.py b/psycopg/psycopg/crdb/_types.py
index fcf2a47ef..01e496e38 100644
--- a/psycopg/psycopg/crdb/_types.py
+++ b/psycopg/psycopg/crdb/_types.py
@@ -54,9 +54,11 @@ def register_crdb_adapters(context: AdaptContext) -> None:
def _register_postgres_adapters(context: AdaptContext) -> None:
# Same adapters used by PostgreSQL, or a good starting point for customization
- from ..types import array, bool, composite, datetime, numeric, numpy, string, uuid
+ from ..types import array, bool, catalog, composite, datetime, numeric, numpy
+ from ..types import string, uuid
array.register_default_adapters(context)
+ catalog.register_default_adapters(context)
composite.register_default_adapters(context)
datetime.register_default_adapters(context)
string.register_default_adapters(context)
@@ -132,7 +134,7 @@ def register_crdb_types(types: TypesRegistry) -> None:
TypeInfo("int8", 20, 1016, regtype="integer"), # Alias integer -> int8
TypeInfo('"char"', 18, 1002), # special case, not generated
# autogenerated: start
- # Generated from CockroachDB 23.1.10
+ # Generated from CockroachDB 25.1.2
TypeInfo("bit", 1560, 1561, typemod=BitTypeModifier),
TypeInfo("bool", 16, 1000, regtype="boolean"),
TypeInfo("bpchar", 1042, 1014, regtype="character", typemod=CharTypeModifier),
@@ -151,7 +153,9 @@ def register_crdb_types(types: TypesRegistry) -> None:
TypeInfo("numeric", 1700, 1231, typemod=NumericTypeModifier),
TypeInfo("oid", 26, 1028),
TypeInfo("oidvector", 30, 1013),
+ TypeInfo("pg_lsn", 3220, 3221),
TypeInfo("record", 2249, 2287),
+ TypeInfo("refcursor", 1790, 2201),
TypeInfo("regclass", 2205, 2210),
TypeInfo("regnamespace", 4089, 4090),
TypeInfo("regproc", 24, 1008),
diff --git a/psycopg/psycopg/postgres.py b/psycopg/psycopg/postgres.py
index 362012027..4b7615010 100644
--- a/psycopg/psycopg/postgres.py
+++ b/psycopg/psycopg/postgres.py
@@ -133,10 +133,11 @@ def register_default_types(types: TypesRegistry) -> None:
def register_default_adapters(context: AdaptContext) -> None:
- from .types import array, bool, composite, datetime, enum, json, multirange, net
- from .types import none, numeric, numpy, range, string, uuid
+ from .types import array, bool, catalog, composite, datetime, enum, json
+ from .types import multirange, net, none, numeric, numpy, range, string, uuid
array.register_default_adapters(context)
+ catalog.register_default_adapters(context)
composite.register_default_adapters(context)
datetime.register_default_adapters(context)
enum.register_default_adapters(context)
diff --git a/psycopg/psycopg/types/catalog.py b/psycopg/psycopg/types/catalog.py
new file mode 100644
index 000000000..ff491dd81
--- /dev/null
+++ b/psycopg/psycopg/types/catalog.py
@@ -0,0 +1,113 @@
+"""
+Adapters for catalog types.
+"""
+
+# Copyright (C) 2026 The Psycopg Team
+
+from __future__ import annotations
+
+from .. import _oids
+from ..pq import Format
+from ..abc import AdaptContext, Buffer
+from ..adapt import Dumper, Loader
+from .._struct import pack_uint8, unpack_uint8
+
+
+class Lsn(str):
+ """PostgreSQL LSN (Log Sequence Number).
+
+ Subclass of ``str`` so existing code that receives ``pg_lsn`` as a plain
+ string continues to work. Ordering operators use integer comparison, which
+ is correct for LSNs (string ordering is wrong when the hex segments differ
+ in digit count, e.g. ``"F/0"`` vs ``"10/0"``).
+ """
+
+ __slots__ = ("_value",)
+
+ _value: int
+
+ def __new__(cls, value: int | str) -> Lsn:
+ if isinstance(value, str):
+ shigh, slow = value.split("/")
+ value = (int(shigh, 16) << 32) | int(slow, 16)
+
+ if not 0 <= value < 2**64:
+ raise OverflowError("Lsn value must be in the unsigned 64 bits range")
+
+ high = value >> 32
+ low = value & 0xFFFFFFFF
+ s = f"{high:X}/{low:X}"
+
+ lsn = super().__new__(cls, s)
+ lsn._value = value
+ return lsn
+
+ def __repr__(self) -> str:
+ return f"{type(self).__name__}({super().__repr__()})"
+
+ def __int__(self) -> int:
+ return self._value
+
+ def __bool__(self) -> bool:
+ return bool(self._value)
+
+ def __add__(self, other: int) -> Lsn: # type: ignore[override]
+ return Lsn(int(self) + other)
+
+ def __sub__(self, other: Lsn) -> int:
+ return int(self) - int(other)
+
+ def __lt__(self, other: object) -> bool:
+ if isinstance(other, str):
+ return int(self) < int(Lsn(other))
+ return NotImplemented
+
+ def __le__(self, other: object) -> bool:
+ if isinstance(other, str):
+ return int(self) <= int(Lsn(other))
+ return NotImplemented
+
+ def __gt__(self, other: object) -> bool:
+ if isinstance(other, str):
+ return int(self) > int(Lsn(other))
+ return NotImplemented
+
+ def __ge__(self, other: object) -> bool:
+ if isinstance(other, str):
+ return int(self) >= int(Lsn(other))
+ return NotImplemented
+
+
+class LsnLoader(Loader):
+ def load(self, data: Buffer) -> Lsn:
+ return Lsn(bytes(data).decode())
+
+
+class LsnBinaryLoader(Loader):
+ format = Format.BINARY
+
+ def load(self, data: Buffer) -> Lsn:
+ return Lsn(unpack_uint8(data)[0])
+
+
+class LsnDumper(Dumper):
+ oid = _oids.PG_LSN_OID
+
+ def dump(self, obj: Lsn) -> Buffer | None:
+ return str(obj).encode()
+
+
+class LsnBinaryDumper(Dumper):
+ format = Format.BINARY
+ oid = _oids.PG_LSN_OID
+
+ def dump(self, obj: Lsn) -> Buffer | None:
+ return pack_uint8(int(obj))
+
+
+def register_default_adapters(context: AdaptContext) -> None:
+ adapters = context.adapters
+ adapters.register_loader("pg_lsn", LsnLoader)
+ adapters.register_loader("pg_lsn", LsnBinaryLoader)
+ adapters.register_dumper(Lsn, LsnDumper)
+ adapters.register_dumper(Lsn, LsnBinaryDumper)
diff --git a/tests/fix_crdb.py b/tests/fix_crdb.py
index ab8758195..2602e65ff 100644
--- a/tests/fix_crdb.py
+++ b/tests/fix_crdb.py
@@ -119,6 +119,7 @@ def crdb_scs_off(*args):
"severity_nonlocalized": 81794,
"stored procedure": 1751,
"to_regtype": None,
+ "pg_current_wal_lsn": None,
}
_crdb_reason_version = {
diff --git a/tests/fix_faker.py b/tests/fix_faker.py
index 905b6ad4a..9dd1316e6 100644
--- a/tests/fix_faker.py
+++ b/tests/fix_faker.py
@@ -539,6 +539,11 @@ def match_list(self, spec, got, want):
for g, w in zip(got, want):
m(spec[1], g, w)
+ def make_Lsn(self, spec):
+ from psycopg.types.catalog import Lsn
+
+ return Lsn(randrange(0, 2**64))
+
def make_memoryview(self, spec):
return self.make_bytes(spec)
diff --git a/tests/types/test_lsn.py b/tests/types/test_lsn.py
new file mode 100644
index 000000000..3c2705c0e
--- /dev/null
+++ b/tests/types/test_lsn.py
@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+import psycopg
+
+try:
+ from psycopg.types.catalog import Lsn
+except ImportError:
+ # Allow importing the test module with Psycopg < 3.4 installed.
+ # (e.g. to run pool compatibility tests).
+ pass
+
+
+def test_right_module_defined() -> None:
+ assert Lsn.__module__ == "psycopg.types.catalog"
+
+
+def test_from_zero() -> None:
+ assert Lsn(0) == "0/0"
+
+
+def test_bool() -> None:
+ assert not Lsn("0/0")
+ assert Lsn("0/1")
+
+
+def test_from_int_roundtrip() -> None:
+ for v in [0, 1, 2**32, 2**32 - 1, 0xABCDEF12_3456789A]:
+ assert int(Lsn(v)) == v
+
+
+@pytest.mark.parametrize("base, delta", [("0/1", -1), ("FFFFFFFF/FFFFFFFE", 1)])
+def test_overflow(base: str, delta: int) -> None:
+ lsn = Lsn(base)
+ lsn + delta
+ with pytest.raises(OverflowError):
+ lsn + (2 * delta)
+
+
+def test_from_string_uppercase() -> None:
+ assert Lsn("A/3B000000") == "A/3B000000"
+
+
+def test_normalises_to_uppercase() -> None:
+ assert Lsn("a/3b000000") == "A/3B000000"
+
+
+def test_is_str_subclass() -> None:
+ assert isinstance(Lsn(0), str)
+
+
+def test_str_operations_work() -> None:
+ lsn = Lsn("A/3B000000")
+ assert lsn.split("/") == ["A", "3B000000"]
+ assert f"{lsn}" == "A/3B000000"
+
+
+def test_repr() -> None:
+ lsn = Lsn("A/3B000000")
+ assert repr(lsn) == "Lsn(" + repr("A/3B000000") + ")"
+
+
+def test_addition() -> None:
+ result = Lsn("0/100") + 0x100
+ assert result == Lsn("0/200")
+ assert isinstance(result, Lsn)
+
+
+def test_subtraction() -> None:
+ assert Lsn("0/200") - Lsn("0/100") == 0x100
+
+
+def test_ordering_is_numeric_not_lexical() -> None:
+ # "F/0" < "10/0" numerically (0xF < 0x10) but "F" > "1" lexically
+ lsn_f = Lsn("F/0")
+ lsn_10 = Lsn("10/0")
+ assert lsn_f < lsn_10
+ assert lsn_10 > lsn_f
+ assert lsn_f <= lsn_10
+ assert lsn_f <= lsn_f
+ assert lsn_10 >= lsn_10
+
+
+def test_equality() -> None:
+ assert Lsn("A/0") == Lsn("A/0")
+ assert Lsn("A/0") == "A/0"
+ assert Lsn("A/0") != Lsn("B/0")
+
+
+def test_lsn_text_loader_registered() -> None:
+ text_loaders = psycopg.adapters._loaders[0]
+ assert 3220 in text_loaders, "pg_lsn text loader not registered"
+
+
+def test_lsn_binary_loader_registered() -> None:
+ binary_loaders = psycopg.adapters._loaders[1]
+ assert 3220 in binary_loaders, "pg_lsn binary loader not registered"
+
+
+def test_lsn_text_dumper_registered() -> None:
+ text_dumpers = psycopg.adapters._dumpers[psycopg.adapt.PyFormat.TEXT]
+ assert Lsn in text_dumpers, "Lsn text dumper not registered"
+
+
+def test_lsn_binary_dumper_registered() -> None:
+ binary_dumpers = psycopg.adapters._dumpers[psycopg.adapt.PyFormat.BINARY]
+ assert Lsn in binary_dumpers, "Lsn binary dumper not registered"
+
+
+@pytest.mark.crdb_skip("pg_current_wal_lsn")
+@pytest.mark.parametrize("format", psycopg.pq.Format)
+def test_lsn_type_from_db(
+ conn: psycopg.Connection[Any], format: psycopg.pq.Format
+) -> None:
+ row = conn.execute("SELECT pg_current_wal_lsn()", binary=bool(format)).fetchone()
+ assert row is not None
+ lsn = row[0]
+ assert isinstance(lsn, Lsn), f"expected Lsn, got {type(lsn)}"
+ assert isinstance(lsn, str), "Lsn must be str subclass"
+ assert "/" in lsn
+
+
+@pytest.mark.parametrize("format", psycopg.pq.Format)
+def test_lsn_roundtrip_as_parameter(
+ conn: psycopg.Connection[Any], format: psycopg.pq.Format
+) -> None:
+ lsn_in = Lsn("AB/12345678")
+ row = conn.execute("SELECT %s", [lsn_in], binary=bool(format)).fetchone()
+ assert row is not None
+ lsn_out = row[0]
+ assert isinstance(lsn_out, Lsn), f"expected Lsn, got {type(lsn_out)}"
+ assert lsn_out == lsn_in
view thread (28+ messages) latest in thread
Message-ID: <gh-psycopg-psycopg-1322@github.com>
Permalink: ../gh-psycopg-psycopg-1322@github.com/
· ·
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox