pg.ddx.io  psycopg/psycopg GitHub issues and pull requests  
help / color / mirror / Atom feed
From: 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.patchdiff --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