Files
flvx/plans/019-federation-share-traffic-bigint-migration.md
sagitchu e0dd70a054 fix(backend): migrate PostgreSQL traffic columns from int4 to bigint
Widens legacy PostgreSQL traffic/quota columns to BIGINT to prevent
int4 overflow when storing large values like 536870912000 (500GB).

Affected tables:
- user (flow, in_flow, out_flow)
- forward (in_flow, out_flow)
- statistics_flow (flow, total_flow)
- tunnel (flow)
- user_tunnel (flow, in_flow, out_flow)
- peer_share (max_bandwidth, current_flow)

Schema version bumped from 4 to 5 with auto-migration on startup.
2026-03-08 11:48:36 +08:00

983 B

019 Federation Share Traffic Bigint Migration

Checklist

  • Inspect federation share creation failure and identify the PostgreSQL int4 overflow source.
  • Audit other traffic-related legacy PostgreSQL columns that may still be integer despite Go models using int64.
  • Add a schema migration that widens legacy traffic/quota columns from integer to bigint.
  • Add migration tests covering the new schema version branch and error propagation.
  • Run focused backend verification for the migration changes.

Notes

  • The reported failing value 536870912000 is 500 GiB in bytes and overflows PostgreSQL int4.
  • The fix widens historical PostgreSQL traffic columns in user, forward, statistics_flow, tunnel, user_tunnel, and peer_share to BIGINT when needed.

Test Record

  • Command: cd go-backend && go test ./internal/store/repo/...
  • Result: passed.
  • Command: cd go-backend && go test ./tests/contract/...
  • Result: passed.