Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

fix: enforce workspace payee uniqueness (#443)

Albert Dolkun3786bd87f7fc
diff --git a/backend/alembic/versions/076_payee_workspace_uniqueness.py b/backend/alembic/versions/076_payee_workspace_uniqueness.py
new file mode 100644
index 00000000..049e3952
--- /dev/null
+++ b/backend/alembic/versions/076_payee_workspace_uniqueness.py
@@ -0,0 +1,238 @@
+"""enforce normalized payee names within each workspace
+
+Revision ID: 076
+Revises: 075
+Create Date: 2026-07-19
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "076"
+down_revision: Union[str, None] = "075"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+ # Revision 072 made exact names workspace-unique. Collapse case/whitespace
+ # variants before adding the normalized invariant used by the service.
+ op.execute(
+ """
+ CREATE TEMP TABLE payee_dedupe_076 ON COMMIT DROP AS
+ SELECT id AS source_id, target_id
+ FROM (
+ SELECT
+ id,
+ first_value(id) OVER (
+ PARTITION BY workspace_id, lower(btrim(name))
+ ORDER BY created_at, id
+ ) AS target_id,
+ row_number() OVER (
+ PARTITION BY workspace_id, lower(btrim(name))
+ ORDER BY created_at, id
+ ) AS duplicate_rank
+ FROM payees
+ ) ranked
+ WHERE duplicate_rank > 1
+ """
+ )
+ op.execute(
+ """
+ UPDATE payees target
+ SET
+ is_favorite = merged.is_favorite,
+ notes = left(merged.notes, 1000),
+ type = coalesce(target.type, merged.payee_type),
+ email = coalesce(target.email, merged.email),
+ phone = coalesce(target.phone, merged.phone),
+ address = coalesce(target.address, merged.address),
+ website = coalesce(target.website, merged.website)
+ FROM (
+ SELECT
+ duplicates.target_id,
+ bool_or(payees.is_favorite) AS is_favorite,
+ (array_agg(payees.type ORDER BY payees.created_at, payees.id)
+ FILTER (WHERE payees.type IS NOT NULL))[1] AS payee_type,
+ (array_agg(payees.email ORDER BY payees.created_at, payees.id)
+ FILTER (WHERE payees.email IS NOT NULL))[1] AS email,
+ (array_agg(payees.phone ORDER BY payees.created_at, payees.id)
+ FILTER (WHERE payees.phone IS NOT NULL))[1] AS phone,
+ (array_agg(payees.address ORDER BY payees.created_at, payees.id)
+ FILTER (WHERE payees.address IS NOT NULL))[1] AS address,
+ (array_agg(payees.website ORDER BY payees.created_at, payees.id)
+ FILTER (WHERE payees.website IS NOT NULL))[1] AS website,
+ string_agg(
+ DISTINCT NULLIF(btrim(payees.notes), ''),
+ E'\n' ORDER BY NULLIF(btrim(payees.notes), '')
+ ) AS notes
+ FROM payee_dedupe_076 duplicates
+ JOIN payees
+ ON payees.id = duplicates.source_id
+ OR payees.id = duplicates.target_id
+ GROUP BY duplicates.target_id
+ ) merged
+ WHERE target.id = merged.target_id
+ """
+ )
+ op.execute(
+ """
+ WITH candidates AS (
+ SELECT
+ tax_id.id,
+ duplicates.target_id,
+ row_number() OVER (
+ PARTITION BY duplicates.target_id, tax_id.kind
+ ORDER BY tax_id.created_at, tax_id.id
+ ) AS keep_rank
+ FROM payee_tax_ids tax_id
+ JOIN payee_dedupe_076 duplicates
+ ON duplicates.source_id = tax_id.payee_id
+ WHERE NOT EXISTS (
+ SELECT 1
+ FROM payee_tax_ids existing
+ WHERE existing.payee_id = duplicates.target_id
+ AND existing.kind = tax_id.kind
+ )
+ )
+ UPDATE payee_tax_ids tax_id
+ SET payee_id = candidates.target_id
+ FROM candidates
+ WHERE tax_id.id = candidates.id
+ AND candidates.keep_rank = 1
+ """
+ )
+ op.execute(
+ """
+ UPDATE transactions
+ SET payee_id = duplicates.target_id
+ FROM payee_dedupe_076 duplicates
+ WHERE transactions.payee_id = duplicates.source_id
+ """
+ )
+ op.execute(
+ """
+ UPDATE payee_mapping
+ SET
+ target_id = duplicates.target_id,
+ workspace_id = target.workspace_id
+ FROM payee_dedupe_076 duplicates
+ JOIN payees target ON target.id = duplicates.target_id
+ WHERE payee_mapping.target_id = duplicates.source_id
+ """
+ )
+ op.execute(
+ """
+ INSERT INTO payee_mapping (id, user_id, workspace_id, target_id)
+ SELECT source.id, source.user_id, source.workspace_id, duplicates.target_id
+ FROM payee_dedupe_076 duplicates
+ JOIN payees source ON source.id = duplicates.source_id
+ ON CONFLICT (id) DO UPDATE
+ SET
+ target_id = EXCLUDED.target_id,
+ workspace_id = EXCLUDED.workspace_id
+ """
+ )
+ op.execute(
+ """
+ UPDATE rules
+ SET actions = rewritten.actions
+ FROM (
+ SELECT
+ rules_to_update.id,
+ jsonb_agg(
+ CASE
+ WHEN duplicates.target_id IS NOT NULL THEN jsonb_set(
+ action.item::jsonb,
+ '{value}',
+ to_jsonb(duplicates.target_id::text)
+ )
+ ELSE action.item::jsonb
+ END
+ ORDER BY action.ordinality
+ )::json AS actions
+ FROM rules rules_to_update
+ CROSS JOIN LATERAL json_array_elements(rules_to_update.actions)
+ WITH ORDINALITY AS action(item, ordinality)
+ LEFT JOIN payee_dedupe_076 duplicates
+ ON action.item->>'op' = 'set_payee'
+ AND action.item->>'value' = duplicates.source_id::text
+ GROUP BY rules_to_update.id
+ HAVING bool_or(duplicates.target_id IS NOT NULL)
+ ) rewritten
+ WHERE rules.id = rewritten.id
+ """
+ )
+ op.execute(
+ """
+ DO $$
+ DECLARE duplicate record;
+ BEGIN
+ FOR duplicate IN SELECT * FROM payee_dedupe_076 LOOP
+ UPDATE rules
+ SET conditions = (
+ SELECT jsonb_agg(
+ CASE
+ WHEN node.item ? 'conditions' THEN jsonb_set(
+ node.item,
+ '{conditions}',
+ (
+ SELECT jsonb_agg(
+ CASE
+ WHEN leaf.item->>'field' = 'payee_id'
+ AND leaf.item->>'value' = duplicate.source_id::text
+ THEN jsonb_set(
+ leaf.item,
+ '{value}',
+ to_jsonb(duplicate.target_id::text)
+ )
+ ELSE leaf.item
+ END
+ ORDER BY leaf.ordinality
+ )
+ FROM jsonb_array_elements(node.item->'conditions')
+ WITH ORDINALITY AS leaf(item, ordinality)
+ )
+ )
+ WHEN node.item->>'field' = 'payee_id'
+ AND node.item->>'value' = duplicate.source_id::text
+ THEN jsonb_set(
+ node.item,
+ '{value}',
+ to_jsonb(duplicate.target_id::text)
+ )
+ ELSE node.item
+ END
+ ORDER BY node.ordinality
+ )::json
+ FROM jsonb_array_elements(conditions::jsonb)
+ WITH ORDINALITY AS node(item, ordinality)
+ )
+ WHERE jsonb_path_exists(
+ conditions::jsonb,
+ '$.** ? (@.field == "payee_id" && @.value == $source)',
+ jsonb_build_object('source', duplicate.source_id::text)
+ );
+ END LOOP;
+ END $$
+ """
+ )
+ op.execute(
+ """
+ DELETE FROM payees
+ USING payee_dedupe_076 duplicates
+ WHERE payees.id = duplicates.source_id
+ """
+ )
+ op.create_index(
+ "uq_payees_workspace_id_lower_name",
+ "payees",
+ ["workspace_id", sa.text("lower(btrim(name))")],
+ unique=True,
+ )
+
+
+def downgrade() -> None:
+ op.drop_index("uq_payees_workspace_id_lower_name", table_name="payees")
diff --git a/backend/app/models/payee.py b/backend/app/models/payee.py
index fa849c99..18ae672c 100644
--- a/backend/app/models/payee.py
+++ b/backend/app/models/payee.py
@@ -2,7 +2,7 @@ import uuid
from datetime import datetime, timezone
from typing import TYPE_CHECKING, Optional, cast
-from sqlalchemy import Boolean, DateTime, ForeignKey, String, UniqueConstraint
+from sqlalchemy import Boolean, DateTime, ForeignKey, Index, String, UniqueConstraint, func
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import Mapped, mapped_column, relationship
@@ -121,6 +121,14 @@ class PayeeTaxId(Base):
payee: Mapped["Payee"] = relationship(back_populates="tax_ids")
+Index(
+ "uq_payees_workspace_id_lower_name",
+ Payee.workspace_id,
+ func.lower(func.trim(Payee.name)),
+ unique=True,
+)
+
+
class PayeeMapping(Base):
__tablename__ = "payee_mapping"
diff --git a/backend/app/services/payee_service.py b/backend/app/services/payee_service.py
index c31be048..c784b8d6 100644
--- a/backend/app/services/payee_service.py
+++ b/backend/app/services/payee_service.py
@@ -4,6 +4,7 @@ from decimal import Decimal
from typing import Optional, cast
from sqlalchemy import CursorResult, case, select, func, update, delete
+from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession
from app.models.payee import Payee, PayeeMapping, PayeeTaxId
@@ -70,14 +71,10 @@ async def get_or_create_payee(
user_id: uuid.UUID,
name: str,
*,
- workspace_id: Optional[uuid.UUID] = None,
+ workspace_id: uuid.UUID,
source: str = "sync",
) -> Payee:
- """Find a payee by name (case-insensitive) or create a new one.
-
- `user_id` is kept first for backwards compatibility with import/connection
- sync paths. When `workspace_id` is provided, the lookup scopes by workspace;
- otherwise the autostamp listener fills it in on insert.
+ """Find a normalized workspace payee or create it.
`source` is stamped only on rows this call creates. An existing payee is
returned untouched, so a counterparty somebody entered by hand keeps
@@ -94,23 +91,36 @@ async def get_or_create_payee(
if len(name) > 255:
name = name[:255]
-
- lookup = select(Payee).where(func.lower(Payee.name) == name.lower())
- if workspace_id is not None:
- lookup = lookup.where(Payee.workspace_id == workspace_id)
- else:
- lookup = lookup.where(Payee.user_id == user_id)
+ # Mirrors the uq_payees_workspace_id_lower_name index exactly, so the
+ # lookup hits the same row the unique constraint would reject.
+ lookup = select(Payee).where(
+ Payee.workspace_id == workspace_id,
+ func.lower(func.trim(Payee.name)) == name.lower(),
+ )
result = await session.execute(lookup)
payee = result.scalar_one_or_none()
if payee:
return payee
- payee = Payee(user_id=user_id, name=name, source=source)
- if workspace_id is not None:
- payee.workspace_id = workspace_id
- session.add(payee)
- await session.flush()
- return payee
+ payee = Payee(
+ user_id=user_id,
+ workspace_id=workspace_id,
+ name=name,
+ source=source,
+ )
+ try:
+ async with session.begin_nested():
+ session.add(payee)
+ await session.flush()
+ return payee
+ except IntegrityError:
+ # Another sync/import created it after our lookup. The savepoint keeps
+ # the caller's transaction usable; return the winner instead.
+ result = await session.execute(lookup)
+ existing = result.scalar_one_or_none()
+ if existing:
+ return existing
+ raise
async def _apply_tax_ids(
@@ -177,14 +187,22 @@ async def create_payee(
user_id: uuid.UUID,
data: PayeeCreate,
) -> Payee:
+ name = data.name.strip()
+ if not name:
+ raise ValueError("Payee name cannot be empty")
+
# Check uniqueness
existing = await session.execute(
- select(Payee).where(Payee.workspace_id == workspace_id, func.lower(Payee.name) == data.name.strip().lower())
+ select(Payee).where(
+ Payee.workspace_id == workspace_id,
+ func.lower(func.trim(Payee.name)) == name.lower(),
+ )
)
if existing.scalar_one_or_none():
raise ValueError("A payee with this name already exists")
fields = data.model_dump(exclude={"tax_ids"})
+ fields["name"] = name
# Stamped here rather than taken from the request: this is the path a
# person went through a form to reach.
payee = Payee(user_id=user_id, workspace_id=workspace_id, source="manual", **fields)
@@ -215,11 +233,15 @@ async def update_payee(
tax_ids = update_data.pop("tax_ids", None)
# Check name uniqueness if name is being changed
- if "name" in update_data and update_data["name"]:
+ if "name" in update_data:
+ name = (update_data["name"] or "").strip()
+ if not name:
+ raise ValueError("Payee name cannot be empty")
+ update_data["name"] = name
existing = await session.execute(
select(Payee).where(
Payee.workspace_id == workspace_id,
- func.lower(Payee.name) == update_data["name"].strip().lower(),
+ func.lower(func.trim(Payee.name)) == name.lower(),
Payee.id != payee_id,
)
)
diff --git a/backend/tests/test_payee_service.py b/backend/tests/test_payee_service.py
index 91ab8e3b..b9d2ed99 100644
--- a/backend/tests/test_payee_service.py
+++ b/backend/tests/test_payee_service.py
@@ -1,14 +1,17 @@
import uuid
from datetime import date, datetime, timezone
from decimal import Decimal
+from unittest.mock import MagicMock
import pytest
+from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession
-from app.models.payee import PayeeMapping
+from app.models.payee import Payee, PayeeMapping
from app.models.transaction import Transaction
from app.models.account import Account
from app.models.user import User
+from app.models.workspace import Workspace
from app.schemas.payee import PayeeCreate, PayeeUpdate
from app.services.payee_service import (
create_payee,
@@ -188,7 +191,9 @@ async def test_get_payees_includes_zero_transaction_payees(session: AsyncSession
@pytest.mark.asyncio
async def test_get_or_create_payee_creates_new(session: AsyncSession, test_user, test_workspace):
- payee = await get_or_create_payee(session, test_user.id, "New Payee")
+ payee = await get_or_create_payee(
+ session, test_user.id, "New Payee", workspace_id=test_workspace.id
+ )
assert payee.name == "New Payee"
assert payee.user_id == test_user.id
@@ -196,20 +201,110 @@ async def test_get_or_create_payee_creates_new(session: AsyncSession, test_user,
@pytest.mark.asyncio
async def test_get_or_create_payee_returns_existing(session: AsyncSession, test_user, test_workspace):
original = await create_payee(session, test_workspace.id, test_user.id, PayeeCreate(name="Existing"))
- found = await get_or_create_payee(session, test_user.id, "existing") # case-insensitive
+ found = await get_or_create_payee(
+ session, test_user.id, "existing", workspace_id=test_workspace.id
+ )
assert found.id == original.id
@pytest.mark.asyncio
async def test_get_or_create_payee_strips_whitespace(session: AsyncSession, test_user, test_workspace):
- payee = await get_or_create_payee(session, test_user.id, " Trimmed ")
+ payee = await get_or_create_payee(
+ session, test_user.id, " Trimmed ", workspace_id=test_workspace.id
+ )
assert payee.name == "Trimmed"
@pytest.mark.asyncio
async def test_get_or_create_payee_empty_raises(session: AsyncSession, test_user, test_workspace):
with pytest.raises(ValueError, match="cannot be empty"):
- await get_or_create_payee(session, test_user.id, " ")
+ await get_or_create_payee(
+ session, test_user.id, " ", workspace_id=test_workspace.id
+ )
+
+
+async def test_get_or_create_payee_returns_case_insensitive_concurrent_winner(
+ session: AsyncSession, test_user, test_workspace, monkeypatch
+):
+ winner = await create_payee(
+ session,
+ test_workspace.id,
+ test_user.id,
+ PayeeCreate(name="Same Payee"),
+ )
+
+ real_execute = session.execute
+ missing = MagicMock()
+ missing.scalar_one_or_none.return_value = None
+ first_lookup = True
+
+ async def miss_once(*args, **kwargs):
+ nonlocal first_lookup
+ if first_lookup:
+ first_lookup = False
+ return missing
+ return await real_execute(*args, **kwargs)
+
+ monkeypatch.setattr(session, "execute", miss_once)
+
+ result = await get_or_create_payee(
+ session, test_user.id, "same payee", workspace_id=test_workspace.id
+ )
+
+ assert result.id == winner.id
+
+
+async def test_payee_name_is_case_insensitive_within_workspace(
+ session: AsyncSession, test_user, test_workspace
+):
+ session.add(Payee(
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ name="Case Variant",
+ ))
+ await session.flush()
+ session.add(Payee(
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ name=" case variant ",
+ ))
+
+ with pytest.raises(IntegrityError):
+ await session.flush()
+ await session.rollback()
+
+
+async def test_same_user_can_have_same_payee_name_in_different_workspaces(
+ session: AsyncSession, test_user, test_workspace
+):
+ second_workspace = Workspace(
+ name="Second",
+ kind="personal",
+ created_by_user_id=test_user.id,
+ default_currency="USD",
+ )
+ session.add(second_workspace)
+ await session.flush()
+
+ first = await get_or_create_payee(
+ session,
+ test_user.id,
+ "Shared Name",
+ workspace_id=test_workspace.id,
+ )
+ second = await get_or_create_payee(
+ session,
+ test_user.id,
+ "shared name",
+ workspace_id=second_workspace.id,
+ )
+
+ assert first.id != second.id
+ assert first.workspace_id == test_workspace.id
+ assert second.workspace_id == second_workspace.id
# ---------------------------------------------------------------------------
@@ -234,6 +329,28 @@ async def test_update_payee(session: AsyncSession, test_user, test_workspace):
assert updated.type is None
+async def test_create_and_update_payee_strip_names(
+ session: AsyncSession, test_user, test_workspace
+):
+ payee = await create_payee(
+ session,
+ test_workspace.id,
+ test_user.id,
+ PayeeCreate(name=" Trimmed Create "),
+ )
+ assert payee.name == "Trimmed Create"
+
+ updated = await update_payee(
+ session,
+ payee.id,
+ test_workspace.id,
+ PayeeUpdate(name=" Trimmed Update "),
+ )
+ assert updated is not None
+ assert updated.name == "Trimmed Update"
+
+
@pytest.mark.asyncio
async def test_update_payee_not_found(session: AsyncSession, test_user, test_workspace):
result = await update_payee(