| name | paystack-schema-migrations |
| description | Modify or review @alexasomba/better-auth-paystack database schema behavior. Use for paystackProduct, paystackPlan, paystackTransaction, subscription, user.paystackCustomerCode, organization.paystackCustomerCode/email, Better Auth schema overrides, mergeSchema behavior, migrations, indexes, unique fields, and backward-compatible table or field changes.
|
| type | core |
| library | @alexasomba/better-auth-paystack |
| library_version | 3.0.0 |
| license | MIT |
| compatibility | Node.js >=22.0.0; better-auth ^1.6.9; @alexasomba/paystack-node 1.10.x; @alexasomba/better-auth-paystack >=3.0.0 <4.0.0 |
| sources | ["alexasomba/better-auth-paystack:src/schema.ts","alexasomba/better-auth-paystack:src/types.ts","alexasomba/better-auth-paystack:test/paystack.test.ts","alexasomba/better-auth-paystack:test/typesafety.test.ts"] |
Schema Contract
The plugin contributes Better Auth schema through getSchema(options).
Always included:
user.paystackCustomerCodepaystackTransactionpaystackProductpaystackPlan
Included when subscription.enabled is true:
Included when organization.enabled is true:
organization.paystackCustomerCodeorganization.email
Product and plan tables are intentionally always present. Do not make them optional in a
compatibility-preserving release.
Core Patterns
Use schema overrides only for Better Auth-supported customization
Consumers can pass options.schema and the plugin merges it with the default schema via
mergeSchema. Use this for model/field naming and migration metadata, not for removing core billing
state.
When subscriptions are disabled, getSchema strips a user-provided subscription override before
merging so the subscription model is not reintroduced accidentally.
Preserve field compatibility
Schema changes affect persisted billing state. Treat these as migration-sensitive:
- changing required fields
- changing uniqueness or indexes
- renaming
paystack* identity fields
- changing transaction
reference uniqueness
- changing subscription
paystackSubscriptionCode uniqueness
- changing product/plan
paystackId or planCode uniqueness
Prefer additive optional fields in minor releases. Required field changes need clear migrations and
major-version scrutiny.
Keep TypeScript schema exports aligned
PaystackPluginSchema, individual schema exports, and PaystackOptions["schema"] should stay in
sync. If a field is added to a schema table, update the corresponding TypeScript table type in
src/schema.ts.
Common Mistakes
Removing catalog tables when products are unused
The package supports catalog sync and discovery. paystackProduct and paystackPlan remain part of
the plugin schema even if a specific app only uses subscriptions or only uses transactions.
Reintroducing subscription schema when subscriptions are disabled
Keep the guard in getSchema that removes options.schema.subscription unless
subscription.enabled is true.
Forgetting organization schema conditions
Organization billing fields should only be added when organization.enabled is true.
Verification
Run schema and type tests after schema changes:
vp test test/paystack.test.ts test/typesafety.test.ts
vp check
