Upgrading
What changes between versions, the one schema change in 0.2, and how to fix the Postgres migration error some upgrades hit.
0.1 to 0.2
Everything in 0.2 is additive. Your code keeps working, and the only database change is one optional column:
| Table | New column | Type | Notes |
|---|---|---|---|
nuvionPayment | userId | text, nullable | The payer, set when someone pays without an organization. Existing rows stay NULL. |
Upgrade the package, then run the migration you already use:
npm install @umohpyro/better-auth-nuvion@latest- Better Auth CLI:
npx @better-auth/cli migrate(Kysely databases). Read the plan it prints, which should be one added column. - Prisma or Drizzle: regenerate your schema (
npx @better-auth/cli generate), review the diff (one optional field) and run your own migration tool. - Your own code:
const { runMigrations } = await getMigrations(auth.options)frombetter-auth/db/migration, using the samebetter-authyour app runs.
Other changes you may notice: the admin view moved to class names with an optional stylesheet in 0.2.2 (see Styling the admin view), and POST /nuvion/payments accepts a missing organizationId when you set defaultOrganizationId.
0.4 to 0.5
No schema change and nothing to do. New: the onEntityUpdated hook, which runs when an entity's review status changes (for example to approved), confirmed with Nuvion first. See Entity approval.
0.3 to 0.4
No schema change. Behaviour you may notice:
- Events are confirmed with Nuvion before the plugin acts (
confirmEvents, on by default). Your Nuvion key therefore needs read access to funding sessions and transfers, which any key that can create them has. SetconfirmEvents: falseto keep the old behaviour. - The webhook answers
503, not500, for a temporary failure, and acknowledges setup problems (an organization that is not bound) with200after marking the legfailed, so they no longer risk blacklisting your webhook. - The checkout session id is saved on the payment. Payments made before the upgrade fall back to the id in the event.
- Rebinding is possible with
replace: true, andapiKeyandwebhookSecretcan be functions for per-tenant credentials. POST /nuvion/payments/reconcilealso recovers unpaid-looking payments whose checkout settled, and there is an optional scheduler endpoint (cronSecret).
0.2 to 0.3
No schema change. One behaviour change: a payment's split is now saved at checkout as pending legs, instead of being worked out when the money lands. Changing a rule or a parent while a customer is paying no longer changes that payment, and a payer-borne fee rule changed in that window no longer stops the payment for manual review.
- Payments created before you upgrade have no saved legs and are worked out when their money lands, as before.
- A payment nobody pays keeps its pending legs and never moves money. The admin view shows them as
0/2 done. - A lone organization (no parent) has no legs, so nothing changes for it.
Postgres: type "nuvionPayment_userId_idx" does not exist
Who: you upgraded an existing Postgres database to 0.2.0, 0.2.1 or 0.2.2 using a Better Auth CLI older than your better-auth (the CLI bundles its own copy, for example 1.4.22). Fresh installs and Better Auth 1.7 migrations are not affected.
Cause: those versions declared userId as an indexed column. The older migrator turns "add an indexed column to an existing table" into an ALTER TABLE ... ADD INDEX statement, which is not valid Postgres, so it fails after (or instead of) adding the column.
Fix: upgrade to 0.2.3 or later. userId is now a plain column, so the migration only needs ADD COLUMN. If you cannot upgrade yet, add the column yourself and skip the failing step:
-- Postgres
ALTER TABLE "nuvionPayment" ADD COLUMN IF NOT EXISTS "userId" text;
-- MySQL / MariaDB
ALTER TABLE nuvionPayment ADD COLUMN userId varchar(255) NULL;
-- SQLite
ALTER TABLE nuvionPayment ADD COLUMN userId TEXT;Check that it is there:
SELECT column_name FROM information_schema.columns
WHERE table_name = 'nuvionPayment' AND column_name = 'userId';If an earlier attempt already added the column, you only need to upgrade the package. Re-running the migration then reports nothing to do.
Optional index
0.2.3 does not index userId. Listing a payer's own payments (GET /nuvion/payments/list without an organizationId) filters on it, which is fine for thousands of rows. For a large table, add the index yourself:
CREATE INDEX IF NOT EXISTS "nuvionPayment_userId_idx" ON "nuvionPayment" ("userId");Better Auth does not check for indexes, so a manual index does not conflict with later migrations.
Before any upgrade
- Read the plan your migration tool prints before you accept it. A plugin upgrade should only add columns or tables.
- Back up the database or take a snapshot first, as for any schema change.
- Pin the version while you test (
"@umohpyro/better-auth-nuvion": "0.2.3"), then widen the range.