Key types & schema

One table, credits, holds every ledger row for every owner. Its shape:

A composite index on (creditable_type, creditable_id, bucket) backs every balance read.

The credit_locks table

The same migration creates credit_locks — one small row per owner that every change bumps, so racing changes of one owner serialise. It holds a version counter only; the ledger stays the single source of truth:

Two independent key types

Two settings type two different columns. They are independent — uuid users holding credits under a bigint credits id is perfectly ordinary:

Both are fixed when the migration first runs, so set them before you publish and migrate:

# Decide before publishing and running the migration — both are fixed at migrate time.
CREDITS_KEY_TYPE=uuid             # your creditable models use HasUuids
CREDITS_PRIMARY_KEY_TYPE=bigint   # the credits table's own id — keep the default

Matching key_type to your models

key_type must match your creditable models’ primary key: keep the default bigint for auto-incrementing ids, and set uuid or ulid when those models use HasUuids or HasUlids:

CREDITS_KEY_TYPE=uuid

Leave it at bigint with uuid-keyed users and PostgreSQL rejects the first change:

SQLSTATE[22P02]: invalid input syntax for type bigint: "01a0e9ca-cf2c-7..."

Every creditable model in the application must share that one key type.

Why primary_key_type defaults to bigint

A Credit is something other packages point at polymorphically, and a Laravel morph column ($table->morphs('subject')) is an unsigned bigint. On a strict engine such as PostgreSQL, a uuid credit id will not go into one:

SQLSTATE[22P02]: invalid input syntax for type bigint: "019f6f33-22b8-737f-a581-849e7cdc517a"

SQLite will not warn you about this — its type affinity silently stores the string in an integer column, so a green SQLite suite proves nothing here.

The constraint: this assumes every morph target in your application shares one key type. If you set CREDITS_PRIMARY_KEY_TYPE=uuid, the models on the other end of your polymorphic relations need to be uuid-keyed too, and the packages owning those columns need to agree. A mixed application — a uuid Credit and a bigint Comment pointed at by the same morph column — is not supported by this package, by Laravel’s own morphs()/uuidMorphs() split, or by anything else. Pick one key type per application.