# 常用指令(in mvn)
Liquibase Maven Plugin 的指令都遵循標準的 Maven 格式：`mvn liquibase:<目標 (Goal)>`。
## ✨ Liquibase Maven Plugin 常用指令範例
以下是您在使用 Liquibase 進行資料庫版本控制時最常用到的幾個指令：
| 目標 (Goal) | 指令格式 | 作用說明 |
| :--- | :--- | :--- |
| **`update`** | `mvn liquibase:update` | 🚀 **執行資料庫更新**。執行 Changelog 檔案中所有尚未被執行的 `changeset`，將資料庫更新到最新狀態。 |
| **`updateSQL`** | `mvn liquibase:updateSQL` | 📄 **生成更新 SQL 腳本**。生成執行 `update` 時所需要的所有 SQL 腳本，但**不實際執行**到資料庫，用於審核。 |
| **`rollback`** | `mvn liquibase:rollback` | 🔙 **回滾最近 N 個 Changeset**。回滾最近執行過的指定數量 (`rollbackCount`) 的變更。 |
| **`tag`** | `mvn liquibase:tag` | 🏷️ **標記資料庫狀態**。在 `DATABASECHANGELOG` 表中寫入一個標籤 (Tag)，用於標記當前的資料庫狀態，方便後續回滾。 |
| **`status`** | `mvn liquibase:status` | 💡 **查看待執行變更**。列印出 Changelog 中還有哪些 `changeset` 尚未被應用到資料庫。 |
-----
## 🛠️ 詳細指令與用法
### 1\. 執行資料庫更新 (Update)
這是最常用的指令，將所有未執行的變更集套用到資料庫。
* **指令：**
```bash
mvn liquibase:update
```
### 2\. 生成更新 SQL 腳本 (UpdateSQL)
在生產環境部署前，通常會先用這個指令生成 SQL 腳本，手動審核後再執行。
* **指令：**
```bash
mvn liquibase:updateSQL
```
* *結果:* SQL 腳本通常會輸出到 `target/liquibase/migrate.sql` 或控制台，具體取決於您的配置。
### 3\. 回滾變更 (Rollback)
回滾是將資料庫狀態恢復到先前某個時間點、某個標籤或某個變更集之前。
#### 範例 A: 回滾最近 N 個變更
回滾最近 3 個已執行的 `changeset`。
* **指令：**
```bash
mvn liquibase:rollback -Dliquibase.rollbackCount=3
```
#### 範例 B: 回滾到指定標籤
回滾所有在特定標籤 (`version_1.0.0`) 之後執行的變更。
* **指令：**
```bash
mvn liquibase:rollback -Dliquibase.rollbackTag=version_1.0.0
```
### 4\. 標記資料庫狀態 (Tag)
在成功部署到某個版本後，建議打上標籤。
* **指令：**
```bash
mvn liquibase:tag -Dliquibase.tag=v2.0.0_release
```
### 5\. 查看待執行的變更 (Status)
檢查本地 Changelog 中有多少變更集還沒有被應用。
* **指令：**
```bash
mvn liquibase:status
```
### 6\. 生成變更集差異報告/檔案 (Diff)
比較兩個資料庫 (源資料庫和參考資料庫) 之間的差異。
* **指令：**
```bash
# 僅生成差異報告（輸出到控制台）
mvn liquibase:diff
# 生成差異並輸出到新的 Changelog 檔案
mvn liquibase:diffChangeLog
```
* *注意:* `diff` 相關指令需要您在 Maven 配置中定義 `referenceUrl`、`referenceUsername` 等參考資料庫的連線資訊。
-----
## ⚠️ 前提：Maven 配置
請確保您的 `pom.xml` 已經正確配置了 `liquibase-maven-plugin`，並且提供了資料庫連線資訊，例如：
```xml
<plugin>
<groupId>org.liquibase</groupId>
<artifactId>liquibase-maven-plugin</artifactId>
<version>...</version>
<configuration>
<propertyFile>src/main/resources/liquibase.properties</propertyFile>
</configuration>
</plugin>
```