---
title: "Upgrading and Migrating DreamFactory | DreamFactory Docs"
source: "https://docs.dreamfactory.com/upgrades-and-migrations/upgrading-and-migrating-dreamfactory"
canonical_url: "https://docs.dreamfactory.com/upgrades-and-migrations/upgrading-and-migrating-dreamfactory"
converted_at: "2026-04-05T14:01:46.503Z"
format: "markdown"
converted_by: "html-to-md-ai"
---
## Current Version & Changelog[​](#current-version--changelog)

The current stable release of DreamFactory is **v7.x**. For the full list of releases, version history, and release notes, see the [DreamFactory GitHub Releases page](https://github.com/dreamfactorysoftware/dreamfactory/releases).

Each release includes a changelog describing new features, bug fixes, and any breaking changes. Before upgrading, review the changelog for your target version to identify any actions required on your end (e.g., PHP version changes, `.env` configuration additions, or deprecated API behaviors).

To check the version currently running on your instance, log in to the DreamFactory admin panel and navigate to **Admin > About DreamFactory**, or run:

```
php artisan df:version
```

## Upgrade Path by Version[​](#upgrade-path-by-version)

Use the table below to identify the appropriate upgrade method based on your current and target versions:

From VersionTo VersionMethodNotes4.x5.xIn-place (`git pull`)PHP 7.4+ required; run `php artisan migrate --seed`5.x6.xIn-place (`git pull`)Review `.env` for new required variables; check deprecated connectors6.x7.xIn-place or fresh migrationPHP 8.1+ required; significant dependency updates — test in staging firstAnyCross-serverFull migration (see below)Use the Major Version Migration process to copy `.env` and system database

**Breaking changes to watch for:**

- **3.x → 4.x**: System database schema changed significantly — a fresh migration is required; data can be re-imported via the 4.x import tools.

- **5.x → 6.x**: Several legacy connectors were removed; verify your active services are still supported.

- **6.x → 7.x**: PHP minimum version bumped to 8.1; Composer 2 required; some deprecated API behaviors removed.

## Pre-Upgrade Checklist[​](#pre-upgrade-checklist)

Before starting any upgrade, complete these steps to ensure you can recover if something goes wrong:

1. **Back up the `.env` file** — this file contains your `APP_KEY`, database credentials, and all environment-specific configuration. Without it, encrypted data is unrecoverable.

```
cp /opt/dreamfactory/.env /opt/dreamfactory/.env.backup.$(date +%Y%m%d)
```

2. **Back up the system database** — the system database stores all your API configurations, roles, scripts, and user accounts. Use the [Step 2: Back Up the System Database](#step-2-back-up-the-system-database) instructions below for your database type.

3. **Note your PHP version** — confirm the target DreamFactory version supports your current PHP installation:

```
php --version
```

4. **Note custom scripts and connectors** — list any event scripts, scripted services, or custom connectors you've added so you can verify they still function after the upgrade.

5. **Check scheduled jobs and cron tasks** — if you use DreamFactory's scheduler or have external cron jobs calling DreamFactory APIs, document them before upgrading.

6. **Test in a staging environment first** — if possible, clone your instance to a staging server and run the upgrade there before applying it to production.

## Rolling Back an Upgrade[​](#rolling-back-an-upgrade)

If an upgrade fails or causes unexpected behavior, restore your previous state using the backups created in the Pre-Upgrade Checklist:

### Step 1: Restore the application files[​](#step-1-restore-the-application-files)

If you performed an in-place upgrade via `git pull`, revert to the previous commit:

```
cd /opt/dreamfactorygit log --oneline -5   # identify the commit hash before the upgradegit checkout <previous-commit-hash>composer install --no-dev --ignore-platform-reqs
```

If you made a file-based backup (`cp -r dreamfactory dreamfactory.backup`), restore it:

```
cp -r /opt/dreamfactory.backup /opt/dreamfactory
```

### Step 2: Restore the system database[​](#step-2-restore-the-system-database)

Use your database-specific method to restore the `dump.sql` backup:

```
# MySQL examplemysql -u root -p dreamfactory < /path/to/dump.sql# PostgreSQL examplepsql -U root -d dreamfactory < /path/to/dump.sql
```

### Step 3: Restore the .env file[​](#step-3-restore-the-env-file)

```
cp /opt/dreamfactory/.env.backup.YYYYMMDD /opt/dreamfactory/.env
```

### Step 4: Clear caches and restart[​](#step-4-clear-caches-and-restart)

```
php artisan cache:clearphp artisan config:clearsudo systemctl restart nginx
```

After restoring, verify the admin panel loads correctly and your APIs respond as expected.

---

This guide covers two different scenarios for updating your DreamFactory installation:

- **Minor Version Upgrades**: In-place updates for patch releases and minor versions (e.g., 7.0.0 → 7.1.0)

- **Major Version Migration**: Complete migration to a new server or environment, typically for major version changes or infrastructure updates

Choose the appropriate section based on your needs. Most users will use the minor version upgrade process for routine updates.

---

# Minor Version Upgrades

For minor version upgrades and patch releases, you can perform an in-place upgrade of your existing DreamFactory installation. This process uses Git, Composer, and Laravel's Artisan commands to update your current environment.

## Prerequisites[​](#prerequisites)

- **Backup Required**: Always perform complete backups before upgrading

- **Git Repository**: Your DreamFactory installation must be a Git repository

- **Command Line Access**: Shell/SSH access to your server

- **Permissions**: Proper file permissions on storage and cache directories

## Upgrade Process[​](#upgrade-process)

### Step 1: Create Backups[​](#step-1-create-backups)

Navigate to one level above your DreamFactory directory (typically `/opt/dreamfactory`) and create a file backup:

```
cd /optcp -r dreamfactory dreamfactory.backup
```

Create a database backup, reference for methods found [here](#step-2-back-up-the-system-database).

### Step 2: Prepare for Upgrade[​](#step-2-prepare-for-upgrade)

Navigate to your DreamFactory installation directory:

```
cd /opt/dreamfactory
```

Stash any local changes to preserve modifications:

```
git stash
```

### Step 3: Update Source Code[​](#step-3-update-source-code)

Switch to the master branch:

```
git checkout master
```

Pull the latest version:

```
git pull origin master
```

### Step 4: Update Dependencies and Permissions[​](#step-4-update-dependencies-and-permissions)

Set proper permissions on cache directories. Replace `{web-service-user}` with your web server user (e.g., `www-data`, `dreamfactory`) and `{your-user-group}` with your user group:

```
sudo chown -R {web-service-user}:{your-user-group} storage/ bootstrap/cache/
```

*e.g., `sudo chown -R dreamfactory:dreamfactory storage/ bootstrap/cache/`*

```
sudo chmod -R 2775 storage/ bootstrap/cache/
```

Update Composer dependencies:

```
composer install --no-dev --ignore-platform-reqs
```

Run database migrations:

```
php artisan migrate --seed
```

Clear application cache and config:

```
php artisan cache:clear
```

```
php artisan config:clear
```

### Step 5: Restart Web Server[​](#step-5-restart-web-server)

For Nginx (DreamFactory default)

```
sudo systemctl restart nginx
```

For Apache:

```
sudo systemctl restart apache2
```

## Troubleshooting[​](#troubleshooting)

### Composer Install Errors[​](#composer-install-errors)

Clear Composer cache:

```
composer clear-cache
```

Remove vendor directory and reinstall:

```
rm -rf vendor/
```

```
composer install --no-dev --ignore-platform-reqs
```

### Permission Issues[​](#permission-issues)

Reset permissions on critical directories:

```
sudo chown -R {web-service-user}:{your-user-group} storage/ bootstrap/cache/
```

*e.g., `sudo chown -R dreamfactory:dreamfactory storage/ bootstrap/cache/`*

```
sudo chmod -R 2775 storage/ bootstrap/cache/
```

### Migration Command Not Found[​](#migration-command-not-found)

Clear compiled cache files:

```
rm -rf bootstrap/cache/compiled.php storage/framework/cache/*
```

Retry the composer install:

```
composer install --no-dev --ignore-platform-reqs
```

## Verification[​](#verification)

After completing the upgrade:

1. **Check DreamFactory version** in the admin interface

2. **Test your APIs** to ensure they're functioning correctly

3. **Verify user access** and permissions are intact

4. **Check system logs** for any errors

---

# Major Version Migration

For major version changes or when migrating to a new server/environment, you'll need to migrate your DreamFactory instance completely. This process focuses on transferring two critical components: the `.env` file and the DreamFactory system database.

## Why These Components Matter[​](#why-these-components-matter)

### `.env` File[​](#env-file)

Contains essential configuration settings including:

- The APP_KEY (critical for data encryption)

- Database credentials

- Caching preferences

- API keys

- Environmental settings

### DreamFactory System Database[​](#dreamfactory-system-database)

Stores all your configuration data:

- User accounts

- Scripts

- API configurations

- System-level metadata

Migrating these components ensures your new instance contains all original configurations, eliminating manual recreation.

## File Transfer Reference[​](#file-transfer-reference)

CLI File Transfer Methods by Deployment Type- VM/Linux
- Docker
- Kubernetes

**FROM remote TO local**

```
scp <user>@<remote-server>:/path/to/file local-destination/
```

Example: `scp [[email protected]](/cdn-cgi/l/email-protection):/opt/dreamfactory/.env .`

**FROM local TO remote**

```
scp local-source <user>@<remote-server>:/path/to/destination/
```

Example: `scp dump.sql [[email protected]](/cdn-cgi/l/email-protection):/opt/dreamfactory/`

**FROM container TO local**

```
docker cp <container_name_or_id>:/path/to/file local-destination/
```

Example: `docker cp df-docker-web-1:/opt/dreamfactory/.env .`

**FROM local TO container**

```
docker cp local-source <container_name_or_id>:/path/to/destination/
```

Example: `docker cp dump.sql df-docker-web-1:/opt/dreamfactory/`

**FROM pod TO local**

```
kubectl cp <namespace>/<pod-name>:/path/to/file local-destination/
```

Example: `kubectl cp df-namespace/df-pod:/opt/dreamfactory/.env .`

**FROM local TO pod**

```
kubectl cp local-source <namespace>/<pod-name>:/path/to/destination/
```

Example: `kubectl cp dump.sql df-namespace/df-pod:/opt/dreamfactory/`

## Migration Process[​](#migration-process)

### Step 1: Back Up the .env File[​](#step-1-back-up-the-env-file)

Navigate to the DreamFactory root directory:

```
cd /opt/dreamfactory
```

Copy the `.env` file to your local machine (see [File Transfer Reference](#file-transfer-reference) for deployment-specific commands):

```
scp <user>@<remote-server>:/opt/dreamfactory/.env .
```

**Tip:** Store the `.env` file in a secure location to recover from any migration issues.

### Step 2: Back Up the System Database[​](#step-2-back-up-the-system-database)

Use the system database credentials from the `.env` file to create a backup:

Backup Methods by Database Type- MySQL
- MS SQL Server
- PostgreSQL
- SQLite

```
mysqldump -u root -p --databases dreamfactory --no-create-db > dump.sql
```

Use SSMS (SQL Server Management Studio) to export the database to a file.

```
pg_dump -U root -d dreamfactory -F p > dump.sql
```

```
sqlite3 dreamfactory.db ".dump" > dump.sql
```

Replace `root` with your database user and `dreamfactory` with your database name if different.

Transfer the backup file to a secure external location:

```
scp <user>@<remote-server>:/opt/dreamfactory/dump.sql .
```

### Step 3: Prepare the New DreamFactory Instance[​](#step-3-prepare-the-new-dreamfactory-instance)

1. Set up a new server with a clean operating system installation

2. Follow the [DreamFactory installation guide](/getting-started/installing-dreamfactory/) for your platform

3. Complete the initial setup by creating an administrator account (this will be replaced with migrated data)

### Step 4: Additional Configuration[​](#step-4-additional-configuration)

#### MySQL Specific Configuration[​](#mysql-specific-configuration)

If upgrading MySQL versions (e.g., 5.6 to 5.7+), you may need to disable strict mode by opening `config/database.php` and adding `'strict' => false` under the MySQL configuration section.

#### General Configuration[​](#general-configuration)

Ensure all system dependencies are up to date. DreamFactory supports PHP 8.1 or later.

### Step 5: Import the System Database[​](#step-5-import-the-system-database)

Transfer the `dump.sql` file to the new server:

```
scp dump.sql <user>@<new-server>:/opt/dreamfactory/
```

Clear the default database schema:

```
php artisan migrate:fresh
```

```
php artisan migrate:reset
```

Import the database backup:

Import Methods by Database Type- MySQL
- MS SQL Server
- PostgreSQL
- SQLite

```
mysql -u root -p dreamfactory < dump.sql
```

Use SSMS (SQL Server Management Studio) to import the database from the file.

```
psql -U root -d dreamfactory < dump.sql
```

```
sqlite3 dreamfactory.db < dump.sql
```

Run database migrations to apply schema updates:

```
php artisan migrate --seed
```

Edit the `.env` file and replace the APP_KEY with the value from your old instance:

```
APP_KEY=YOUR_OLD_APP_KEY_VALUE
```

Clear caches to finalize the configuration:

```
php artisan cache:clear
```

```
php artisan config:clear
```

## Migration Verification[​](#migration-verification)

Log in to the new DreamFactory instance using credentials from the migrated environment. Verify that:

1. **All user accounts** are present and accessible

2. **API configurations** are intact

3. **Scripts and custom logic** are functioning

4. **Database connections** work properly

5. **System settings** match your original configuration

**Congratulations!** Your DreamFactory instance has been successfully migrated.