​

ADR-0006: Go backend as read-only consumer of Better Auth via shared PostgreSQL

​

Status

​

Tags

​

Decision

​

Why

​

Table ownership

​

Permission resolution (multi-tier)

1. JWT claims (orgRole, organizationId) — fast, no IO, used for coarse checks
2. Redis cache (perm:<userId>:<orgId>, 5m TTL) — mid-tier, avoids repeated DB hits
3. PostgreSQL (members table) — authoritative, queried only on cache miss

​

Consistency model

​

Required indexes

idx_users_role
idx_members_user_org                   -- compound: (user_id, organization_id)
idx_members_organization_id_role       -- for listing org members by role

​

Rules for agents

• Go models that map to Better Auth tables must use exact plural table names: users, members, organizations
• Never add write operations to Better Auth table repositories — INSERT, UPDATE, DELETE belong in the Bun backend only
• Role changes must go through the Better Auth API on Bun, never direct SQL from Go — except the single carve-out recorded under Exceptions (E1); do not widen it
• Maintain all three required indexes; do not drop them
• When adding a new permission check, follow the three-tier lookup: JWT claim → Redis → PostgreSQL

​

Exceptions

​

E1 — Rental landlord self-promotion (users.role)

• One meaningful column, users.role, on the session user’s own row. No other user’s row may be written.
• The same statement also sets that row’s updated_at. This is deliberate and is part of the exception: updated_at records when the row last changed, so a write that skipped it would leave every Better Auth consumer reading a timestamp that denies a change which did happen. It carries no authorization meaning of its own. No other Better Auth column may be written.
• The write is guarded in SQL, not in Go: rows already holding admin or superadmin are excluded by the WHERE clause, so a staff role can never be overwritten.
• Only the landlord value may be assigned to role. Granting or revoking any staff role from Go stays forbidden.
• Organization roles (members.role) are not covered. They keep going through the Better Auth API on Bun, with the NATS cache invalidation described above.

​

Bad pattern (do not generate)

// Mutating a Better Auth table from Go (org roles are never exempt; see E1 for
// the one narrow global-role carve-out)
db.Table("members").Where(...).Update("role", newRole) // wrong — Bun owns this

// Replicating identity data into a Go-owned table
type GoUser struct { gorm.Model; BetterAuthID string } // wrong — single source of truth

​

Good pattern

// Read-only org role query
db.Table("members").
    Select("role").
    Where("user_id = ? AND organization_id = ?", userID, orgID).
    Scan(&role)

// Real-time cache invalidation
redis.Del(ctx, fmt.Sprintf("perm:%s:%s", event.UserID, event.OrgID))