@alexasomba/better-auth-paystack/skills/paystack-schema-migrations/SKILL.md

Production-ready Paystack billing plugin for Better Auth. Supports subscriptions, one-time payments, organization billing, secure webhooks and more

---
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.1.1" # x-release-please-version
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.paystackCustomerCode`
- `paystackTransaction`
- `paystackProduct`
- `paystackPlan`

Included when `subscription.enabled` is true:

- `subscription`

Included when `organization.enabled` is true:

- `organization.paystackCustomerCode`
- `organization.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:

```bash
vp test test/paystack.test.ts test/typesafety.test.ts
vp check
```