> ## Documentation Index
> Fetch the complete documentation index at: https://ownpay.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> OwnPay is licensed under AGPL-3.0 and is completely free - no licensing fees.
> Production docs URL: https://ownpay.org/docs - append .md to any page URL for clean markdown.
> OwnPay requires PHP 8.3+, MySQL/MariaDB, and Redis.
> MCP server available at https://ownpay.org/docs/mcp for programmatic documentation queries.
> Use root-relative links (e.g. /quickstart) for internal navigation - do NOT include /docs prefix.
> Plugin development: consult /developer/plugins/ pages for correct interfaces and manifests.
> Canonical locations: API auth = /api/authentication, webhook verification = /api/webhooks, rate limits = /resources/rate-limiting, transaction statuses = /fundamentals/payment-flow.
> The documentation uses the Diataxis framework: Tutorials (learning), How-to (tasks), Reference (lookup), Explanation (understanding).

# Migration Guide

> Safely upgrade OwnPay between versions with pre-migration checklists, the auto-migration process, post-migration verification, and rollback procedures.

Upgrading OwnPay between versions involves database schema changes, file updates, and cache clearing. This guide walks you through the process from preparation to verification.

***

## Version history

| From   | To     | Key changes                                                                                                                  |
| :----- | :----- | :--------------------------------------------------------------------------------------------------------------------------- |
| v0.1.0 | v0.2.0 | New tables: `op_disputes`, `op_fee_rules`. New columns on `op_transactions`, `op_gateways`. CSP origin tracking per gateway. |

<Note>
  Check the [Changelog](/docs/resources/changelog) for the full list of changes in each release.
</Note>

***

## Pre-migration checklist

Complete every item before starting an upgrade. Skipping any of these steps risks data loss or a broken installation.

<Steps />

***

## Migration process

OwnPay uses an **auto-migration** system that runs at boot time. You do not need to run migration commands manually.

### How auto-migration works

When `Kernel::boot()` runs, it compares the current schema version (stored in `op_system_settings`) against the code version. If they differ, it executes pending migration files from `database/migrations/` in order.

Each migration file uses a safe pattern:

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
-- Migration: 001_add_disputes_table.sql

CREATE TABLE IF NOT EXISTS op_disputes (
  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  -- ...
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- Add column only if it does not exist
SET @dbname = DATABASE();
SET @tablename = 'op_transactions';
SET @columnname = 'dispute_status';
SET @preparedStatement = (SELECT IF(
  (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS
   WHERE TABLE_SCHEMA = @dbname AND TABLE_NAME = @tablename AND COLUMN_NAME = @columnname) > 0,
  'SELECT 1',
  CONCAT('ALTER TABLE ', @tablename, ' ADD COLUMN ', @columnname, ' VARCHAR(50) DEFAULT NULL')
));
PREPARE alterIfNotExists FROM @preparedStatement;
EXECUTE alterIfNotExists;
DEALLOCATE PREPARE alterIfNotExists;
```

This `SHOW COLUMNS / ALTER TABLE` pattern means migrations are **idempotent** - running them multiple times is safe.

### Running the upgrade

<Steps />

***

## Post-migration steps

After the migration completes, verify everything is working correctly.

<Steps />

***

## Rollback

If something goes wrong after an upgrade, restore from your pre-migration backups.

<Steps />

<Warning>
  Rolling back after the new version has processed transactions will create a data mismatch. The restored database will not contain transactions that were completed between the upgrade and the rollback. Reconcile with your gateway dashboards.
</Warning>

***

## Related Pages

* [Changelog](/docs/resources/changelog) - Detailed release notes for each version
* [Backup and Export](/docs/resources/backup-export) - Backup procedures
* [Performance and Scaling](/docs/resources/performance-scaling) - Post-upgrade optimization
* [Common Errors](/docs/resources/common-errors) - Troubleshooting migration failures


## Related topics

- [System Update](/docs/system/system-update.md)
- [Backup and Export](/docs/resources/backup-export.md)
- [Common Errors](/docs/resources/common-errors.md)
- [Plugin Directory Structure](/docs/developer/plugins/directory-structure.md)
- [Addon Plugin Development - Build General-Purpose Extensions](/docs/developer/plugin-types/addon.md)