本文記錄如何在 Docker 容器中執行 MariaDB (12.1.1) 的 SQL 匯入作業，並說明常見錯誤與修正方式，方便日後備查。
一、背景說明
在維運環境中，我們常會在 Docker 容器中部署 MariaDB 資料庫，並需要將備份的 .sql 檔或 .sql.gz 壓縮檔匯入。
以本次環境為例：
| 項目 | 設定值 |
|---|---|
| 容器名稱 | blognufacedb |
| MariaDB 版本 | 12.1.1-MariaDB |
| 帳號 | nuface |
| 密碼 | abcd123 |
| 資料庫名稱 | nuface |
| 匯入檔案 | nuface_2025-09-16.sql |
二、原始執行指令
docker exec -i blognufacedb mariadb -u nuface -p 'abcd123' --default-character-set=utf8mb4 nuface < nuface_2025-09-16.sql
執行後出現以下訊息：
mariadb from 12.1.1-MariaDB, client 15.2 for Linux (x86_64) using EditLine wrapper
Copyright (c) 2000, 2018, Oracle...
Usage: mariadb [OPTIONS] [database]
...
MariaDB 並未執行匯入，而是列出整份使用說明。
三、問題原因
造成問題的主因是：
-p後面多了一個空白
MariaDB 會將'abcd123'視為「資料庫名稱」而非密碼，導致參數順序錯亂，程式直接輸出說明文件。
四、正確匯入方式
✅ 方法 1：-p'密碼'（不能有空白）
docker exec -i blognufacedb \
mariadb -u nuface -p'abcd123' --default-character-set=utf8mb4 nuface \
< nuface_2025-09-16.sql
✅ 方法 2：使用 --password=密碼
docker exec -i blognufacedb \
mariadb -u nuface --password='abcd123' --default-character-set=utf8mb4 nuface \
< nuface_2025-09-16.sql
✅ 方法 3：使用環境變數（推薦）
這方式可避免密碼出現在指令列（提高安全性）：
docker exec -i -e MYSQL_PWD='abcd123' \
blognufacedb mariadb -u nuface --default-character-set=utf8mb4 nuface \
< nuface_2025-09-16.sql
五、匯入壓縮檔（.sql.gz）
gunzip -c nuface_2025-09-16.sql.gz | \
docker exec -i -e MYSQL_PWD='abcd123' \
blognufacedb mariadb -u nuface --default-character-set=utf8mb4 nuface
六、進階選項（大檔案或特殊環境）
若要匯入大型資料庫，可加上：
--max-allowed-packet=512M \
--init-command="SET time_zone='+08:00'; SET FOREIGN_KEY_CHECKS=0;"
範例如下：
docker exec -i -e MYSQL_PWD='abcd123' \
blognufacedb mariadb -u nuface --default-character-set=utf8mb4 nuface \
--max-allowed-packet=512M \
--init-command="SET time_zone='+08:00'; SET FOREIGN_KEY_CHECKS=0;" \
< nuface_2025-09-16.sql
七、小提醒
- 若匯出檔中已包含
CREATE DATABASE/USE nuface;，可省略命令中的資料庫名稱。 - 若出現
ERROR 1227 (42000): Access denied，通常是權限不足（例如有DEFINER的 View 或 Routine），建議使用具備CREATE ROUTINE或SUPER權限的帳號。 - 匯入前可檢查是否連線成功：
docker exec -it blognufacedb mariadb -u nuface -p'abcd123' -e "SELECT VERSION();"
八、總結
在 Docker 容器中匯入 MariaDB 資料時，常見的問題多半是參數格式錯誤。
記住以下要點即可快速完成匯入：
| 重點 | 說明 |
|---|---|
-p 後不能有空白 | 否則會被誤判為資料庫名稱 |
可用 MYSQL_PWD 避免密碼外洩 | 更安全的做法 |
| 匯入壓縮檔可直接用 `gunzip -c | docker exec -i` |
大型資料庫建議加上 --max-allowed-packet 與 --init-command | 提高成功率 |
📌 延伸閱讀