Improve migration guide for external services: enhance clarity, add PostgreSQL version compatibility, and update MinIO instructions

Author: akshat5302

docs/self-hosting/manage/migration/migrate-data-to-external-services.md

@@ -1,7 +1,8 @@
 ---
+
 title: Migrate to external services
 description: Move your Plane data from the default local Postgres and MinIO containers to managed cloud services for a production ready deployment.
----
+---------------------------------------------------------------------------------------------------------------------------------------------------
 
 # Migrate to external Postgres and storage
 
@@ -13,10 +14,11 @@ This guide walks through moving your existing data from the local containers to
 
 You need:
 
-- Docker and Docker Compose installed on the host running Plane
-- The PostgreSQL client `psql` and `pg_restore` installed on your local machine
-- Your cloud Postgres connection details: host, username, database name, and password
-- Your cloud storage connection details: endpoint URL, access key, secret key, and bucket name
+* Docker and Docker Compose installed on the host running Plane
+* The PostgreSQL client `psql` and `pg_restore` installed on your local machine
+* Your cloud Postgres connection details: host, username, database name, and password
+* Your cloud storage connection details: endpoint URL, access key, secret key, and bucket name
+* Your cloud PostgreSQL version should ideally match your source PostgreSQL version
 
 ## Stop Plane
 
@@ -49,16 +51,33 @@ docker exec \
 
 Verify the file was created and is not empty:
 
-```
+```bash
 ls -lh plane-backup.dump
 ```
 
 ## Restore the database to your cloud Postgres
 
-Use `pg_restore` on your local machine to load the dump into your cloud database. Replace the placeholder values with your actual connection details.
+Before restoring, clear the existing schema in your cloud database.
+
+```bash
+psql \
+    -h "your-cloud-host.com" \
+    -U "cloud-username" \
+    -d "cloud-database-name" \
+    -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
+```
+
+Restore the dump using `pg_restore`.
+
+The `--no-owner` flag prevents ownership errors when the source database roles do not exist in your cloud database.
+
+The `--no-privileges` flag skips grants for roles that may not exist in the target database.
 
 ```bash
 pg_restore \
+    --no-owner \
+    --no-privileges \
+    --verbose \
     -h "your-cloud-host.com" \
     -U "cloud-username" \
     -d "cloud-database-name" \
@@ -67,42 +86,85 @@ pg_restore \
 
 You will be prompted for your cloud database password.
 
+### PostgreSQL version compatibility
+
+Use a `pg_restore` version that matches your target PostgreSQL version when possible.
+
+For example, if your cloud database is PostgreSQL 15, use PostgreSQL 15 client tools.
+
+If you use a newer `pg_restore` version, you may see:
+
+```text
+ERROR: unrecognized configuration parameter "transaction_timeout"
+Command was: SET transaction_timeout = 0;
+```
+
+This warning can be ignored if the restore continues successfully. Using matching PostgreSQL client tools avoids this warning.
+
 ## Sync storage to your cloud bucket
 
 MinIO ships with the `mc` client. Use it from inside the MinIO container to sync your local uploads to your cloud storage.
 
-1. Create an alias for your local MinIO.
+### 1. Create an alias for your local MinIO
 
-Your MinIO credentials are in plane.env as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
+Your MinIO credentials are in `plane.env` as `MINIO_ROOT_USER` and `MINIO_ROOT_PASSWORD`.
 
 ```bash
 docker compose --env-file plane.env exec plane-minio \
     mc alias set localminio http://localhost:9000 \
     <MINIO_ROOT_USER> <MINIO_ROOT_PASSWORD>
 ```
 
-2. Create an alias for your cloud storage.
+### 2. Create an alias for your cloud storage
+
+For AWS S3, use the S3 endpoint.
+
+Default AWS endpoint:
+
+```bash
+docker compose --env-file plane.env exec plane-minio \
+    mc alias set cloudminio https://s3.amazonaws.com \
+    <CLOUD_ACCESS_KEY> <CLOUD_SECRET_KEY>
+```
+
+Regional AWS S3 endpoint:
 
 ```bash
 docker compose --env-file plane.env exec plane-minio \
-    mc alias set cloudminio <cloud-endpoint-url> \
+    mc alias set cloudminio https://s3.<aws-region>.amazonaws.com \
     <CLOUD_ACCESS_KEY> <CLOUD_SECRET_KEY>
 ```
 
-3. Mirror local data to your cloud bucket.
+For other S3-compatible providers, replace the endpoint with your provider's S3 endpoint.
+
+Verify the connection:
+
+```bash
+docker compose --env-file plane.env exec plane-minio \
+    mc ls cloudminio
+```
+
+### 3. Mirror local data to your cloud bucket
 
 ```bash
 docker compose --env-file plane.env exec plane-minio \
     mc mirror localminio/uploads cloudminio/<bucket-name> --overwrite
 ```
 
-This copies all files from the local uploads bucket to your cloud bucket. The `--overwrite` flag replaces any existing files in the destination with the same name.
+Example:
+
+```bash
+docker compose --env-file plane.env exec plane-minio \
+    mc mirror localminio/uploads cloudminio/my-plane-bucket --overwrite
+```
+
+This copies all files from the local uploads bucket to your cloud bucket. The `--overwrite` flag replaces existing files with the same name.
 
 Wait for the sync to complete before continuing.
 
 ## Update your environment configuration
 
-Open plane.env and update the database and storage settings to point to your cloud services.
+Open `plane.env` and update the database and storage settings to point to your cloud services.
 
 ### Database
 
@@ -112,17 +174,21 @@ DATABASE_URL=postgresql://cloud-username:cloud-password@your-cloud-host.com:5432
 
 ### Storage
 
+For AWS S3:
+
 ```bash
 AWS_ACCESS_KEY_ID=<CLOUD_ACCESS_KEY>
 AWS_SECRET_ACCESS_KEY=<CLOUD_SECRET_KEY>
-AWS_S3_ENDPOINT_URL=<cloud-endpoint-url>
+AWS_S3_ENDPOINT_URL=https://s3.amazonaws.com
 AWS_S3_BUCKET_NAME=<bucket-name>
-AWS_REGION = <aws-region>
+AWS_REGION=<aws-region>
 ```
 
+For other S3-compatible providers, replace `AWS_S3_ENDPOINT_URL` with your provider endpoint.
+
 ## Restart Plane
 
-Bring all services back up
+Bring all services back up:
 
 ```bash
 docker compose up -d
@@ -132,4 +198,4 @@ Open Plane in a browser and verify that your data, attachments, and pages are in
 
 ## After migration
 
-Keep plane-backup.dump in a safe location as a point-in-time backup.
+Keep `plane-backup.dump` in a safe location as a point-in-time backup.