Hướng dẫn đổi database n8n từ SQLite sang PostgreSQL không mất workflow

Để đổi database n8n từ SQLite sang PostgreSQL, bạn cần sao lưu dữ liệu hiện tại, cấu hình PostgreSQL trong Docker Compose, sau đó chuyển workflow và credential sang database mới. Quá trình này giúp n8n sử dụng PostgreSQL thay cho SQLite mà không cần xây dựng lại toàn bộ quy trình tự động hóa. Cùng Tino theo dõi bài viết dưới đây nhé!

Tại sao nên chuyển database n8n từ SQLite sang PostgreSQL?

PostgreSQL phù hợp hơn khi triển khai n8n lâu dài trên VPS, đặc biệt với hệ thống có nhiều workflow hoạt động thường xuyên hoặc cần mở rộng khả năng xử lý.

Theo mặc định, n8n self-hosted sử dụng SQLite để lưu trữ workflow, thông tin đăng nhập đã mã hóa và lịch sử thực thi. PostgreSQL là lựa chọn thay thế được n8n hỗ trợ chính thức.

Dưới đây là một số khác biệt:

Khi nào nên chuyển sang PostgreSQL?

• VPS chạy nhiều workflow n8n thường xuyên.
• Có nhiều người cùng sử dụng n8n.
• Cần quản lý, sao lưu và khôi phục database chuyên nghiệp hơn.
• Có kế hoạch mở rộng n8n hoặc triển khai queue mode.
• Muốn sử dụng PostgreSQL làm database lâu dài cho hệ thống.

Tuy nhiên, PostgreSQL không mặc định giúp mọi workflow chạy nhanh hơn. Hiệu quả thực tế còn phụ thuộc vào tài nguyên VPS, số lượng tác vụ, cách thiết kế workflow và cấu hình hệ thống.

Cần chuẩn bị gì trước khi chuyển database n8n?

Trước khi thực hiện, bạn cần chuẩn bị:

• VPS Linux đã cài Docker và Docker Compose.
• n8n đang hoạt động với database SQLite.
• Quyền SSH để truy cập và chỉnh sửa cấu hình VPS.
• Quyền truy cập tệp Docker Compose hiện tại.
• Dung lượng trống để lưu bản sao lưu và database PostgreSQL.

Lưu ý: Hướng dẫn dưới đây áp dụng cho n8n self-hosted triển khai bằng Docker Compose, với service mang tên n8n và thư mục dữ liệu được gắn tại /home/node/.n8n.

Nếu đang sử dụng Docker độc lập, npm hoặc một hệ thống quản lý container khác, cần điều chỉnh câu lệnh và cách triển khai cho phù hợp.

Những dữ liệu nào sẽ được chuyển?

Phương pháp trong bài sử dụng CLI của n8n để xuất và nhập workflow, credential.

Vì vậy, hướng dẫn phù hợp nhất với hệ thống nhỏ, ít người dùng và ưu tiên giữ lại các workflow đang sử dụng.

Nếu cần bảo toàn toàn bộ tài khoản, dự án, phân quyền và lịch sử hoạt động, cần đánh giá phương án di chuyển toàn bộ database thay vì chỉ xuất workflow và credential.

Hướng dẫn đổi database n8n từ SQLite sang PostgreSQL

Các bước sau được thực hiện qua Terminal SSH trên VPS Linux. Ví dụ sử dụng Docker Compose và PostgreSQL 17.

Bước 1: Kiểm tra n8n đang chạy trên VPS

Đầu tiên, SSH vào VPS bằng Xshell hoặc phần mềm SSH đang sử dụng. Tiếp theo, di chuyển đến thư mục chứa tệp compose.yaml hoặc docker-compose.yml của n8n (tùy VPS của bạn).

Chạy lệnh:

sudo docker compose ls

Trong ví dụ này, tệp Docker Compose nằm tại:

/opt/n8n/docker-compose.yml

Sau khi tìm được đường dẫn, chuyển đến thư mục tương ứng. Ví dụ:

cd /opt/n8n

Sau đó, kiểm tra các container:

docker compose ps

Nếu n8n đang hoạt động, bạn sẽ thấy service n8n trong danh sách.

Tiếp tục kiểm tra phiên bản n8n:

docker compose exec -T n8n n8n --version

Mở tệp Docker Compose hiện tại:

sudo nano docker-compose.yml

Tại đây kiểm tra phần volumes của service n8n. Ví dụ:

volumes:

  - n8n_data:/home/node/.n8n

Thông thường, SQLite được lưu tại:

/home/node/.n8n/database.sqlite

Đây là thư mục cần giữ nguyên trong suốt quá trình chuyển database, vì còn chứa khóa mã hóa credential và các dữ liệu quan trọng khác.

Sau khi kiểm tra xong, nhấn Ctrl + X để thoát.

Bước 2: Sao lưu và xuất workflow, credential

Trước khi thay đổi database, hãy dừng n8n và tạo bản sao lưu dữ liệu hiện tại. Đối với hệ thống đang xử lý tác vụ quan trọng, hãy chờ các workflow cần thiết hoàn tất và lên lịch bảo trì trước khi dừng.

Chạy:

docker compose stop n8n

Tạo thư mục lưu bản sao trên VPS:

mkdir -p ./backup-n8n

Sao chép thư mục dữ liệu n8n từ container:

docker compose cp n8n:/home/node/.n8n ./backup-n8n/

Kiểm tra thư mục backup-n8n/.n8n để xác nhận đã có bản sao database và tệp cấu hình. Đồng thời, sao lưu tệp Docker Compose, .env và các thư mục dữ liệu ngoài nếu đang sử dụng.

Tiếp theo, xuất toàn bộ workflow bằng CLI:

docker compose run --rm --no-deps n8n export:workflow --backup --output=/home/node/.n8n/migration/workflows/

Xuất credential:

docker compose run --rm --no-deps n8n export:credentials --backup --output=/home/node/.n8n/migration/credentials/

Các tệp JSON được lưu trong thư mục migration thuộc volume dữ liệu của n8n để có thể sử dụng lại sau khi đổi database.

Quan trọng:

• Hai lệnh phải thực hiện thành công trước khi chuyển sang bước tiếp theo.
• Giữ nguyên khóa mã hóa N8N_ENCRYPTION_KEY hoặc khóa trong tệp cấu hình n8n hiện tại.
• Không xóa volume n8n_data.
• Nên sao chép bản backup ra khỏi VPS để đề phòng sự cố máy chủ.

Bước 3: Cấu hình PostgreSQL trong Docker Compose

Sau khi sao lưu, bạn cần bổ sung PostgreSQL vào hệ thống Docker Compose hiện tại.

Thêm thông tin PostgreSQL vào .env

Mở tệp .env trong thư mục Docker Compose và thêm:

POSTGRES_USER=n8n

POSTGRES_DB=n8n

POSTGRES_PASSWORD=THAY_BANG_MAT_KHAU_MANH

Thay giá trị POSTGRES_PASSWORD bằng mật khẩu mạnh do bạn tự tạo. Không sử dụng nguyên mật khẩu mẫu khi triển khai thực tế.

Thêm service PostgreSQL

Mở tệp compose.yaml hoặc docker-compose.yml, sau đó bổ sung service sau vào phần services:

postgres:

    image: postgres:17

    restart: unless-stopped

    environment:

      POSTGRES_USER: ${POSTGRES_USER}

      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

      POSTGRES_DB: ${POSTGRES_DB}

    volumes:

      - postgres_data:/var/lib/postgresql/data

    healthcheck:

      test: ["CMD-SHELL", "pg_isready -U n8n -d n8n"]

      interval: 5s

      timeout: 5s

      retries: 10

Ở cuối tệp Docker Compose, thêm volume mới vào phần volumes hiện có:

volumes:

  n8n_data:

  postgres_data:

Đây là ví dụ dành cho hệ thống đang dùng named volume n8n_data. Nếu tệp hiện tại đã khai báo các volume khác, hãy giữ nguyên và chỉ bổ sung postgres_data.

PostgreSQL sử dụng volume riêng để dữ liệu không bị mất khi container được tạo lại.

Cập nhật cấu hình database cho n8n

Trong service n8n, bổ sung các biến môi trường:

environment:

  DB_TYPE: postgresdb

  DB_POSTGRESDB_HOST: postgres

  DB_POSTGRESDB_PORT: "5432"

  DB_POSTGRESDB_DATABASE: ${POSTGRES_DB}

  DB_POSTGRESDB_USER: ${POSTGRES_USER}

  DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}

Giữ lại các biến môi trường có sẵn như cấu hình tên miền, webhook, múi giờ, encryption key và những thiết lập liên quan khác. Nếu service đang sử dụng dạng danh sách environment, hãy thêm các biến theo cùng định dạng.

Tiếp tục bổ sung PostgreSQL vào phần depends_on của service n8n:

depends_on:

  postgres:

    condition: service_healthy

Nếu đã có depends_on, chỉ bổ sung PostgreSQL và giữ các service phụ thuộc trước đó.

Lưu ý: Những đoạn YAML trên là các phần cần thêm vào cấu hình hiện tại, không phải một tệp Docker Compose hoàn chỉnh để thay thế toàn bộ tệp cũ. Đặc biệt, không thay đổi image n8n, đường dẫn volume cũ hoặc tên Docker Compose project trong cùng lần chuyển database.

Bước 4: Khởi động n8n với PostgreSQL

Sau khi hoàn tất cấu hình, kiểm tra cú pháp Docker Compose:

docker compose config -q

Nếu lệnh không báo lỗi, khởi động PostgreSQL và n8n:

docker compose up -d postgres n8n

Kiểm tra trạng thái:

docker compose ps

Xem log n8n:

docker compose logs --tail=50 n8n

Nếu cấu hình chính xác, n8n sẽ kết nối PostgreSQL và tạo các bảng cần thiết trong database mới.

Vì PostgreSQL chưa chứa tài khoản người dùng từ SQLite, n8n có thể hiển thị màn hình thiết lập tài khoản Owner.

Hãy mở giao diện web n8n và hoàn tất bước tạo Owner trước khi nhập dữ liệu.

Lưu ý: Những workflow cũ chưa xuất hiện ở thời điểm này là điều bình thường. Dữ liệu sẽ được nhập ở bước tiếp theo.

Bước 5: Nhập lại workflow và credential

Sau khi tạo tài khoản Owner, trở lại Terminal SSH và nhập workflow đã sao lưu:

docker compose exec -T n8n n8n import:workflow --separate --input=/home/node/.n8n/migration/workflows/

Tiếp tục nhập credential:

docker compose exec -T n8n n8n import:credentials --separate --input=/home/node/.n8n/migration/credentials/

Nếu cả hai lệnh thực hiện thành công, khởi động lại n8n:

docker compose restart n8n

Truy cập giao diện web và kiểm tra các workflow đã được chuyển sang PostgreSQL.

Sau đó:

1. Mở một workflow quan trọng.
2. Kiểm tra các node và credential đang sử dụng.
3. Chạy thử workflow bằng thao tác thủ công.
4. Kiểm tra kết quả trong phần Executions.
5. Publish lại các workflow cần kích hoạt.

Ở n8n 2.x, các workflow nhập bằng Server CLI mặc định không được kích hoạt. Vì vậy, hãy kiểm tra trạng thái Publish trước khi đưa hệ thống trở lại hoạt động bình thường.

Nếu hệ thống có nhiều người dùng hoặc project, cần kiểm tra quyền sở hữu và sử dụng tùy chọn –userId hoặc –projectId phù hợp khi nhập dữ liệu.

Cách kiểm tra n8n đã chuyển sang PostgreSQL thành công

Sau khi hoàn tất, bạn có thể xác minh bằng hai cách.

Cách 1 – Kiểm tra kết nối PostgreSQL

Chạy lệnh:

docker compose exec -T postgres pg_isready -U n8n -d n8n

Nếu PostgreSQL sẵn sàng nhận kết nối, kết quả sẽ thông báo database đang chấp nhận kết nối.

Tiếp tục kiểm tra danh sách bảng:

docker compose exec -T postgres psql -U n8n -d n8n -c '\dt'

Nếu danh sách bảng được hiển thị, PostgreSQL đã được khởi tạo. Kết hợp kiểm tra này với cấu hình DB_TYPE=postgresdb của service n8n để xác nhận ứng dụng đang sử dụng đúng database.

Cách 2 – Kiểm tra trực tiếp trên n8n

• Truy cập giao diện n8n.
• Kiểm tra danh sách workflow và credential.
• Mở một workflow và chạy thử.
• Xác nhận kết quả thực thi mới được lưu thành công.
• Kiểm tra các workflow có webhook hoặc lịch chạy tự động.

Kết quả mong đợi: n8n sử dụng PostgreSQL, workflow và credential đã nhập hoạt động bình thường, đồng thời không xuất hiện lỗi kết nối hoặc giải mã dữ liệu.

Các lỗi thường gặp và cách khắc phục

Trong quá trình đổi database n8n, một số vấn đề có thể xuất hiện:

Nếu PostgreSQL đã được khởi tạo trước đó, thay đổi POSTGRES_PASSWORD trong .env không tự động thay đổi mật khẩu bên trong database. Trong trường hợp này, cần cập nhật mật khẩu PostgreSQL đúng cách thay vì xóa volume.

Những lưu ý quan trọng sau khi chuyển database

Để đảm bảo n8n hoạt động ổn định, bạn nên lưu ý:

• Giữ bản sao SQLite: Chưa xóa database cũ cho đến khi xác nhận quá trình chuyển đổi thành công.
• Không chạy hai hệ thống cùng xử lý workflow: Tránh kích hoạt đồng thời instance cũ và mới để hạn chế tác vụ trùng lặp.
• Giữ encryption key: Mất khóa mã hóa có thể khiến credential cũ không thể sử dụng.
• Kiểm tra dữ liệu ngoài database: Các tệp nhị phân, custom nodes hoặc dữ liệu lưu trên dịch vụ ngoài cần được xử lý riêng.
• Thiết lập sao lưu PostgreSQL: Sau khi chuyển đổi, nên xây dựng lịch backup database bằng công cụ PostgreSQL phù hợp.
• Không sử dụng docker compose down -v: Tùy chọn -v có thể xóa các named volume của dự án, bao gồm dữ liệu cần bảo toàn.

Có thể chuyển toàn bộ dữ liệu SQLite sang PostgreSQL không?

n8n có cung cấp các lệnh export:entities và import:entities nhằm xuất, nhập nhiều loại dữ liệu database, bao gồm trường hợp chuyển giữa SQLite và PostgreSQL.

Tuy nhiên, phương pháp này yêu cầu kiểm tra kỹ tính tương thích của phiên bản, cấu trúc database và trạng thái migration. Một số phiên bản đã được báo cáo gặp lỗi khác biệt migration ID hoặc thiếu bảng dữ liệu sau khi nhập.

Vì vậy, nếu hệ thống có nhiều người dùng, project, phân quyền hoặc dữ liệu lịch sử quan trọng, bạn nên thử chuyển toàn bộ database trong môi trường riêng trước khi áp dụng trên VPS đang hoạt động.

Có thể quay lại SQLite không?

Có. Nếu chưa xóa database và volume cũ, bạn có thể dừng n8n, khôi phục cấu hình Docker Compose và các biến môi trường SQLite trước đó, rồi khởi động lại với dữ liệu đã sao lưu.

Cần lưu ý rằng dữ liệu mới tạo trên PostgreSQL sau thời điểm chuyển đổi sẽ không tự động xuất hiện trong SQLite khi quay lại.

Kết luận

Đổi database n8n từ SQLite sang PostgreSQL là lựa chọn đáng cân nhắc khi muốn vận hành các workflow tự động hóa lâu dài trên VPS. Phương pháp sử dụng Docker Compose và Server CLI giúp chuyển workflow, credential mà không cần xây dựng lại từ đầu.

Điều quan trọng nhất là sao lưu dữ liệu trước khi thao tác, giữ nguyên encryption key và kiểm tra từng workflow sau khi chuyển đổi. Với hệ thống đang hoạt động thực tế, hãy hoàn tất quá trình kiểm thử trước khi kích hoạt lại các tác vụ tự động.

Những câu hỏi thường gặp