diff --git a/English/SUMMARY.md b/English/SUMMARY.md index 25c6b93a..58aeb6ac 100644 --- a/English/SUMMARY.md +++ b/English/SUMMARY.md @@ -753,6 +753,7 @@ * [Create and Manage PostgreSQL Cluster](vdb/relational-database-service-rds/postgresql/create-and-manage-postgresql-cluster.md) * [PostgreSQL Cluster Parameters](vdb/relational-database-service-rds/postgresql/postgresql-cluster-parameters.md) * [vDB PostgreSQL - Supported Extensions](vdb/relational-database-service-rds/postgresql/vdb-postgresql-cac-extension-duoc-ho-tro.md) + * [Migrate from Postgres Single to Postgres Cluster](vdb/relational-database-service-rds/postgresql/migrate-from-postgres-single-to-cluster.md) * [MemoryStore Database Service (MDS)](vdb/memorystore-database-service-mds/README.md) * [Redis Standalone](vdb/memorystore-database-service-mds/redis-standalone/README.md) * [Create MDS Instance](vdb/memorystore-database-service-mds/khoi-tao-mds-instance.md) diff --git a/English/vdb/relational-database-service-rds/postgresql/migrate-from-postgres-single-to-cluster.md b/English/vdb/relational-database-service-rds/postgresql/migrate-from-postgres-single-to-cluster.md new file mode 100644 index 00000000..abf9a9f9 --- /dev/null +++ b/English/vdb/relational-database-service-rds/postgresql/migrate-from-postgres-single-to-cluster.md @@ -0,0 +1,247 @@ +# Migrate from Postgres Single to Postgres Cluster + +This guide walks you through exporting data from a **Postgres Single Node** instance and restoring it to a **Postgres Cluster** on vDB. Two scenarios are covered: **Section A** for instances with a single database, and **Section B** for instances with multiple databases. + +{% hint style="info" %} +**Note:** vDB does not support changing the Deployment Type of an existing database. Migration requires creating a new Postgres Cluster and transferring data manually using the steps below. +{% endhint %} + +*** + +## Prerequisites + +Before you begin, make sure: + +* `psql`, `pg_dump` or `pg_dumpall`, and `pg_restore` are installed on the machine running the migration (version must match the PostgreSQL version on the source instance). +* You have credentials (host, username, password) for both the Postgres Single Node and the Postgres Cluster. + +*** + +## A. Single-Database Migration (pg\_dump) + +Use this section when your Postgres Single Node instance contains **one database** that you want to migrate. + + +### Step 1 — Verify Connectivity + +Before starting, confirm that both your Postgres Single Node instance and your Postgres Cluster are running and reachable. + +```bash +# Test Postgres Single Node +psql -h -U -d -c "SELECT 1;" + +# Test Postgres Cluster +psql -h -U -d -c "SELECT 1;" +``` + +*** + +### Step 2 — Export the Database + +Use `pg_dump` to export the source database. Choose the format that matches your preferred restore method. + +**Option A — Custom format** (recommended; for use with `pg_restore`): + +```bash +pg_dump -h -U -d \ + -Fc -f backup.dump +``` + +**Option B — Plain SQL format** (for use with `psql`): + +```bash +pg_dump -h -U -d \ + -Fp > backup.sql +``` + +{% hint style="info" %} +**Tip — Choosing a format:** +The custom format (`-Fc`) produces a compressed binary file and supports multi-job restore with `pg_restore`. The plain SQL format (`-Fp`) produces a human-readable file that is easier to inspect or edit before restoring. Use custom format for large databases. +{% endhint %} + +*** + +### Step 3 — Restore on Postgres Cluster + +Restore the dump to the target cluster using the method that matches your export format. + +**If you exported in custom format**, use `pg_restore`: + +```bash +pg_restore -h -U -d \ + --no-owner --no-privileges backup.dump +``` + +**If you exported in plain SQL format**, use `psql`: + +```bash +psql -h -U -d \ + -f backup.sql +``` + +{% hint style="warning" %} +**Superuser errors during restore:** +Postgres Cluster does not grant superuser access. You may see errors such as `ERROR: must be superuser` or warnings about `ALTER TABLE ... OWNER TO`. These are expected and safe to ignore. + +The flags `--no-owner` and `--no-privileges` (shown above for `pg_restore`) suppress the most common ones. Any error related to table creation or actual data should be investigated before proceeding. +{% endhint %} + +*** + +### Step 4 — Verify the Restored Data + +After the restore completes, validate the data on Postgres Cluster before cutting over traffic. Recommended checks: + +* Compare table counts between source and target. +* Compare row counts for critical tables. +* Spot-check a sample of rows in key tables. +* Test application queries against the restored database. + +*** + +## B. Multi-Database Migration (pg\_dumpall / pg\_dump) + +Use this section when your Postgres Single Node instance contains **more than one database**. + +*** + +### Step 1 — Verify Connectivity + +Confirm that both instances are running and accessible before proceeding. + +```bash +# Test Postgres Single Node +psql -h -U -c "\l" + +# Test Postgres Cluster +psql -h -U -c "\l" +``` + +*** + +### Step 2 — Export All Databases + +Choose one of the two export approaches below. + +**Option A — pg\_dumpall** (exports all databases in a single file): + +```bash +pg_dumpall -h -U \ + --no-role-passwords > alldb.sql +``` + +{% hint style="info" %} +**pg\_dumpall limitations:** +`pg_dumpall` only produces plain SQL output, so you must restore with `psql`. It also attempts to export global objects (roles, tablespaces) that require superuser access. Errors like `ERROR: must be superuser` during export are expected and safe to skip. The flag `--no-role-passwords` omits hashed passwords, which cannot be restored without superuser access anyway. +{% endhint %} + +**Option B — pg\_dump per database** (recommended for most cases): + +Run `pg_dump` separately for each database. This avoids global-permission errors entirely and gives you more control over the restore process. + +```bash +# Repeat for each database +pg_dump -h -U -d \ + -Fc -f .dump +``` + +{% hint style="info" %} +`pg_dump` does not export global objects such as roles and tablespaces. You must recreate these manually on Postgres Cluster before restoring. See Step 3 for details. +{% endhint %} + +*** + +### Step 3 — Recreate Roles and Tablespaces (if needed) + +If your databases rely on specific roles or custom tablespaces, recreate them on Postgres Cluster before restoring. Roles created here will need passwords set manually. + +```sql +-- Recreate a role +CREATE ROLE WITH LOGIN; +ALTER ROLE WITH PASSWORD ''; +``` + +If you used `pg_dumpall`, the SQL file contains role definitions, but some statements may fail due to missing superuser access. Review the file and apply role statements manually as needed. + +*** + +### Step 4 — Restore on Postgres Cluster + +**If you used pg\_dumpall (Option A)**, restore with `psql` connecting to the default `postgres` database: + +```bash +psql -h -U -d postgres \ + -f alldb.sql +``` + +**If you used pg\_dump per database (Option B)**, restore each dump individually: + +```bash +# Repeat for each database +pg_restore -h -U -d \ + --no-owner --no-privileges .dump +``` + +{% hint style="warning" %} +**Role passwords after restore:** +`pg_dumpall` exports role definitions but not their passwords (the `--no-role-passwords` flag omits them, and encrypted passwords cannot be restored without superuser access). After the restore, you must manually set passwords for all roles that require authentication: + +```sql +ALTER ROLE WITH PASSWORD ''; +``` +{% endhint %} + +*** + +### Step 5 — Verify Each Database + +After the restore, verify every database on Postgres Cluster: + +* Confirm all expected databases are present. +* Check table counts and row counts in each database. +* Verify that application users can connect and query successfully. + +*** + +## Quick Reference + +| Scenario | Export tool | Restore tool | When to use | +| --- | --- | --- | --- | +| Single database | `pg_dump -Fc` | `pg_restore` | Large databases; supports multi-job restore | +| Single database | `pg_dump -Fp` | `psql` | Need to inspect or edit the SQL file before restoring | +| Multiple databases | `pg_dumpall` | `psql` | Want to export all databases into a single file | +| Multiple databases | `pg_dump` (per DB) | `pg_restore` / `psql` | Need per-database control; avoids global permission errors | + +*** + +## Troubleshooting + +**`ERROR: must be superuser`** + +Errors mentioning superuser access are expected on both Postgres Single Node and Postgres Cluster. Skip them. Use `--no-owner` and `--no-privileges` flags with `pg_restore` to suppress the most common cases. + +**Roles or ownership errors after restore** + +`pg_dump` and `pg_dumpall` do not carry over role passwords. After restoring, manually set passwords for all roles that need to authenticate. + +**Missing tablespaces** + +If the source database uses custom tablespaces, the restore may fail because those tablespaces do not exist on the target cluster. Recreate any required tablespaces on Postgres Cluster before running the restore. + +**Table creation errors** + +Errors unrelated to superuser access (e.g., duplicate tables, type mismatches) should be investigated before proceeding. Do not skip these. + +**Large databases** + +For very large databases, use `pg_restore --jobs ` to enable multi-job restore with the custom format and reduce the total restore time. + +*** + +## Next Steps + +After verifying the data successfully: + +* Update the connection string in your application to point to the Postgres Cluster (new host, port, and credentials). +* Confirm the application works correctly against the migrated database. +* Delete the old Postgres Single Node on vDB once you have confirmed it is no longer needed. diff --git a/README.md b/README.md index f045629d..dfe4bfab 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,9 @@ | Thông tin | Giá trị | |-----------|---------| -| Tổng số file markdown | 2,113 files | -| Số file Tiếng Việt | 1,134 files | -| Số file Tiếng Anh | 979 files | +| Tổng số file markdown | 2,334 files | +| Số file Tiếng Việt | 1,194 files | +| Số file Tiếng Anh | 1,140 files | | Nền tảng xuất bản | GitBook | --- @@ -121,9 +121,9 @@ This repository contains all user guides and documentation for **GreenNode** ser | Information | Value | |-------------|-------| -| Total markdown files | 2,113 files | -| Vietnamese files | 1,134 files | -| English files | 979 files | +| Total markdown files | 2,334 files | +| Vietnamese files | 1,194 files | +| English files | 1,140 files | | Publishing platform | GitBook | --- diff --git a/Vietnamese/SUMMARY.md b/Vietnamese/SUMMARY.md index 002a2359..fe63d504 100644 --- a/Vietnamese/SUMMARY.md +++ b/Vietnamese/SUMMARY.md @@ -881,6 +881,7 @@ * [Khởi tạo và Quản lý PostgreSQL Cluster](vdb/relational-database-service-rds/postgresql/khoi-tao-va-quan-ly-postgresql-cluster.md) * [Cấu hình tham số cho Cluster](vdb/relational-database-service-rds/postgresql/cau-hinh-tham-so-cho-cluster.md) * [vDB PostgreSQL - Các extension được hỗ trợ](vdb/relational-database-service-rds/postgresql/vdb-postgresql-cac-extension-duoc-ho-tro.md) + * [Migrate từ Postgres Single sang Postgres Cluster](vdb/relational-database-service-rds/postgresql/migrate-tu-postgres-single-sang-cluster.md) * [MemoryStore Database Service (MDS)](vdb/memorystore-database-service-mds/README.md) * [Redis Standalone](vdb/memorystore-database-service-mds/redis-standalone/README.md) * [Khởi tạo MDS Instance](vdb/memorystore-database-service-mds/khoi-tao-mds-instance.md) diff --git a/Vietnamese/vdb/relational-database-service-rds/postgresql/migrate-tu-postgres-single-sang-cluster.md b/Vietnamese/vdb/relational-database-service-rds/postgresql/migrate-tu-postgres-single-sang-cluster.md new file mode 100644 index 00000000..9507ec96 --- /dev/null +++ b/Vietnamese/vdb/relational-database-service-rds/postgresql/migrate-tu-postgres-single-sang-cluster.md @@ -0,0 +1,247 @@ +# Migrate từ Postgres Single sang Postgres Cluster + +Hướng dẫn này mô tả các bước export dữ liệu từ **Postgres Single Node** và restore sang **Postgres Cluster** trên vDB. Tài liệu bao gồm hai tình huống: **Phần A** cho instance có một database, và **Phần B** cho instance có nhiều database. + +{% hint style="info" %} +**Lưu ý:** vDB không hỗ trợ thay đổi Deployment Type của database hiện có. Việc migrate yêu cầu tạo mới một Postgres Cluster và chuyển dữ liệu thủ công theo các bước dưới đây. +{% endhint %} + +*** + +## Điều kiện tiên quyết + +Trước khi bắt đầu, hãy đảm bảo: + +* `psql`, `pg_dump` hoặc `pg_dumpall`, và `pg_restore` đã được cài đặt trên máy thực hiện migrate (phiên bản khớp với PostgreSQL trên instance nguồn). +* Bạn có credentials (host, username, password) cho cả Postgres Single Node và Postgres Cluster. + +*** + +## A. Migrate một database (pg\_dump) + +Sử dụng phần này khi Postgres Single Node của bạn chứa **một database** cần migrate. + + +### Bước 1 — Kiểm tra kết nối + +Trước khi bắt đầu, hãy xác nhận rằng cả Postgres Single Node và Postgres Cluster đều đang chạy và có thể kết nối được. + +```bash +# Kiểm tra Postgres Single Node +psql -h -U -d -c "SELECT 1;" + +# Kiểm tra Postgres Cluster +psql -h -U -d -c "SELECT 1;" +``` + +*** + +### Bước 2 — Xuất dữ liệu + +Dùng `pg_dump` để xuất database nguồn. Chọn định dạng phù hợp với phương thức restore bạn muốn sử dụng. + +**Tùy chọn A — Custom format** (khuyến nghị; dùng với `pg_restore`): + +```bash +pg_dump -h -U -d \ + -Fc -f backup.dump +``` + +**Tùy chọn B — Plain SQL format** (dùng với `psql`): + +```bash +pg_dump -h -U -d \ + -Fp > backup.sql +``` + +{% hint style="info" %} +**Gợi ý — Chọn định dạng phù hợp:** +Custom format (`-Fc`) tạo ra file binary được nén và hỗ trợ restore multi-job với `pg_restore`. Plain SQL format (`-Fp`) tạo ra file có thể dễ dàng đọc được, dễ kiểm tra hoặc chỉnh sửa trước khi restore. Nên dùng custom format cho database có dung lượng lớn. +{% endhint %} + +*** + +### Bước 3 — Restore trên Postgres Cluster + +Restore dữ liệu lên cluster đích theo đúng định dạng đã export. + +**Nếu export bằng custom format**, dùng `pg_restore`: + +```bash +pg_restore -h -U -d \ + --no-owner --no-privileges backup.dump +``` + +**Nếu export bằng plain SQL format**, dùng `psql`: + +```bash +psql -h -U -d \ + -f backup.sql +``` + +{% hint style="warning" %} +**Lỗi superuser trong quá trình restore:** +Postgres Cluster không cấp quyền superuser. Bạn có thể gặp lỗi như `ERROR: must be superuser` hoặc cảnh báo về `ALTER TABLE ... OWNER TO`. Đây là hành vi bình thường và có thể bỏ qua. + +Các flag `--no-owner` và `--no-privileges` (dùng với `pg_restore`) sẽ ngăn các lỗi phổ biến nhất. Bất kỳ lỗi nào liên quan đến việc tạo bảng hoặc dữ liệu thực cần được xem xét kỹ trước khi tiếp tục. +{% endhint %} + +*** + +### Bước 4 — Xác minh dữ liệu sau restore + +Sau khi restore hoàn tất, hãy kiểm tra dữ liệu trên Postgres Cluster trước khi chuyển traffic sang. Khuyến nghị một số kiểm tra: + +* So sánh số lượng bảng giữa nguồn và đích. +* So sánh số lượng bản ghi trong các bảng quan trọng. +* Kiểm tra thủ công một số bản ghi trong các bảng chính. +* Chạy thử các câu truy vấn của ứng dụng với database vừa restore. + +*** + +## B. Migrate nhiều database (pg\_dumpall / pg\_dump) + +Sử dụng phần này khi Postgres Single Node của bạn chứa **nhiều hơn một database**. + +*** + +### Bước 1 — Kiểm tra kết nối + +Xác nhận cả hai instance đang chạy và có thể kết nối được trước khi tiến hành. + +```bash +# Kiểm tra Postgres Single Node +psql -h -U -c "\l" + +# Kiểm tra Postgres Cluster +psql -h -U -c "\l" +``` + +*** + +### Bước 2 — Xuất toàn bộ database + +Chọn một trong hai cách xuất dữ liệu dưới đây. + +**Tùy chọn A — pg\_dumpall** (xuất tất cả database vào một file): + +```bash +pg_dumpall -h -U \ + --no-role-passwords > alldb.sql +``` + +{% hint style="info" %} +**Giới hạn của pg\_dumpall:** +`pg_dumpall` chỉ tạo output dạng plain SQL, do đó bạn phải restore bằng `psql`. Lệnh này cũng cố gắng export các global object (role, tablespace) yêu cầu quyền superuser. Lỗi `ERROR: must be superuser` trong quá trình export là bình thường và có thể bỏ qua. Flag `--no-role-passwords` bỏ qua các mật khẩu đã được mã hóa vì không thể restore chúng mà không có quyền superuser. +{% endhint %} + +**Tùy chọn B — pg\_dump theo từng database** (khuyến nghị cho hầu hết các trường hợp): + +Chạy `pg_dump` riêng cho từng database. Cách này tránh hoàn toàn các lỗi liên quan đến quyền global và cho bạn kiểm soát tốt hơn trong quá trình restore. + +```bash +# Lặp lại cho từng database +pg_dump -h -U -d \ + -Fc -f .dump +``` + +{% hint style="info" %} +`pg_dump` không export các global object như role và tablespace. Bạn phải tạo lại chúng thủ công trên Postgres Cluster trước khi restore. Xem Bước 3 để biết thêm chi tiết. +{% endhint %} + +*** + +### Bước 3 — Tạo lại Role và Tablespace (nếu cần) + +Nếu database của bạn phụ thuộc vào các role hoặc tablespace cụ thể, hãy tạo lại chúng trên Postgres Cluster trước khi restore. Các role được tạo ở đây cần đặt mật khẩu thủ công. + +```sql +-- Tạo lại một role +CREATE ROLE WITH LOGIN; +ALTER ROLE WITH PASSWORD ''; +``` + +Nếu bạn dùng `pg_dumpall`, file SQL chứa định nghĩa role nhưng một số câu lệnh có thể thất bại do thiếu quyền superuser. Hãy xem qua file và áp dụng thủ công các câu lệnh quản lý role khi cần. + +*** + +### Bước 4 — Restore trên Postgres Cluster + +**Nếu dùng pg\_dumpall (Tùy chọn A)**, restore bằng `psql` kết nối vào database mặc định `postgres`: + +```bash +psql -h -U -d postgres \ + -f alldb.sql +``` + +**Nếu dùng pg\_dump theo từng database (Tùy chọn B)**, restore từng file dump riêng lẻ: + +```bash +# Lặp lại cho từng database +pg_restore -h -U -d \ + --no-owner --no-privileges .dump +``` + +{% hint style="warning" %} +**Mật khẩu role sau khi restore:** +`pg_dumpall` export định nghĩa role nhưng không bao gồm mật khẩu (flag `--no-role-passwords` bỏ qua chúng, và mật khẩu đã mã hóa không thể restore mà không có quyền superuser). Sau khi restore, bạn phải đặt thủ công mật khẩu cho tất cả role cần xác thực: + +```sql +ALTER ROLE WITH PASSWORD ''; +``` +{% endhint %} + +*** + +### Bước 5 — Xác minh từng database + +Sau khi restore, kiểm tra toàn bộ database trên Postgres Cluster. Khuyến nghị một số kiểm tra: + +* Xác nhận tất cả database dự kiến đều hiện diện. +* Kiểm tra số lượng bảng và số lượng bản ghi trong từng database. +* Xác minh rằng người dùng ứng dụng có thể kết nối và truy vấn thành công. + +*** + +## Bảng tham khảo nhanh + +| Tình huống | Công cụ export | Công cụ restore | Khi nào dùng | +| --- | --- | --- | --- | +| Một database | `pg_dump -Fc` | `pg_restore` | Database lớn, cần restore nhanh (hỗ trợ multi-job) | +| Một database | `pg_dump -Fp` | `psql` | Cần đọc hoặc chỉnh sửa file SQL trước khi restore | +| Nhiều database | `pg_dumpall` | `psql` | Muốn export tất cả database vào một file duy nhất | +| Nhiều database | `pg_dump` (từng DB) | `pg_restore` / `psql` | Cần kiểm soát riêng từng database, tránh lỗi quyền global | + +*** + +## Một số vấn đề thường gặp + +**`ERROR: must be superuser`** + +Lỗi về quyền superuser là bình thường trên cả Postgres Single Node và Postgres Cluster. Bỏ qua chúng. Dùng flag `--no-owner` và `--no-privileges` với `pg_restore` để ngăn các lỗi phổ biến nhất. + +**Lỗi về role hoặc ownership sau khi restore** + +`pg_dump` và `pg_dumpall` không mang theo mật khẩu role. Sau khi restore, đặt thủ công mật khẩu cho tất cả role cần xác thực. + +**Thiếu tablespace** + +Nếu database nguồn sử dụng custom tablespace, quá trình restore có thể thất bại vì các tablespace đó không tồn tại trên cluster đích. Tạo lại các tablespace cần thiết trên Postgres Cluster trước khi chạy lệnh restore. + +**Lỗi tạo bảng** + +Các lỗi không liên quan đến quyền superuser (ví dụ: bảng trùng lặp, không khớp kiểu dữ liệu) cần được điều tra trước khi tiếp tục. Không bỏ qua những lỗi này. + +**Database dung lượng lớn** + +Với database rất lớn, dùng `pg_restore --jobs ` để bật chế độ restore multi-job với custom format và giảm thời gian restore tổng thể. + +*** + +## Bước tiếp theo + +Sau khi xác minh dữ liệu thành công: + +* Cập nhật connection string trong ứng dụng để trỏ sang Postgres Cluster (host, port, credentials mới). +* Kiểm tra ứng dụng hoạt động bình thường với database vừa migrate. +* Xóa Postgres Single Node cũ trên vDB sau khi đã xác nhận không còn cần thiết.