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

# Upgrade

## Upgrade Process

This guide walks through upgrading Bytebase with Docker. **Complete each step sequentially to ensure a smooth and safe upgrade:**

### Step 1: Stop and Remove the Existing Container

First, gracefully stop and remove your current Bytebase container. This prevents data corruption by ensuring no concurrent access to the metadata.

### Step 2: Back Up Your Metadata

🚨 **Critical:** Before proceeding, create a complete backup of your metadata. This backup serves as your safety net for rolling back if needed. Refer to the "Back up and Restore" section below for comprehensive backup procedures.

### Step 3: Launch the Updated Version

Start Bytebase with the new version using your existing Docker run command, updating only the image tag to the desired version.

<Warning>
  **Production Safety:** Validate your upgrade procedure in a staging environment before executing it in production.
</Warning>

## Back up and Restore (External PostgreSQL)

### Creating a Backup

Execute the following command to create a complete database clone:

```sql theme={null}
CREATE DATABASE metadb_backup WITH TEMPLATE metadb;
```

### Restoring from Backup

1. Stop your Bytebase instance completely.

2. Preserve the current database by renaming it:

   ```sql theme={null}
   ALTER DATABASE metadb RENAME TO metadb_old;
   ```

3. Restore from your backup:

   ```sql theme={null}
   CREATE DATABASE metadb WITH TEMPLATE metadb_backup;
   ```

4. Start Bytebase with the previous version (the version you were running before the failed upgrade).

5. After confirming successful restoration, remove temporary databases:

   ```sql theme={null}
   DROP DATABASE metadb_old;
   DROP DATABASE metadb_backup;
   ```