diff --git a/AGENTS.md b/AGENTS.md
index ad7ccba..cd81e74 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -115,6 +115,8 @@ secrets config show   # 查看当前配置（密码脱敏）
 secrets config path   # 打印配置文件路径
 ```
 
+`set-db` 会先验证连接可用，成功后才写入配置文件；连接失败时提示 "Database connection failed" 且不修改配置。
+
 配置文件：`~/.config/secrets/config.toml`，权限 0600。`--db-url` 参数可一次性覆盖。
 
 ## 主密钥与加密
@@ -406,7 +408,7 @@ secrets run -n refining --kind service --name gitea -- printenv
 ### config — 配置管理（无需主密钥）
 
 ```bash
-# 设置数据库连接（每台设备执行一次，之后永久生效）
+# 设置数据库连接（每台设备执行一次，之后永久生效；先验证连接可用再写入）
 secrets config set-db "postgres://postgres:<password>@<host>:<port>/secrets"
 
 # 查看当前配置（密码脱敏）
diff --git a/README.md b/README.md
index 6f5c956..77654f5 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ cargo build --release
 ## 首次使用（每台设备各执行一次）
 
 ```bash
-# 1. 配置数据库连接
+# 1. 配置数据库连接（会先验证连接可用再写入）
 secrets config set-db "postgres://postgres:<password>@<host>:<port>/secrets"
 
 # 2. 初始化主密钥（提示输入主密码，派生后存入 OS 钥匙串）
@@ -131,7 +131,7 @@ secrets delete -n refining --kind service --name legacy-mqtt
 secrets init              # 主密钥初始化（每台设备一次，主密码派生后存钥匙串）
 
 # ── config ───────────────────────────────────────────────────────────────────
-secrets config set-db "postgres://postgres:<password>@<host>:<port>/secrets"
+secrets config set-db "postgres://postgres:<password>@<host>:<port>/secrets"   # 先验证再写入
 secrets config show    # 密码脱敏展示
 secrets config path    # 打印配置文件路径
 
diff --git a/src/commands/config.rs b/src/commands/config.rs
index 5c02ee6..48e0551 100644
--- a/src/commands/config.rs
+++ b/src/commands/config.rs
@@ -4,6 +4,12 @@ use anyhow::Result;
 pub async fn run(action: crate::ConfigAction) -> Result<()> {
     match action {
         crate::ConfigAction::SetDb { url } => {
+            // Verify connection before writing config
+            let pool = crate::db::create_pool(&url)
+                .await
+                .map_err(|e| anyhow::anyhow!("Database connection failed: {}", e))?;
+            drop(pool);
+
             let cfg = Config {
                 database_url: Some(url.clone()),
             };