pg_ledger 0.1.0

data/lib/pg_ledger.rb

@@ -0,0 +1,408 @@
+# frozen_string_literal: true
+
+require "digest"
+
+require_relative "pg_ledger/version"
+require_relative "pg_ledger/entry_builder"
+require_relative "pg_ledger/posting"
+require_relative "pg_ledger/batch"
+require_relative "pg_ledger/ledger_scope"
+
+require_relative "pg_ledger/railtie" if defined?(Rails::Railtie)
+
+module PgLedger
+  class Error < StandardError; end
+  class Unbalanced < Error; end
+  class InsufficientBalance < Error; end
+  class IdempotencyConflict < Error; end
+  class ImmutableRecord < Error; end
+  class UnknownAccount < Error; end
+  class FrozenAccount < Error; end
+  class PeriodClosed < Error; end
+  class OverReversal < Error; end
+  class InvalidReversal < Error; end
+  class CrossLedger < Error; end
+
+  DEFAULT_LEDGER_ID = 1
+
+  class << self
+    # +reverses+: link this entry as a (possibly partial) reversal of another.
+    # The database enforces that per account, the sum of all reversals never
+    # exceeds the original legs, and that legs oppose original directions.
+    def post!(idempotency_key: nil, metadata: {}, posted_at: nil, reverses: nil,
+              ledger_id: DEFAULT_LEDGER_ID)
+      builder = EntryBuilder.new
+      yield builder
+      posting = Posting.new(
+        legs: builder.legs,
+        idempotency_key: idempotency_key,
+        metadata: metadata,
+        posted_at: posted_at,
+        reverses: reverses.is_a?(Entry) ? reverses.id : reverses,
+        ledger_id: ledger_id
+      )
+      ActiveSupport::Notifications.instrument("post.pg_ledger") do |payload|
+        started_at = Time.now
+        entry = posting.call
+        payload.merge!(
+          entry_id: entry.id,
+          legs: builder.legs.size,
+          idempotency_key: idempotency_key,
+          reverses_entry_id: entry.reverses_entry_id,
+          # An entry that predates this call is an idempotent replay, not a post.
+          replayed: idempotency_key ? entry.created_at < started_at - 1 : false
+        )
+        entry
+      end
+    end
+
+    # Decreases the natural balance of +from+ and increases the natural
+    # balance of +to+. Same-currency transfers balance only for accounts of
+    # the same polarity — mixed movements (deposits, issuance) need post!.
+    #
+    # Cross-currency transfers route through per-currency trading accounts
+    # (one balanced pair of legs per currency). Pass either the exact
+    # +to_amount+, or +rate+ as a String/Rational — never a Float — which is
+    # rounded with banker's rounding and recorded in the entry metadata.
+    def transfer!(from:, to:, amount:, idempotency_key: nil, metadata: {}, posted_at: nil,
+                  rate: nil, to_amount: nil, ledger_id: DEFAULT_LEDGER_ID)
+      from = Account.resolve!(from, ledger_id: ledger_id)
+      to = Account.resolve!(to, ledger_id: ledger_id)
+      # Account objects carry their own ledger; it wins over the keyword.
+      ledger_id = from.ledger_id
+
+      if from.currency == to.currency
+        raise ArgumentError, "rate/to_amount are for cross-currency transfers" if rate || to_amount
+        return post!(idempotency_key: idempotency_key, metadata: metadata, posted_at: posted_at,
+                     ledger_id: ledger_id) do |entry|
+          build_transfer(entry, from, to, amount)
+        end
+      end
+
+      to_amount ||= convert(amount, rate)
+      metadata = metadata.merge(
+        "fx" => { "rate" => rate&.to_s, "from_amount" => amount, "from_currency" => from.currency,
+                  "to_amount" => to_amount, "to_currency" => to.currency }
+      )
+      post!(idempotency_key: idempotency_key, metadata: metadata, posted_at: posted_at,
+            ledger_id: ledger_id) do |entry|
+        # One balanced pair per currency: the trading leg mirrors the user leg.
+        build_fx_pair(entry, from, trading_account(from.currency, ledger_id: ledger_id), amount, decrease: true)
+        build_fx_pair(entry, to, trading_account(to.currency, ledger_id: ledger_id), to_amount, decrease: false)
+      end
+    end
+
+    def build_fx_pair(entry, account, trading, amount, decrease:)
+      direction =
+        if decrease
+          account.normal_balance == "debit" ? :credit : :debit
+        else
+          account.normal_balance == "debit" ? :debit : :credit
+        end
+      entry.public_send(direction, account, amount)
+      entry.public_send(direction == :debit ? :credit : :debit, trading, amount)
+    end
+
+    def build_transfer(entry, from, to, amount)
+      entry.public_send(from.normal_balance == "debit" ? :credit : :debit, from, amount)
+      entry.public_send(to.normal_balance == "debit" ? :debit : :credit, to, amount)
+    end
+
+    # Balances per currency, optionally for one owner's accounts / one ledger.
+    def balances(owner: nil, ledger_id: nil, at: nil)
+      unless at
+        scope = Balance.joins(:account)
+        scope = scope.where(pg_ledger_accounts: { owner: owner }) if owner
+        scope = scope.where(pg_ledger_accounts: { ledger_id: ledger_id }) if ledger_id
+        return scope.group("pg_ledger_accounts.currency").sum(:amount)
+      end
+
+      raise ArgumentError, "owner is not supported with at: — resolve accounts and use balance(at:)" if owner
+
+      # As-of balances: daily rollups below the global watermark plus the line
+      # tail up to :at. rollup! advances every account to one shared boundary,
+      # so MAX(day) + 1 is a valid watermark for the whole table. Bound as a
+      # literal — a subquery here blinds the planner (see Account#balance).
+      wm_day = AccountDay.maximum(:day)
+      wm_next = wm_day ? wm_day + 1 : Date.new(1970, 1, 1)
+      ledger_cond = ledger_id ? "AND a.ledger_id = :ledger_id" : ""
+      sql = <<~SQL
+        SELECT currency, SUM(v)::bigint FROM (
+          SELECT a.currency,
+                 SUM(CASE WHEN a.normal_balance = 'debit'
+                          THEN d.debits - d.credits ELSE d.credits - d.debits END) AS v
+          FROM pg_ledger_account_days d
+          JOIN pg_ledger_accounts a ON a.id = d.account_id
+          WHERE d.day < LEAST(:wm_next::date, :at::timestamptz::date) #{ledger_cond}
+          GROUP BY a.currency
+          UNION ALL
+          SELECT a.currency,
+                 SUM(CASE WHEN a.normal_balance = 'debit' THEN l.amount ELSE -l.amount END)
+          FROM pg_ledger_lines l
+          JOIN pg_ledger_accounts a ON a.id = l.debit_account_id
+          WHERE l.posted_at >= LEAST(:wm_next::date, :at::timestamptz::date)::timestamptz
+            AND l.posted_at <= :at #{ledger_cond}
+          GROUP BY a.currency
+          UNION ALL
+          SELECT a.currency,
+                 SUM(CASE WHEN a.normal_balance = 'credit' THEN l.amount ELSE -l.amount END)
+          FROM pg_ledger_lines l
+          JOIN pg_ledger_accounts a ON a.id = l.credit_account_id
+          WHERE l.posted_at >= LEAST(:wm_next::date, :at::timestamptz::date)::timestamptz
+            AND l.posted_at <= :at #{ledger_cond}
+          GROUP BY a.currency
+        ) t GROUP BY currency ORDER BY currency
+      SQL
+      Record.connection.select_rows(Record.sanitize_sql_array(
+        [sql, { at: at, wm_next: wm_next, ledger_id: ledger_id }]
+      )).to_h { |currency, amount| [currency, Integer(amount || 0)] }
+    end
+
+    # Scoped facade: every operation of the module, pinned to one ledger.
+    #   billing = PgLedger.ledger("billing")
+    #   billing.transfer!(from: "a", to: "b", amount: 100)
+    def ledger(name = "main", owner: nil)
+      record = Ledger.find_or_create_by!(name: name.to_s) { |l| l.owner = owner }
+      LedgerScope.new(record)
+    end
+
+    # Changes the shard count of an account's balance. Expansion is instant
+    # and safe under concurrent postings (a posting holding a stale shard
+    # count still hits a valid row; the balance is always the SUM of all
+    # rows). Shrinking lowers the count so new postings use the narrow range,
+    # then merges leftovers on excess shards into shard 0 — concurrent
+    # postings may land on an excess shard with a stale count; a later merge
+    # (or the next autoscale pass) folds them in. The sum is correct at every
+    # moment.
+    def resize_shards!(account, target)
+      account = Account.resolve!(account)
+      raise ArgumentError, "shard count must be >= 1, got #{target}" if target < 1
+      if account.min_balance && target > 1
+        raise ArgumentError, "sharded balances cannot enforce min_balance"
+      end
+      return account if target == account.balance_shards
+
+      Account.transaction do
+        if target > account.balance_shards
+          Balance.insert_all(
+            (account.balance_shards...target).map { |s| { account_id: account.id, shard: s, amount: 0 } },
+            unique_by: [:account_id, :shard]
+          )
+        end
+        account.update!(balance_shards: target)
+      end
+      merge_excess_shards!(account)
+      account
+    end
+
+    # Idempotent: folds balances of shards >= balance_shards into shard 0.
+    # Locks rows one at a time in ascending shard order — same global lock
+    # order as posting, so it cannot deadlock against apply_deltas.
+    def merge_excess_shards!(account)
+      account = Account.resolve!(account)
+      Record.transaction do
+        moved = 0
+        Balance.where(account_id: account.id).where("shard >= ? AND shard > 0", account.balance_shards)
+          .order(:shard).pluck(:shard).each_with_index do |shard, i|
+          if i.zero?
+            Balance.where(account_id: account.id, shard: 0).lock.pick(:id)
+          end
+          row = Balance.where(account_id: account.id, shard: shard).lock.first
+          next if row.amount.zero?
+
+          moved += row.amount
+          row.update!(amount: 0)
+        end
+        if moved != 0
+          Balance.where(account_id: account.id, shard: 0)
+            .update_all(["amount = amount + ?, updated_at = now()", moved])
+        end
+      end
+      nil
+    end
+
+    # One pass of shard autoscaling: doubles shards on accounts whose posting
+    # rate over the window exceeds +up_at+ (per minute), halves when below
+    # +down_at+. Hysteresis (default down_at = up_at / 4) prevents flapping.
+    # Only accounts without min_balance participate. Run it from a periodic
+    # job, like rollup!. Returns the applied changes.
+    def autoscale_shards!(up_at: 12_000, down_at: up_at / 4, window: 60, max_shards: 64)
+      rates = Record.connection.select_rows(Record.sanitize_sql_array([<<~SQL, { window: window }]))
+        SELECT account_id, count(*) * (60.0 / :window) AS per_minute FROM (
+          SELECT debit_account_id AS account_id FROM pg_ledger_lines
+          WHERE posted_at >= now() - make_interval(secs => :window)
+          UNION ALL
+          SELECT credit_account_id FROM pg_ledger_lines
+          WHERE posted_at >= now() - make_interval(secs => :window)
+        ) t GROUP BY 1
+      SQL
+      rates = rates.to_h { |id, rate| [id, rate.to_f] }
+
+      changes = []
+      # Busy accounts are candidates to grow; every sharded account is a
+      # candidate to shrink — a fully idle one has no rows in the window.
+      candidates = Account.where(min_balance: nil)
+        .where("id IN (?) OR balance_shards > 1", rates.keys.presence || [0])
+      candidates.find_each do |account|
+        rate = rates.fetch(account.id, 0.0)
+        from = account.balance_shards
+        target =
+          if rate >= up_at && from < max_shards
+            [from * 2, max_shards].min
+          elsif rate < down_at && from > 1
+            from / 2
+          end
+        next unless target
+
+        resize_shards!(account, target)
+        changes << { account: account.code, currency: account.currency,
+                     from: from, to: target, per_minute: rate.round(1) }
+      end
+      changes
+    end
+
+    attr_writer :trading_account_code
+
+    def trading_account_code
+      @trading_account_code ||= "trading"
+    end
+
+    private
+
+    def convert(amount, rate)
+      case rate
+      when nil
+        raise ArgumentError, "cross-currency transfer needs rate: or to_amount:"
+      when Float
+        raise ArgumentError, "rate must be a String or Rational, not Float (floats corrupt money)"
+      end
+      converted = (Rational(rate) * amount).round(half: :even)
+      raise ArgumentError, "rate #{rate} converts #{amount} to a non-positive amount" unless converted.positive?
+      converted
+    end
+
+    def trading_account(currency, ledger_id: DEFAULT_LEDGER_ID)
+      Account.resolve!(trading_account_code, currency: currency, ledger_id: ledger_id)
+    rescue UnknownAccount
+      begin
+        create_account!(code: trading_account_code, currency: currency,
+                        normal_balance: :credit, min_balance: nil, ledger_id: ledger_id)
+      rescue ActiveRecord::RecordNotUnique
+        Account.resolve!(trading_account_code, currency: currency, ledger_id: ledger_id)
+      end
+    end
+  end
+end
+
+module PgLedger
+  class << self
+
+    # N postings in one statement and one fsync. Atomic as a whole.
+    def batch
+      collector = Batch.new
+      yield collector
+      collector.commit!
+    end
+
+    # Full reversal mirrors every leg. Partial reversal (amount:) is only
+    # defined for two-leg entries — reversing part of a multi-leg entry means
+    # deciding which legs shrink, and that is the caller's call: build it with
+    # post!(reverses: entry) and explicit legs.
+    def reverse!(entry, amount: nil, idempotency_key: nil, metadata: {})
+      lines = entry.lines.includes(:debit_account, :credit_account).to_a
+      if amount && lines.size != 1
+        raise ArgumentError,
+          "amount: is only supported for single-pair entries; use post!(reverses:) with explicit legs"
+      end
+
+      post!(idempotency_key: idempotency_key, metadata: metadata, reverses: entry.id,
+            ledger_id: entry.ledger_id) do |reversal|
+        lines.each do |line|
+          # Storno mirrors the pair: money flows back the way it came.
+          reversal.debit(line.credit_account, amount || line.amount)
+          reversal.credit(line.debit_account, amount || line.amount)
+        end
+      end
+    end
+
+    def freeze_account!(account, ledger_id: DEFAULT_LEDGER_ID)
+      Account.resolve!(account, ledger_id: ledger_id).update!(frozen_at: Time.current)
+    end
+
+    def unfreeze_account!(account, ledger_id: DEFAULT_LEDGER_ID)
+      Account.resolve!(account, ledger_id: ledger_id).update!(frozen_at: nil)
+    end
+
+    # Entries with posted_at earlier than +before+ are rejected from now on.
+    def close_period!(before:, ledger_id: DEFAULT_LEDGER_ID)
+      Record.connection.execute(Record.sanitize_sql_array([<<~SQL, { before: before, ledger: ledger_id }]))
+        INSERT INTO pg_ledger_config (ledger_id, closed_before) VALUES (:ledger, :before)
+        ON CONFLICT (ledger_id) DO UPDATE SET closed_before = EXCLUDED.closed_before
+      SQL
+      nil
+    end
+
+    # Rolls completed days into pg_ledger_account_days. Idempotent; run from a
+    # scheduled job. Days from the current watermark up to (not including)
+    # +upto+ are aggregated from lines in one pass.
+    def rollup!(upto: Date.today)
+      Record.transaction do
+        # The backfill aggregates the whole lines table; without enough
+        # work_mem the hash aggregate spills gigabytes to disk.
+        Record.connection.execute("SET LOCAL work_mem = '256MB'")
+        Record.connection.execute(Record.sanitize_sql_array([<<~SQL, { upto: upto }]))
+        INSERT INTO pg_ledger_account_days (account_id, day, debits, credits)
+        SELECT t.account_id, t.day, SUM(t.d), SUM(t.c) FROM (
+          SELECT l.debit_account_id AS account_id, date_trunc('day', l.posted_at)::date AS day,
+                 l.amount AS d, 0 AS c
+          FROM pg_ledger_lines l
+          WHERE l.posted_at >= (SELECT COALESCE(max(day), '-infinity'::date) FROM pg_ledger_account_days) + interval '1 day'
+            AND l.posted_at < :upto::date
+          UNION ALL
+          SELECT l.credit_account_id, date_trunc('day', l.posted_at)::date, 0, l.amount
+          FROM pg_ledger_lines l
+          WHERE l.posted_at >= (SELECT COALESCE(max(day), '-infinity'::date) FROM pg_ledger_account_days) + interval '1 day'
+            AND l.posted_at < :upto::date
+        ) t
+        GROUP BY 1, 2
+        ON CONFLICT (account_id, day) DO UPDATE
+          SET debits = EXCLUDED.debits, credits = EXCLUDED.credits
+        SQL
+      end
+      nil
+    end
+
+    def create_account!(code:, currency:, normal_balance:, owner: nil, min_balance: 0,
+                        balance_shards: 1, metadata: {}, ledger_id: DEFAULT_LEDGER_ID)
+      if min_balance && balance_shards > 1
+        raise ArgumentError, "sharded balances cannot enforce min_balance — pass min_balance: nil"
+      end
+
+      Account.transaction do
+        account = Account.create!(
+          ledger_id: ledger_id,
+          code: code,
+          currency: currency.to_s.upcase,
+          normal_balance: normal_balance.to_s,
+          owner: owner,
+          min_balance: min_balance,
+          balance_shards: balance_shards,
+          metadata: metadata
+        )
+        Balance.insert_all(
+          balance_shards.times.map { |shard| { account_id: account.id, shard: shard, amount: 0 } }
+        )
+        account
+      end
+    end
+  end
+end
+
+if defined?(ActiveSupport)
+  ActiveSupport.on_load(:active_record) do
+    require_relative "pg_ledger/models"
+  end
+else
+  require "active_record"
+  require_relative "pg_ledger/models"
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: pg_ledger
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Aliaksei Hrakovich
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: 'Append-only double-entry ledger on PostgreSQL: balanced-by-construction
+  paired journal rows, idempotent postings, atomic batches, sharded hot balances,
+  point-in-time reporting.'
+email: hrakovich.dev@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/generators/pg_ledger/install/install_generator.rb
+- lib/generators/pg_ledger/install/templates/create_pg_ledger_tables.rb
+- lib/pg_ledger.rb
+- lib/pg_ledger/batch.rb
+- lib/pg_ledger/entry_builder.rb
+- lib/pg_ledger/ledger_scope.rb
+- lib/pg_ledger/models.rb
+- lib/pg_ledger/posting.rb
+- lib/pg_ledger/railtie.rb
+- lib/pg_ledger/version.rb
+homepage: https://github.com/Slaurmagan/pg_ledger
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Slaurmagan/pg_ledger
+  source_code_uri: https://github.com/Slaurmagan/pg_ledger
+  changelog_uri: https://github.com/Slaurmagan/pg_ledger/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Slaurmagan/pg_ledger/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Double-entry ledger for Rails, backed by Postgres invariants
+test_files: []