Когда колонка balance врёт: double-entry ledger, дебет = кредит и неизменяемые проводки
Одна колонка balance не скажет, откуда пришли деньги и куда ушли. Счета, проводки и строки, дебет = кредит под охраной триггера PostgreSQL, сторно и снапшоты: собираем честный леджер на Django.
Понедельник, утро, тикет в поддержку: «Вчера в кошельке было 350 000 сумов, сегодня 150 000. Я ничего не покупал». Открываете базу. В таблице wallets одна строка на пользователя, в колонке balance — 150 000. И всё. Это была покупка? Возврат, который потом откатили? Баг в прошлом деплое, который списал дважды? Число есть, а истории за ним нет.
Теперь обратный случай, и он хуже, потому что никто не жалуется: повтор callback'а от платёжки зачисляет мерчанту деньги дважды. Мерчант доволен, пользователь доволен, а система тихо создала 2 миллиона сумов из воздуха. Ничто в ней не знает, что деньги должны откуда-то прийти.
У обеих проблем общий корень: баланс хранится как единственный источник правды. Бухгалтеры решили это столетия назад — двойной записью. В этой статье соберём небольшой, но честный double-entry ledger на PostgreSQL и Django: счета, проводки, строки проводок, инвариант «дебет = кредит», который проверяет сама база, балансы со снапшотами и исправления без редактирования истории.
Почему колонки balance недостаточно
Вот версия, которую многие из нас когда-то писали:
# wallets/services.py — the "simple" version
from django.db import transaction
from django.db.models import F
from .models import Wallet
@transaction.atomic
def transfer(sender_id: int, receiver_id: int, amount: int) -> None:
Wallet.objects.filter(user_id=sender_id).update(balance=F("balance") - amount)
Wallet.objects.filter(user_id=receiver_id).update(balance=F("balance") + amount)
Она атомарна, использует F(), так что параллельные обновления не затирают друг друга. И всё равно:
- Нет истории. После
UPDATEпрежнее значение исчезло. Если рядом пишется таблица-логtransactions, она живёт рядом с балансом, а не под ним, и рано или поздно они расходятся: кто-то поправил баланс руками, миграция забыла про лог, какой-то путь в коде его пропустил. - Нет инварианта. Никто не проверяет, что ушедшее из одного кошелька пришло в другой. Если из-за бага вторая строка зачислит
amount + fee, база не возразит. - Исправление уничтожает улики. Естественный способ починить неверный баланс — ещё один
UPDATE. Теперь не видно ни бага, ни исправления. - Деньгам неоткуда взяться. Пополнение с карты просто увеличивает одно число. А откуда деньги? От платёжного провайдера, который теперь нам их должен. Одной колонкой это не выразить.
Баланс — производная величина. Источник правды — список движений, и каждое движение обязано откуда-то деньги взять и куда-то их положить.
Модель: счета, проводки, строки
Двойная запись — это всего три понятия.
Счёт (account) — корзина, в которой лежит ценность: кошелёк пользователя, кошелёк мерчанта, деньги, которые нам должен провайдер, наша комиссионная выручка. У каждого счёта есть тип:
| Тип | Пример в платёжном кошельке | Нормальная сторона |
|---|---|---|
| Актив | Деньги в банке / долг PSP перед нами | Дебет |
| Обязательство | Кошельки пользователей и мерчантов (мы им должны) | Кредит |
| Доход | Комиссии | Кредит |
| Расход | Кэшбэк, стоимость эквайринга | Дебет |
| Капитал | Вложения владельцев | Кредит |
Неожиданное для разработчиков: кошелёк пользователя — это обязательство платформы. Деньги лежат у нас, но принадлежат ему, значит, это долг.
Проводка (journal entry) — одно бизнес-событие: «пополнение», «оплата заказа #812», «возврат». У неё есть описание, время и ключ идемпотентности.
Строка проводки (posting) — сумма, которая попадает на один счёт в рамках одной проводки. В проводке две строки или больше, и правило такое: в каждой проводке сумма дебета равна сумме кредита.
В коде удобно хранить одно знаковое целое: плюс — дебет, минус — кредит. Тогда правило превращается в «строки проводки в сумме дают ноль», а это проверить тривиально.
Пользователь пополняет кошелёк на 200 000 сумов с карты:
| Счёт | Тип | Сумма |
|---|---|---|
| asset:psp-clearing | Актив | +200 000 |
| wallet:user:42 | Обязательство | −200 000 |
PSP должен нам больше (актив растёт по дебету), мы должны пользователю больше (обязательство растёт по кредиту). Потом пользователь платит мерчанту 150 000 сумов с комиссией 1%:
| Счёт | Тип | Сумма |
|---|---|---|
| wallet:user:42 | Обязательство | +150 000 |
| wallet:merchant:7 | Обязательство | −148 500 |
| revenue:fees | Доход | −1 500 |
Дебет 150 000, кредит 148 500 + 1 500. Сумма — ноль. Баланс, который видит пользователь, — сумма его строк с обратным знаком: 200 000 − 150 000 = 50 000. Теперь каждый сум в системе можно проследить до проводки, которая его сдвинула.
Схема PostgreSQL и модели Django
Суммы — целые числа в тийинах (см. прошлую статью про float и Decimal). У счёта есть кэшированный balance, но источник правды по-прежнему строки проводок.
# ledger/models.py
from django.db import models
from django.db.models import Q
class Account(models.Model):
class Kind(models.TextChoices):
ASSET = "asset", "Asset"
LIABILITY = "liability", "Liability"
EQUITY = "equity", "Equity"
REVENUE = "revenue", "Revenue"
EXPENSE = "expense", "Expense"
code = models.CharField(max_length=64, unique=True) # "wallet:user:42", "revenue:fees"
kind = models.CharField(max_length=16, choices=Kind.choices)
currency = models.CharField(max_length=3, default="UZS")
allow_negative = models.BooleanField(default=False)
# Cached sum of all postings, in tiyin, debit-positive.
balance = models.BigIntegerField(default=0)
@property
def is_debit_normal(self) -> bool:
return self.kind in (self.Kind.ASSET, self.Kind.EXPENSE)
@property
def display_balance(self) -> int:
return self.balance if self.is_debit_normal else -self.balance
class JournalEntry(models.Model):
description = models.CharField(max_length=255)
idempotency_key = models.CharField(max_length=64, unique=True)
reverses = models.OneToOneField(
"self",
null=True,
blank=True,
on_delete=models.PROTECT,
related_name="reversed_by",
)
created_at = models.DateTimeField(auto_now_add=True)
class Posting(models.Model):
entry = models.ForeignKey(JournalEntry, on_delete=models.PROTECT, related_name="postings")
account = models.ForeignKey(Account, on_delete=models.PROTECT, related_name="postings")
amount = models.BigIntegerField() # tiyin: + debit, - credit
created_at = models.DateTimeField(auto_now_add=True)
class Meta:
constraints = [
models.CheckConstraint(condition=~Q(amount=0), name="posting_amount_nonzero"),
]
indexes = [
models.Index(
fields=["account", "created_at"],
include=["amount"],
name="posting_acc_time_idx",
),
]
Несколько осознанных решений: on_delete=PROTECT везде, потому что в леджере каскадных удалений не бывает; reverses — это OneToOneField, так что сама база не даст сторнировать одну проводку дважды; индекс (account, created_at) INCLUDE (amount) позволяет PostgreSQL посчитать «баланс на момент X» через index-only scan, если visibility map актуальна. Обратите внимание: начиная с Django 5.1 CheckConstraint принимает condition=, а старый аргумент check= в Django 6.0 удалён.
База сама следит за дебет = кредит
Проверка суммы в Python — хорошо, но гарантия не должна зависеть от того, что каждый путь в коде идёт через ваш сервис. Обычный CHECK не видит других строк, поэтому используем constraint trigger, отложенный до коммита:
CREATE FUNCTION ledger_check_entry_balanced() RETURNS trigger
LANGUAGE plpgsql AS $$
BEGIN
IF EXISTS (
SELECT 1
FROM ledger_posting p
JOIN ledger_account a ON a.id = p.account_id
WHERE p.entry_id = NEW.entry_id
GROUP BY a.currency
HAVING SUM(p.amount) <> 0
) THEN
RAISE EXCEPTION 'journal entry % is not balanced', NEW.entry_id
USING ERRCODE = 'check_violation';
END IF;
RETURN NULL;
END;
$$;
CREATE CONSTRAINT TRIGGER ledger_posting_balanced
AFTER INSERT ON ledger_posting
DEFERRABLE INITIALLY DEFERRED
FOR EACH ROW EXECUTE FUNCTION ledger_check_entry_balanced();
Зачем DEFERRABLE INITIALLY DEFERRED? Строки вставляются по одной (или одним запросом), и после первой строки проводка по определению не сбалансирована. Отложенный constraint trigger срабатывает на COMMIT, когда все строки уже на месте. ERRCODE = 'check_violation' заставляет psycopg бросить CheckViolation, и Django отдаст его как IntegrityError; обычный RAISE EXCEPTION пришёл бы как куда менее говорящий ProgrammingError. Группировка по валюте означает, что проводка должна сходиться в каждой валюте отдельно: «уравновесить» 100 USD сотней UZS не выйдет.
Неизменяемые записи
Строки и проводки только добавляются. Не «по договорённости», а принудительно:
CREATE FUNCTION ledger_forbid_change() RETURNS trigger
LANGUAGE plpgsql AS $$
BEGIN
RAISE EXCEPTION '% is append-only: % is not allowed', TG_TABLE_NAME, TG_OP;
END;
$$;
CREATE TRIGGER ledger_posting_append_only
BEFORE UPDATE OR DELETE ON ledger_posting
FOR EACH ROW EXECUTE FUNCTION ledger_forbid_change();
CREATE TRIGGER ledger_posting_no_truncate
BEFORE TRUNCATE ON ledger_posting
FOR EACH STATEMENT EXECUTE FUNCTION ledger_forbid_change();
CREATE TRIGGER ledger_entry_append_only
BEFORE UPDATE OR DELETE ON ledger_journalentry
FOR EACH ROW EXECUTE FUNCTION ledger_forbid_change();
Построчные триггеры на TRUNCATE не срабатывают, поэтому для него отдельный триггер уровня оператора. Сверху, если приложение подключается ролью, которая не владеет таблицами, REVOKE UPDATE, DELETE, TRUNCATE ON ledger_posting, ledger_journalentry FROM app_role; закрывает дверь ещё и на уровне прав. SQL поставляется обычной миграцией:
# ledger/migrations/0002_ledger_triggers.py
from django.db import migrations
FORWARD = """
-- paste both SQL blocks from above here:
-- ledger_check_entry_balanced + ledger_posting_balanced,
-- ledger_forbid_change + the three append-only triggers
"""
REVERSE = """
DROP TRIGGER IF EXISTS ledger_posting_balanced ON ledger_posting;
DROP TRIGGER IF EXISTS ledger_posting_append_only ON ledger_posting;
DROP TRIGGER IF EXISTS ledger_posting_no_truncate ON ledger_posting;
DROP TRIGGER IF EXISTS ledger_entry_append_only ON ledger_journalentry;
DROP FUNCTION IF EXISTS ledger_check_entry_balanced();
DROP FUNCTION IF EXISTS ledger_forbid_change();
"""
class Migration(migrations.Migration):
dependencies = [("ledger", "0001_initial")]
operations = [migrations.RunSQL(FORWARD, reverse_sql=REVERSE)]
Запись проводки из Django
Сервисная функция — единственное место, которое пишет в леджер. Она валидирует, блокирует затронутые счета, проверяет овердрафт, вставляет строки и обновляет кэшированные балансы — всё в одной транзакции:
# ledger/services.py
from collections import defaultdict
from dataclasses import dataclass
from django.db import transaction
from django.db.models import F
from .models import Account, JournalEntry, Posting
class LedgerError(Exception):
pass
class UnbalancedEntry(LedgerError):
pass
class InsufficientFunds(LedgerError):
pass
@dataclass(frozen=True)
class Line:
account_id: int
amount: int # tiyin: + debit, - credit
@transaction.atomic
def post_entry(
*,
description: str,
idempotency_key: str,
lines: list[Line],
reverses: JournalEntry | None = None,
) -> JournalEntry:
if any(line.amount == 0 for line in lines):
raise UnbalancedEntry("zero-amount line")
existing = JournalEntry.objects.filter(idempotency_key=idempotency_key).first()
if existing is not None:
return existing
deltas: dict[int, int] = defaultdict(int)
for line in lines:
deltas[line.account_id] += line.amount
# Stable lock order: A->B and B->A transfers cannot deadlock each other.
accounts = {
acc.id: acc
for acc in Account.objects.select_for_update()
.filter(id__in=list(deltas))
.order_by("id")
}
if len(accounts) != len(deltas):
raise LedgerError("unknown account")
per_currency: dict[str, int] = defaultdict(int)
for acc_id, delta in deltas.items():
per_currency[accounts[acc_id].currency] += delta
if any(total != 0 for total in per_currency.values()):
raise UnbalancedEntry(f"debits != credits: {dict(per_currency)}")
for acc_id, delta in deltas.items():
acc = accounts[acc_id]
new_balance = acc.balance + delta
shown = new_balance if acc.is_debit_normal else -new_balance
if shown < 0 and not acc.allow_negative:
raise InsufficientFunds(acc.code)
entry = JournalEntry.objects.create(
description=description,
idempotency_key=idempotency_key,
reverses=reverses,
)
Posting.objects.bulk_create(
[Posting(entry=entry, account_id=line.account_id, amount=line.amount) for line in lines]
)
for acc_id, delta in deltas.items():
Account.objects.filter(id=acc_id).update(balance=F("balance") + delta)
return entry
Что происходит по шагам:
- Идемпотентность. Если проводка с таким ключом уже есть, возвращаем её вместо повторной записи. Два параллельных запроса с одним ключом оба пройдут проверку, но
uniqueпропустит только один коммит; второй получитIntegrityErrorи может перечитать победителя (подробно — в статье про ключи идемпотентности). - Блокировка в стабильном порядке.
select_for_update()сorder_by("id")блокирует строки счетов по возрастанию id. Два встречных перевода блокируют в одном порядке и ждут друг друга, а не уходят в deadlock. - Баланс по каждой валюте. Проверка в Python даёт понятную ошибку заранее; триггер — страховочная сетка.
- Овердрафт. Пока строки заблокированы, кэшированный баланс актуален, и потратить одни и те же деньги параллельно никто не сможет.
- Запись. Одна проводка, её строки через
bulk_createи обновление баланса каждого счёта.
Оплата мерчанту из примера выше:
# payments/services.py
from ledger.models import Account, JournalEntry
from ledger.services import Line, post_entry
def pay_merchant(
payer: Account, merchant: Account, fees: Account, amount: int, order_id: int
) -> JournalEntry:
fee = amount // 100 # 1%, rounded down to a whole tiyin
lines = [
Line(payer.id, amount), # debit: we owe the payer less
Line(merchant.id, -(amount - fee)), # credit: we owe the merchant more
Line(fees.id, -fee), # credit: our revenue
]
return post_entry(
description=f"order #{order_id}",
idempotency_key=f"order:{order_id}:pay",
lines=[line for line in lines if line.amount != 0],
)
Обратите внимание на округление комиссии: мерчант получает amount - fee, а не отдельно округлённое amount * 0.99. Посчитайте одну сторону и выведите из неё другую — тогда строки всегда в сумме дают ровно ноль.
Исправления: сторно, а не редактирование
Неверная сумма? Не тот мерчант? Старую проводку не трогаем. Записываем сторнирующую проводку с теми же строками и обратными знаками, а затем, если нужно, новую правильную:
# ledger/services.py (continued)
def reverse_entry(entry: JournalEntry, *, reason: str) -> JournalEntry:
return post_entry(
description=f"reversal of #{entry.pk}: {reason}",
idempotency_key=f"reversal:{entry.pk}",
lines=[Line(p.account_id, -p.amount) for p in entry.postings.all()],
reverses=entry,
)
История теперь читается ровно так, как всё было: исходная проводка, сторно, правильная проводка. Аудитор (или вы в три часа ночи) восстановит любой баланс на любой момент. OneToOneField вместе с ключом идемпотентности делают двойное сторно невозможным.
Балансы и снапшоты
На вопрос «какой баланс» есть три ответа, и реальная система использует все три:
- Кэшированный
balanceна счёте, обновляемый в той же транзакции, что и строки. Его показываем в приложении и по нему проверяем овердрафт. - Сумма строк — истина. На момент времени:
# ledger/queries.py
from datetime import datetime
from django.db.models import Sum
from .models import Account, Posting
def balance_at(account: Account, moment: datetime) -> int:
"""Debit-positive balance from all postings created before `moment`."""
return Posting.objects.filter(account=account, created_at__lt=moment).aggregate(
total=Sum("amount", default=0)
)["total"]
- Снапшоты. Суммировать миллионы строк ради выписки медленно, поэтому закрываем каждый день в отдельную таблицу и суммируем только строки после последнего снапшота:
CREATE TABLE ledger_daily_balance (
account_id bigint NOT NULL REFERENCES ledger_account (id),
day date NOT NULL,
balance bigint NOT NULL, -- closing balance, debit-positive
PRIMARY KEY (account_id, day)
);
-- Closing balance of 2026-11-10 (Tashkent time) = previous day + that day's postings.
INSERT INTO ledger_daily_balance (account_id, day, balance)
SELECT a.id,
DATE '2026-11-10',
COALESCE(prev.balance, 0) + COALESCE(SUM(p.amount), 0)
FROM ledger_account a
LEFT JOIN ledger_daily_balance prev
ON prev.account_id = a.id AND prev.day = DATE '2026-11-09'
LEFT JOIN ledger_posting p
ON p.account_id = a.id
AND p.created_at >= TIMESTAMPTZ '2026-11-10 00:00:00+05'
AND p.created_at < TIMESTAMPTZ '2026-11-11 00:00:00+05'
GROUP BY a.id, prev.balance
ON CONFLICT (account_id, day) DO UPDATE SET balance = EXCLUDED.balance;
Баланс на любой момент — это остаток на конец предыдущего дня плюс строки с полуночи. Прежде чем на это полагаться, измерьте: прогоните EXPLAIN (ANALYZE, BUFFERS) на запросе «баланс на момент» для самого нагруженного счёта со снапшотами и без них.
И наконец сверка. Запускайте регулярно (ночной Celery-задачи достаточно) и поднимайте алерт, если запрос вернул хоть одну строку:
-- 1. Every account: cached balance must equal the sum of its postings.
SELECT a.id, a.code, a.balance, COALESCE(SUM(p.amount), 0) AS computed
FROM ledger_account a
LEFT JOIN ledger_posting p ON p.account_id = a.id
GROUP BY a.id
HAVING a.balance <> COALESCE(SUM(p.amount), 0);
-- 2. The whole ledger, per currency, must sum to zero.
SELECT a.currency, SUM(p.amount) AS total
FROM ledger_posting p
JOIN ledger_account a ON a.id = p.account_id
GROUP BY a.currency
HAVING SUM(p.amount) <> 0;
Подводные камни в продакшене
- Отложенные триггеры и тесты.
TestCaseв Django оборачивает каждый тест в транзакцию, которая никогда не коммитится, поэтому отложенная проверка не срабатывает там, где вы её ждёте. Форсируйте её черезSET CONSTRAINTS ALL IMMEDIATE— он проверяет накопленные события задним числом:
# ledger/tests.py
from django.db import IntegrityError, connection, transaction
from django.test import TestCase
from ledger.models import Account, JournalEntry, Posting
class LedgerInvariantTests(TestCase):
def test_unbalanced_entry_is_rejected_by_db(self):
a = Account.objects.create(code="asset:psp", kind="asset")
b = Account.objects.create(code="wallet:user:1", kind="liability")
with self.assertRaises(IntegrityError):
with transaction.atomic():
entry = JournalEntry.objects.create(description="bad", idempotency_key="t1")
Posting.objects.create(entry=entry, account=a, amount=100)
Posting.objects.create(entry=entry, account=b, amount=-90)
# TestCase never commits, so force the deferred check right here.
with connection.cursor() as cur:
cur.execute("SET CONSTRAINTS ALL IMMEDIATE")
- Внешние транзакции. Если
post_entryвызывается внутри большого блокаatomic(), триггер сработает на внешнем коммите, иIntegrityErrorвылезет там, далеко от причины. Держите записи в леджер в коротких транзакциях. - Триггер на TRUNCATE и очистка тестовой базы.
TransactionTestCaseиmanage.py flushочищают таблицы черезTRUNCATE, поэтому триггер падает с «ledger_posting is append-only». Либо держите тесты леджера наTestCase, либо уберите именно этот триггер и полагайтесь наREVOKE TRUNCATEдля продакшен-роли. - Горячие счета. Каждый платёж кредитует
revenue:fees. Если блокировать его черезselect_for_update(), все платежи выстроятся в очередь на одну строку. Счетам, которые могут уходить в минус или не требуют проверки овердрафта (доходы, PSP clearing), не нужны ни блокировка, ни кэшированный баланс: вставляйте строки, а баланс считайте по строкам и снапшотам. - Время — не порядок коммитов.
created_atвыставляется до коммита (в Python черезauto_now_add, аnow()в PostgreSQL — это время начала транзакции). Транзакция, начавшаяся в 23:59:59 и закоммиченная в 00:00:01, попадёт во «вчера», когда вчерашний снапшот, возможно, уже посчитан. Запускайте снапшот с запасом по времени и держите транзакции короткими. По той же причине никогда не используйте «id последней строки» как водяной знак снапшота: значения sequence выдаются при вставке, а не при коммите. - Сторно может уйти в овердрафт. Сторно пополнения после того, как пользователь потратил деньги, упадёт с
InsufficientFunds. Это правильное поведение, но нужен бизнес-ответ: счёт дебиторки для долга пользователя или ручной процесс. - Админка. Стандартный
ModelAdminдляPostingпредлагает кнопки редактирования и удаления. Регистрируйте его только для чтения (has_change_permissionиhas_delete_permissionвозвращаютFalse), даже если триггер всё равно откажет. - Один счёт — одна валюта. Конвертация — это две проводки через FX-счёт, а не одна проводка со смешанными валютами.
Чеклист
- Деньги — целые числа в минимальных единицах (
BigIntegerField, тийины), никогда не float. - Каждое движение — проводка с ≥ 2 строками, сумма которых по каждой валюте равна нулю.
- Отложенный constraint trigger проверяет сумму на коммите.
- Строки и проводки только добавляются: триггеры плюс отозванные права.
- Ошибки исправляются сторно, никогда не
UPDATE. - Счета блокируются
select_for_update()по возрастанию id. - У каждой проводки уникальный ключ идемпотентности.
- Кэшированные балансы регулярно сверяются со строками; при расхождении — алерт.
- Снапшоты только для закрытых периодов и с запасом по времени.
Итог
Колонка balance говорит вам число; double-entry ledger говорит, почему число именно такое. Дизайн небольшой: счета, проводки, строки и один инвариант — каждая проводка в сумме даёт ноль, и следит за этим PostgreSQL, а не добрые намерения. Добавьте неизменяемость и сторно — и у каждого сума в системе появится прослеживаемое происхождение.
// комментарии
Загружаем комментарии...