@carllee1983/dbcli 0.2.0-beta → 0.3.1-beta

package/README.md

@@ -36,14 +36,20 @@ All messages, help text, error messages, and command output respond to the langu
 #### Global Installation (Recommended)
 
 ```bash
-npm install -g dbcli
+npm install -g @carllee1983/dbcli
 ```
 
 #### Zero-Install (No Installation Needed)
 
 ```bash
-npx dbcli init
-npx dbcli query "SELECT * FROM users"
+npx @carllee1983/dbcli init
+npx @carllee1983/dbcli query "SELECT * FROM users"
+```
+
+#### Update
+
+```bash
+npm update -g @carllee1983/dbcli
 ```
 
 #### Development Installation

package/README.zh-TW.md

@@ -17,13 +17,23 @@ dbcli 是一個統一的資料庫 CLI 工具，能讓 AI 代理（Claude Code、
 使用 Bun 安裝：
 
 ```bash
-bun add -D dbcli
+bun add -D @carllee1983/dbcli
 ```
 
 或使用 npm：
 
 ```bash
-npm install --save-dev dbcli
+npm install --save-dev @carllee1983/dbcli
+```
+
+### 更新
+
+```bash
+# Bun
+bun update @carllee1983/dbcli
+
+# npm
+npm update --save-dev @carllee1983/dbcli
 ```
 
 ### 初始化

package/dist/cli.mjs

@@ -42686,6 +42686,60 @@ var require_table = __commonJS((exports, module) => {
   module.exports = Table;
 });
 
+// src/core/size-category.ts
+var exports_size_category = {};
+__export(exports_size_category, {
+  getSizeCategory: () => getSizeCategory
+});
+function getSizeCategory(estimatedRowCount) {
+  const count = estimatedRowCount ?? 0;
+  for (const [threshold, category] of THRESHOLDS) {
+    if (count >= threshold)
+      return category;
+  }
+  return "small";
+}
+var THRESHOLDS;
+var init_size_category = __esm(() => {
+  THRESHOLDS = [
+    [1e6, "huge"],
+    [1e5, "large"],
+    [1e4, "medium"]
+  ];
+});
+
+// src/commands/query-size-guard.ts
+var exports_query_size_guard = {};
+__export(exports_query_size_guard, {
+  shouldBlockQuery: () => shouldBlockQuery
+});
+function shouldBlockQuery(sql, tableSizeInfo) {
+  if (!tableSizeInfo) {
+    return { blocked: false };
+  }
+  const category = getSizeCategory(tableSizeInfo.estimatedRowCount);
+  if (category !== "huge") {
+    return { blocked: false, sizeCategory: category };
+  }
+  const normalizedSql = sql.trim().toUpperCase();
+  if (!normalizedSql.startsWith("SELECT")) {
+    return { blocked: false, sizeCategory: category };
+  }
+  const hasWhere = /\bWHERE\b/i.test(sql);
+  const hasLimit = /\bLIMIT\b/i.test(sql);
+  if (hasWhere || hasLimit) {
+    return { blocked: false, sizeCategory: category };
+  }
+  return {
+    blocked: true,
+    sizeCategory: category,
+    reason: `Table has ~${tableSizeInfo.estimatedRowCount.toLocaleString()} rows (huge). Add WHERE or LIMIT clause, or use --no-limit to override.`
+  };
+}
+var init_query_size_guard = __esm(() => {
+  init_size_category();
+});
+
 // node_modules/commander/esm.mjs
 var import__ = __toESM(require_commander(), 1);
 var {
@@ -42704,7 +42758,7 @@ var {
 // package.json
 var package_default = {
   name: "@carllee1983/dbcli",
-  version: "0.2.0-beta",
+  version: "0.3.1-beta",
   description: "Database CLI for AI agents",
   type: "module",
   publishConfig: {
@@ -47358,18 +47412,28 @@ class PostgreSQLAdapter {
     try {
       const query = `
         SELECT
-          schemaname,
-          relname as table_name,
-          n_live_tup as row_count
-        FROM pg_stat_user_tables
-        ORDER BY relname
+          c.relname as table_name,
+          c.reltuples::bigint as estimated_rows,
+          CASE c.relkind
+            WHEN 'r' THEN 'table'
+            WHEN 'v' THEN 'view'
+            WHEN 'm' THEN 'view'
+            ELSE 'table'
+          END as table_type
+        FROM pg_class c
+        JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE n.nspname = 'public'
+          AND c.relkind IN ('r', 'v', 'm')
+        ORDER BY c.relname
       `;
       const results = await this.execute(query);
       return results.map((row) => ({
         name: row.table_name,
         columns: [],
-        rowCount: row.row_count || 0,
-        engine: "PostgreSQL"
+        rowCount: Math.max(0, row.estimated_rows || 0),
+        engine: "PostgreSQL",
+        estimatedRowCount: Math.max(0, row.estimated_rows || 0),
+        tableType: row.table_type
       }));
     } catch (error) {
       throw mapError(error, "postgresql", this.options);
@@ -47391,19 +47455,40 @@ class PostgreSQLAdapter {
               SELECT 1 FROM information_schema.table_constraints tc
               JOIN information_schema.key_column_usage kcu
                 ON tc.constraint_name = kcu.constraint_name
-              WHERE tc.table_name = t.table_name
+              WHERE tc.table_name = $1
+                AND tc.table_schema = 'public'
                 AND tc.constraint_type = 'PRIMARY KEY'
                 AND kcu.column_name = c.column_name
             )
-          ) as is_primary_key
+          ) as is_primary_key,
+          (c.column_default LIKE 'nextval%') as auto_increment,
+          pgd.description as comment
         FROM information_schema.columns c
-        JOIN information_schema.tables t
-          ON c.table_name = t.table_name
+        LEFT JOIN pg_catalog.pg_statio_all_tables st
+          ON st.schemaname = c.table_schema AND st.relname = c.table_name
+        LEFT JOIN pg_catalog.pg_description pgd
+          ON pgd.objoid = st.relid AND pgd.objsubid = c.ordinal_position
         WHERE c.table_name = $1
-          AND t.table_schema = 'public'
+          AND c.table_schema = 'public'
         ORDER BY c.ordinal_position
       `;
       const columns = await this.execute(columnQuery, [tableName]);
+      const enumQuery = `
+        SELECT
+          c.column_name as name,
+          array_agg(e.enumlabel ORDER BY e.enumsortorder) as enum_values
+        FROM information_schema.columns c
+        JOIN pg_type t ON t.typname = c.udt_name
+        JOIN pg_enum e ON e.enumtypid = t.oid
+        WHERE c.table_name = $1
+          AND c.table_schema = 'public'
+        GROUP BY c.column_name
+      `;
+      const enumResults = await this.execute(enumQuery, [tableName]);
+      const enumMap = new Map;
+      for (const row of enumResults) {
+        enumMap.set(row.name, Array.isArray(row.enum_values) ? row.enum_values : []);
+      }
       const fkQuery = `
         SELECT
           tc.constraint_name as name,
@@ -47425,6 +47510,28 @@ class PostgreSQLAdapter {
           fkMap.set(fk.columns[0], { table: fk.ref_table, column: fk.ref_columns[0] });
         }
       }
+      const indexQuery = `
+        SELECT
+          i.relname as name,
+          array_agg(a.attname ORDER BY array_position(ix.indkey, a.attnum)) as columns,
+          ix.indisunique as is_unique
+        FROM pg_index ix
+        JOIN pg_class t ON t.oid = ix.indrelid
+        JOIN pg_class i ON i.oid = ix.indexrelid
+        JOIN pg_namespace n ON n.oid = t.relnamespace
+        JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(ix.indkey)
+        WHERE t.relname = $1
+          AND n.nspname = 'public'
+          AND NOT ix.indisprimary
+        GROUP BY i.relname, ix.indisunique
+      `;
+      const indexResults = await this.execute(indexQuery, [tableName]);
+      const estimateQuery = `
+        SELECT reltuples::bigint as estimated_rows
+        FROM pg_class
+        WHERE relname = $1
+      `;
+      const estimateResults = await this.execute(estimateQuery, [tableName]);
       const pkQuery = `
         SELECT array_agg(a.attname) as columns
         FROM (
@@ -47452,12 +47559,21 @@ class PostgreSQLAdapter {
           nullable: col.nullable,
           default: col.default_value || undefined,
           primaryKey: col.is_primary_key,
-          foreignKey: fkMap.get(col.name)
+          foreignKey: fkMap.get(col.name),
+          autoIncrement: col.auto_increment,
+          comment: col.comment || null,
+          enumValues: enumMap.get(col.name)
         })),
         rowCount: countResult[0]?.count || 0,
         engine: "PostgreSQL",
         primaryKey: primaryKeyArray,
-        foreignKeys: safeForeignKeys
+        foreignKeys: safeForeignKeys,
+        indexes: indexResults.map((idx) => ({
+          name: idx.name,
+          columns: Array.isArray(idx.columns) ? idx.columns : [],
+          unique: idx.is_unique
+        })),
+        estimatedRowCount: Math.max(0, estimateResults[0]?.estimated_rows || 0)
       };
       return schema;
     } catch (error) {
@@ -47468,6 +47584,13 @@ class PostgreSQLAdapter {
 
 // src/adapters/mysql-adapter.ts
 var import_promise = __toESM(require_promise(), 1);
+function parseEnumValues(columnType) {
+  const match = columnType.match(/^enum\((.+)\)$/i);
+  if (!match)
+    return;
+  return match[1].split(",").map((v) => v.trim().replace(/^'|'$/g, ""));
+}
+
 class MySQLAdapter {
   db = null;
   options;
@@ -47533,12 +47656,13 @@ class MySQLAdapter {
           t.TABLE_NAME as table_name,
           t.TABLE_ROWS as row_count,
           t.ENGINE as engine,
+          t.TABLE_TYPE as table_type,
           COUNT(c.COLUMN_NAME) as column_count
         FROM information_schema.TABLES t
         LEFT JOIN information_schema.COLUMNS c
           ON t.TABLE_SCHEMA = c.TABLE_SCHEMA AND t.TABLE_NAME = c.TABLE_NAME
         WHERE t.TABLE_SCHEMA = DATABASE()
-        GROUP BY t.TABLE_NAME, t.TABLE_ROWS, t.ENGINE
+        GROUP BY t.TABLE_NAME, t.TABLE_ROWS, t.ENGINE, t.TABLE_TYPE
         ORDER BY t.TABLE_NAME
       `;
       const results = await this.execute(query);
@@ -47546,7 +47670,9 @@ class MySQLAdapter {
         name: row.table_name,
         columns: Array(row.column_count).fill(null),
         rowCount: row.row_count || 0,
-        engine: row.engine
+        engine: row.engine,
+        estimatedRowCount: row.row_count || 0,
+        tableType: row.table_type === "VIEW" ? "view" : "table"
       }));
     } catch (error) {
       throw mapError(error, this.system, this.options);
@@ -47563,7 +47689,9 @@ class MySQLAdapter {
           COLUMN_TYPE as type,
           IS_NULLABLE = 'YES' as nullable,
           COLUMN_DEFAULT as default_value,
-          COLUMN_KEY = 'PRI' as is_primary_key
+          COLUMN_KEY = 'PRI' as is_primary_key,
+          EXTRA LIKE '%auto_increment%' as auto_increment,
+          COLUMN_COMMENT as comment
         FROM information_schema.COLUMNS
         WHERE TABLE_SCHEMA = DATABASE()
           AND TABLE_NAME = ?
@@ -47592,6 +47720,18 @@ class MySQLAdapter {
         }
       }
       const primaryKeyColumns = columns.filter((col) => col.is_primary_key).map((col) => col.name);
+      const indexQuery = `
+        SELECT
+          INDEX_NAME as name,
+          GROUP_CONCAT(COLUMN_NAME ORDER BY SEQ_IN_INDEX) as columns,
+          NOT NON_UNIQUE as is_unique
+        FROM information_schema.STATISTICS
+        WHERE TABLE_SCHEMA = DATABASE()
+          AND TABLE_NAME = ?
+          AND INDEX_NAME != 'PRIMARY'
+        GROUP BY INDEX_NAME, NON_UNIQUE
+      `;
+      const indexResults = await this.execute(indexQuery, [tableName]);
       const countResult = await this.execute(`SELECT COUNT(*) as count FROM \`${tableName}\``);
       const tableQuery = `
         SELECT ENGINE as engine
@@ -47599,6 +47739,12 @@ class MySQLAdapter {
         WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?
       `;
       const tableResults = await this.execute(tableQuery, [tableName]);
+      const estimateQuery = `
+        SELECT TABLE_ROWS as estimated_rows
+        FROM information_schema.TABLES
+        WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?
+      `;
+      const estimateResults = await this.execute(estimateQuery, [tableName]);
       const schema = {
         name: tableName,
         columns: columns.map((col) => ({
@@ -47607,7 +47753,10 @@ class MySQLAdapter {
           nullable: col.nullable,
           default: col.default_value || undefined,
           primaryKey: col.is_primary_key,
-          foreignKey: fkMap.get(col.name)
+          foreignKey: fkMap.get(col.name),
+          autoIncrement: col.auto_increment,
+          comment: col.comment || null,
+          enumValues: parseEnumValues(col.type)
         })),
         rowCount: countResult[0]?.count || 0,
         engine: tableResults[0]?.engine || "MySQL",
@@ -47617,7 +47766,13 @@ class MySQLAdapter {
           columns: fk.columns.split(",").map((c) => c.trim()),
           refTable: fk.ref_table,
           refColumns: fk.ref_columns.split(",").map((c) => c.trim())
-        }))
+        })),
+        indexes: indexResults.map((idx) => ({
+          name: idx.name,
+          columns: idx.columns.split(",").map((c) => c.trim()),
+          unique: idx.is_unique
+        })),
+        estimatedRowCount: estimateResults[0]?.estimated_rows || 0
       };
       return schema;
     } catch (error) {
@@ -47890,6 +48045,8 @@ class TableListFormatter {
   }
 }
 // src/formatters/json-formatter.ts
+init_size_category();
+
 class JSONFormatter {
   format(data, options) {
     const spacing = options?.compact ? undefined : 2;
@@ -47900,11 +48057,16 @@ class JSONFormatter {
 class TableSchemaJSONFormatter {
   format(table, options) {
     const spacing = options?.compact ? undefined : 2;
+    const rowCount = table.estimatedRowCount ?? table.rowCount;
     const output = {
       name: table.name,
+      estimatedRowCount: rowCount ?? null,
+      sizeCategory: rowCount !== undefined && rowCount !== null ? getSizeCategory(rowCount) : null,
+      tableType: table.tableType ?? "table",
       columns: table.columns,
       primaryKey: table.primaryKey || [],
       foreignKeys: table.foreignKeys || [],
+      indexes: table.indexes || [],
       metadata: {
         rowCount: table.rowCount,
         engine: table.engine
@@ -48055,8 +48217,11 @@ async function listAction(options) {
         const formatter = new TableListFormatter;
         console.log(formatter.format(tables));
       }
+      const tableCount = tables.filter((t2) => t2.tableType !== "view").length;
+      const viewCount = tables.filter((t2) => t2.tableType === "view").length;
+      const viewSuffix = viewCount > 0 ? ` (${viewCount} views)` : "";
       console.log(`
-\u2713 Found ${tables.length} tables`);
+\u2713 Found ${tableCount} tables${viewSuffix}`);
     } finally {
       await adapter.disconnect();
     }
@@ -48197,6 +48362,19 @@ Row count: ~${schema.rowCount.toLocaleString()}`);
     if (schema.engine) {
       console.log(`Engine: ${schema.engine}`);
     }
+    if (schema.estimatedRowCount !== undefined) {
+      const { getSizeCategory: getSizeCategory2 } = await Promise.resolve().then(() => (init_size_category(), exports_size_category));
+      const category = getSizeCategory2(schema.estimatedRowCount);
+      console.log(`Estimated rows: ~${schema.estimatedRowCount.toLocaleString()} (${category})`);
+    }
+    if (schema.indexes && schema.indexes.length > 0) {
+      console.log(`
+Indexes:`);
+      schema.indexes.forEach((idx) => {
+        const uniqueTag = idx.unique ? " [UNIQUE]" : "";
+        console.log(`   ${idx.name}: (${idx.columns.join(", ")})${uniqueTag}`);
+      });
+    }
   }
 }
 async function handleSchemaRefresh(adapter, config, options) {
@@ -48260,7 +48438,10 @@ async function handleSchemaReset(adapter, config, options) {
       rowCount: fullSchema.rowCount,
       engine: fullSchema.engine,
       primaryKey: fullSchema.primaryKey || [],
-      foreignKeys: fullSchema.foreignKeys || []
+      foreignKeys: fullSchema.foreignKeys || [],
+      indexes: fullSchema.indexes || [],
+      estimatedRowCount: fullSchema.estimatedRowCount || 0,
+      tableType: fullSchema.tableType || "table"
     };
     processed++;
     if (processed % 10 === 0 || processed === tables.length) {
@@ -48299,7 +48480,10 @@ async function handleFullDatabaseScan(adapter, config, options) {
       rowCount: fullSchema.rowCount,
       engine: fullSchema.engine,
       primaryKey: fullSchema.primaryKey || [],
-      foreignKeys: fullSchema.foreignKeys || []
+      foreignKeys: fullSchema.foreignKeys || [],
+      indexes: fullSchema.indexes || [],
+      estimatedRowCount: fullSchema.estimatedRowCount || 0,
+      tableType: fullSchema.tableType || "table"
     };
     processed++;
     if (processed % 10 === 0 || processed === tables.length) {
@@ -48980,6 +49164,18 @@ async function queryCommand(sql, options) {
     if (!config.connection) {
       throw new Error('Run "dbcli init" first');
     }
+    const mainTable = extractMainTable(sql);
+    if (mainTable && config.schema && !options.noLimit) {
+      const tableSchema = config.schema[mainTable];
+      if (tableSchema) {
+        const { shouldBlockQuery: shouldBlockQuery2 } = await Promise.resolve().then(() => (init_query_size_guard(), exports_query_size_guard));
+        const guard = shouldBlockQuery2(sql, tableSchema);
+        if (guard.blocked) {
+          console.error(`\u26A0 ${guard.reason}`);
+          process.exit(1);
+        }
+      }
+    }
     const adapter = AdapterFactory.createAdapter(config.connection);
     await adapter.connect();
     try {
@@ -49018,6 +49214,10 @@ async function queryCommand(sql, options) {
     process.exit(1);
   }
 }
+function extractMainTable(sql) {
+  const match = sql.match(/\bFROM\s+[`"']?(\w+)[`"']?/i);
+  return match ? match[1] : null;
+}
 
 // src/core/data-executor.ts
 class DataExecutor {
@@ -49697,152 +49897,14 @@ async function exportCommand(sql, options) {
 // src/commands/skill.ts
 import * as path from "path";
 import { homedir } from "os";
-
-// src/core/skill-generator.ts
-class SkillGenerator {
-  options;
-  constructor(options) {
-    this.options = options;
-  }
-  generateSkillMarkdown() {
-    const commands = this.collectCommands();
-    const filtered = this.filterByPermission(commands);
-    return this.renderSkillMarkdown(filtered);
-  }
-  collectCommands() {
-    const commands = [];
-    this.options.program.commands.forEach((cmd) => {
-      const skillCmd = {
-        name: cmd.name(),
-        description: cmd.description() || "No description",
-        args: cmd.args || [],
-        options: cmd.options.map((opt) => ({
-          flag: opt.flags,
-          description: opt.description || "No description",
-          required: opt.required ?? false
-        })),
-        permissionLevel: this.detectPermissionLevel(cmd.name()),
-        examples: this.generateExamples(cmd.name())
-      };
-      commands.push(skillCmd);
-    });
-    return commands;
-  }
-  detectPermissionLevel(commandName) {
-    if (commandName === "delete")
-      return "admin";
-    if (["insert", "update"].includes(commandName))
-      return "read-write";
-    return "query-only";
-  }
-  filterByPermission(commands) {
-    const permLevel = this.options.permissionLevel;
-    return commands.filter((cmd) => {
-      if (permLevel === "query-only") {
-        return !["insert", "update", "delete"].includes(cmd.name);
-      }
-      if (permLevel === "read-write") {
-        return cmd.name !== "delete";
-      }
-      return true;
-    });
-  }
-  generateExamples(commandName) {
-    const examples = {
-      init: ["dbcli init"],
-      list: ["dbcli list", "dbcli list --format json"],
-      schema: ["dbcli schema users", "dbcli schema users --format json"],
-      query: [
-        'dbcli query "SELECT * FROM users LIMIT 10"',
-        'dbcli query "SELECT id, email FROM users" --format json'
-      ],
-      insert: [`dbcli insert users --data '{"name":"Alice","email":"alice@example.com"}'`],
-      update: [`dbcli update users --where "id=1" --set '{"name":"Bob"}'`],
-      delete: ['dbcli delete users --where "id=1" --force'],
-      export: [
-        'dbcli export "SELECT * FROM users" --format csv --output users.csv',
-        `dbcli export "SELECT * FROM users" --format json | jq '.[]'`
-      ]
-    };
-    return examples[commandName] || [`dbcli ${commandName}`];
-  }
-  renderSkillMarkdown(commands) {
-    const frontmatter = `---
-name: dbcli
-description: Database CLI for AI agents. Use to query, modify, and manage database schemas with permission-based access control.
-user-invocable: true
-allowed-tools: Bash(dbcli *)
----`;
-    const header = `# dbcli Skill Documentation
-
-Database CLI for AI agents with permission-based access control.
-
-## Commands`;
-    const commandDocs = commands.map((cmd) => this.renderCommandSection(cmd)).join(`
-
-`);
-    const footer = `## Permission Levels
-
-dbcli enforces permission-based access control:
-
-- **Query-only**: Execute SELECT queries, list tables, view schemas, export data
-- **Read-Write**: Query-only + INSERT and UPDATE operations
-- **Admin**: Read-Write + DELETE operations
-
-Your current permission level is set in \`.dbcli\` config.
-
-## Tips for AI Agents
-
-1. **Schema introspection first**: Start with \`dbcli schema <table>\` to understand structure
-2. **Test with --dry-run**: Use \`--dry-run\` to preview SQL before executing
-3. **Use --format json**: AI parsing of JSON is more reliable than tables
-4. **Check permission level**: Review \`.dbcli\` to understand what operations are allowed`;
-    return `${frontmatter}
-
-${header}
-
-${commandDocs}
-
-${footer}`;
-  }
-  renderCommandSection(cmd) {
-    const argsStr = cmd.args.length > 0 ? " " + cmd.args.join(" ") : "";
-    const optionsStr = cmd.options.length > 0 ? cmd.options.map((opt) => `- \`${opt.flag}\`: ${opt.description}`).join(`
-`) : "(No options)";
-    const examplesStr = cmd.examples.map((ex) => `\`\`\`bash
-${ex}
-\`\`\``).join(`
-
-`);
-    return `### ${cmd.name}
-
-${cmd.description}
-
-**Usage:** \`dbcli ${cmd.name}${argsStr}\`
-
-**Options:**
-${optionsStr}
-
-**Permission required:** ${cmd.permissionLevel} or higher
-
-**Example:**
-${examplesStr}`;
-  }
-}
-
-// src/commands/skill.ts
-async function skillCommand(program2, options) {
+var SKILL_SOURCE_PATH = path.resolve(import.meta.dir, "../../assets/SKILL.md");
+async function skillCommand(_program, options) {
   try {
-    const config = await configModule.read(".dbcli");
-    if (!config.connection) {
-      throw new Error('Run "dbcli init" to initialize project');
+    const skillFile = Bun.file(SKILL_SOURCE_PATH);
+    if (!await skillFile.exists()) {
+      throw new Error(`Skill source not found: ${SKILL_SOURCE_PATH}`);
     }
-    const skillGen = new SkillGenerator({
-      program: program2,
-      config,
-      permissionLevel: config.permission
-    });
-    const skillMarkdown = skillGen.generateSkillMarkdown();
+    const skillMarkdown = await skillFile.text();
     if (options.output) {
       await Bun.file(options.output).write(skillMarkdown);
       console.error(`Skill written to ${options.output}`);
@@ -50067,6 +50129,428 @@ columnCmd.command("remove <table.column>").description("Remove column from black
   }
 });
 
+// src/core/health-checker.ts
+init_size_category();
+
+class HealthChecker {
+  adapter;
+  constructor(adapter) {
+    this.adapter = adapter;
+  }
+  async check(schema, options = {}) {
+    const checks = options.checks || ["nulls", "duplicates", "orphans", "emptyStrings", "rowCount"];
+    const sample2 = options.sample || 1e4;
+    const blacklisted = options.blacklistedColumns || new Set;
+    const visibleColumns = schema.columns.filter((c) => !blacklisted.has(`${schema.name}.${c.name}`));
+    const countResult = await this.adapter.execute(`SELECT COUNT(*) as count FROM \`${schema.name}\``);
+    const rowCount = countResult[0]?.count || 0;
+    const nulls = checks.includes("nulls") ? await this.checkNulls(schema.name, visibleColumns, rowCount, sample2) : [];
+    const orphans = checks.includes("orphans") ? await this.checkOrphans(schema.name, visibleColumns) : [];
+    const duplicates = checks.includes("duplicates") ? await this.checkDuplicates(schema.name, schema.indexes || []) : [];
+    const emptyStrings = checks.includes("emptyStrings") ? await this.checkEmptyStrings(schema.name, visibleColumns) : [];
+    const issues = orphans.length + duplicates.length;
+    const warnings = nulls.filter((n) => n.nullPercent > 50).length + emptyStrings.length;
+    const clean = Math.max(0, checks.length - (issues > 0 ? 1 : 0) - (warnings > 0 ? 1 : 0));
+    return {
+      table: schema.name,
+      rowCount,
+      sizeCategory: getSizeCategory(schema.estimatedRowCount),
+      checks: { nulls, orphans, duplicates, emptyStrings },
+      summary: { issues, warnings, clean },
+      skippedColumns: blacklisted.size > 0 ? Array.from(blacklisted).filter((c) => c.startsWith(`${schema.name}.`)) : undefined
+    };
+  }
+  async checkNulls(tableName, columns, totalRows, sample2) {
+    if (totalRows === 0)
+      return [];
+    const nullableColumns = columns.filter((c) => c.nullable);
+    const results = [];
+    for (const col of nullableColumns) {
+      try {
+        const useSample = totalRows > sample2;
+        const sql = useSample ? `SELECT COUNT(*) - COUNT(\`${col.name}\`) as null_count FROM (SELECT \`${col.name}\` FROM \`${tableName}\` LIMIT ${sample2}) sub` : `SELECT COUNT(*) - COUNT(\`${col.name}\`) as null_count FROM \`${tableName}\``;
+        const result = await this.adapter.execute(sql);
+        const nullCount = result[0]?.null_count || 0;
+        if (nullCount > 0) {
+          const sampleSize = Math.min(totalRows, sample2);
+          results.push({
+            column: col.name,
+            nullCount,
+            nullPercent: Number((nullCount / sampleSize * 100).toFixed(1))
+          });
+        }
+      } catch {}
+    }
+    return results;
+  }
+  async checkOrphans(tableName, columns) {
+    const fkColumns = columns.filter((c) => c.foreignKey);
+    const results = [];
+    for (const col of fkColumns) {
+      if (!col.foreignKey)
+        continue;
+      try {
+        const sql = `
+          SELECT COUNT(*) as orphan_count
+          FROM \`${tableName}\` child
+          LEFT JOIN \`${col.foreignKey.table}\` parent
+            ON child.\`${col.name}\` = parent.\`${col.foreignKey.column}\`
+          WHERE child.\`${col.name}\` IS NOT NULL
+            AND parent.\`${col.foreignKey.column}\` IS NULL
+        `;
+        const result = await this.adapter.execute(sql);
+        const orphanCount = result[0]?.orphan_count || 0;
+        if (orphanCount > 0) {
+          results.push({
+            column: col.name,
+            references: `${col.foreignKey.table}.${col.foreignKey.column}`,
+            orphanCount
+          });
+        }
+      } catch {}
+    }
+    return results;
+  }
+  async checkDuplicates(tableName, indexes) {
+    const uniqueIndexes = indexes.filter((idx) => idx.unique);
+    const results = [];
+    for (const idx of uniqueIndexes) {
+      try {
+        const colList = idx.columns.map((c) => `\`${c}\``).join(", ");
+        const sql = `
+          SELECT COUNT(*) as dup_count FROM (
+            SELECT ${colList}
+            FROM \`${tableName}\`
+            GROUP BY ${colList}
+            HAVING COUNT(*) > 1
+          ) dups
+        `;
+        const result = await this.adapter.execute(sql);
+        const dupCount = result[0]?.dup_count || 0;
+        if (dupCount > 0) {
+          results.push({
+            columns: idx.columns,
+            indexName: idx.name,
+            duplicateCount: dupCount
+          });
+        }
+      } catch {}
+    }
+    return results;
+  }
+  async checkEmptyStrings(tableName, columns) {
+    const stringColumns = columns.filter((c) => /varchar|text|char/i.test(c.type));
+    const results = [];
+    for (const col of stringColumns) {
+      try {
+        const sql = `SELECT COUNT(*) as empty_count FROM \`${tableName}\` WHERE \`${col.name}\` = ''`;
+        const result = await this.adapter.execute(sql);
+        const count = result[0]?.empty_count || 0;
+        if (count > 0) {
+          results.push({ column: col.name, count });
+        }
+      } catch {}
+    }
+    return results;
+  }
+}
+
+// src/commands/check.ts
+init_size_category();
+var checkCommand = new Command().name("check").description("Run data health checks on tables").argument("[table]", "Table to check (omit for --all)").option("--all", "Check all tables (skips huge tables unless --include-large)", false).option("--include-large", "Include huge tables in --all scan", false).option("--checks <types>", "Comma-separated checks: nulls,duplicates,orphans,emptyStrings", undefined).option("--sample <number>", "Sample size for large tables (default: 10000)", "10000").option("--format <format>", "Output format: json (default) or table", "json").option("--config <path>", "Path to .dbcli config file", ".dbcli").action(checkAction);
+async function checkAction(table, options) {
+  try {
+    const config = await configModule.read(options.config);
+    if (!config.connection) {
+      console.error("Database not configured. Run: dbcli init");
+      process.exit(1);
+    }
+    const adapter = AdapterFactory.createAdapter(config.connection);
+    await adapter.connect();
+    try {
+      const checker = new HealthChecker(adapter);
+      const blacklistManager = new BlacklistManager(config);
+      const blacklistedColumns = getBlacklistedColumnSet(blacklistManager);
+      const blacklistedTables = getBlacklistedTableSet(blacklistManager);
+      const checkTypes = options.checks ? options.checks.split(",") : undefined;
+      const sampleSize = parseInt(options.sample, 10) || 1e4;
+      if (table) {
+        if (blacklistedTables.has(table.toLowerCase())) {
+          console.error(`Table "${table}" is blacklisted`);
+          process.exit(1);
+        }
+        const schema = await adapter.getTableSchema(table);
+        const report = await checker.check(schema, {
+          checks: checkTypes,
+          sample: sampleSize,
+          blacklistedColumns
+        });
+        outputReport(report, options.format);
+      } else if (options.all) {
+        const tables = await adapter.listTables();
+        const reports = [];
+        const skipped = [];
+        for (const t7 of tables) {
+          if (blacklistedTables.has(t7.name.toLowerCase())) {
+            skipped.push(`${t7.name} (blacklisted)`);
+            continue;
+          }
+          if (t7.tableType === "view") {
+            skipped.push(`${t7.name} (view)`);
+            continue;
+          }
+          const category = getSizeCategory(t7.estimatedRowCount);
+          if (category === "huge" && !options.includeLarge) {
+            skipped.push(`${t7.name} (~${(t7.estimatedRowCount || 0).toLocaleString()} rows, huge)`);
+            continue;
+          }
+          const schema = await adapter.getTableSchema(t7.name);
+          const report = await checker.check(schema, {
+            checks: checkTypes,
+            sample: sampleSize,
+            blacklistedColumns
+          });
+          reports.push(report);
+        }
+        if (options.format === "json") {
+          console.log(JSON.stringify({ reports, skipped }, null, 2));
+        } else {
+          for (const report of reports) {
+            outputReport(report, "table");
+            console.log("");
+          }
+          if (skipped.length > 0) {
+            console.log(`Skipped: ${skipped.join(", ")}`);
+          }
+        }
+      } else {
+        console.error("Specify a table name or use --all");
+        process.exit(1);
+      }
+    } finally {
+      await adapter.disconnect();
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(error.message);
+      if (error instanceof ConnectionError) {
+        error.hints.forEach((hint) => console.error(`   Hint: ${hint}`));
+      }
+    }
+    process.exit(1);
+  }
+}
+function outputReport(report, format) {
+  if (format === "json") {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(`
+Table: ${report.table} (${report.rowCount} rows, ${report.sizeCategory})`);
+    console.log(`  Nulls: ${report.checks.nulls.length} columns with NULLs`);
+    for (const n of report.checks.nulls) {
+      console.log(`    ${n.column}: ${n.nullCount} nulls (${n.nullPercent}%)`);
+    }
+    console.log(`  Orphans: ${report.checks.orphans.length} FK violations`);
+    for (const o of report.checks.orphans) {
+      console.log(`    ${o.column} -> ${o.references}: ${o.orphanCount} orphans`);
+    }
+    console.log(`  Duplicates: ${report.checks.duplicates.length} unique index violations`);
+    for (const d of report.checks.duplicates) {
+      console.log(`    ${d.indexName} (${d.columns.join(",")}): ${d.duplicateCount} duplicates`);
+    }
+    console.log(`  Empty strings: ${report.checks.emptyStrings.length} columns`);
+    for (const e of report.checks.emptyStrings) {
+      console.log(`    ${e.column}: ${e.count} empty strings`);
+    }
+    console.log(`  Summary: ${report.summary.issues} issues, ${report.summary.warnings} warnings, ${report.summary.clean} clean`);
+  }
+}
+function getBlacklistedColumnSet(manager) {
+  const state = manager.state;
+  const result = new Set;
+  if (state?.columns) {
+    for (const [table, cols] of state.columns.entries()) {
+      for (const col of cols) {
+        result.add(`${table}.${col}`);
+      }
+    }
+  }
+  return result;
+}
+function getBlacklistedTableSet(manager) {
+  const state = manager.state;
+  return state?.tables || new Set;
+}
+
+// src/commands/diff.ts
+function compareSnapshots(before, after) {
+  const beforeTables = new Set(Object.keys(before.tables));
+  const afterTables = new Set(Object.keys(after.tables));
+  const addedTables = Array.from(afterTables).filter((t7) => !beforeTables.has(t7));
+  const removedTables = Array.from(beforeTables).filter((t7) => !afterTables.has(t7));
+  const addedColumns = [];
+  const removedColumns = [];
+  const modifiedColumns = [];
+  const indexChanges = [];
+  for (const tableName of addedTables) {
+    for (const col of after.tables[tableName].columns) {
+      addedColumns.push({ table: tableName, column: col.name, type: col.type, nullable: col.nullable });
+    }
+  }
+  for (const tableName of removedTables) {
+    for (const col of before.tables[tableName].columns) {
+      removedColumns.push({ table: tableName, column: col.name, type: col.type });
+    }
+  }
+  const commonTables = Array.from(afterTables).filter((t7) => beforeTables.has(t7));
+  for (const tableName of commonTables) {
+    const beforeTable = before.tables[tableName];
+    const afterTable = after.tables[tableName];
+    const beforeColMap = new Map(beforeTable.columns.map((c) => [c.name, c]));
+    const afterColMap = new Map(afterTable.columns.map((c) => [c.name, c]));
+    for (const [name, col] of afterColMap) {
+      if (!beforeColMap.has(name)) {
+        addedColumns.push({ table: tableName, column: name, type: col.type, nullable: col.nullable });
+      }
+    }
+    for (const [name, col] of beforeColMap) {
+      if (!afterColMap.has(name)) {
+        removedColumns.push({ table: tableName, column: name, type: col.type });
+      }
+    }
+    for (const [name, afterCol] of afterColMap) {
+      const beforeCol = beforeColMap.get(name);
+      if (!beforeCol)
+        continue;
+      if (beforeCol.type.toLowerCase() !== afterCol.type.toLowerCase() || beforeCol.nullable !== afterCol.nullable) {
+        modifiedColumns.push({
+          table: tableName,
+          column: name,
+          before: { type: beforeCol.type, nullable: beforeCol.nullable },
+          after: { type: afterCol.type, nullable: afterCol.nullable }
+        });
+      }
+    }
+    const beforeIndexes = new Map((beforeTable.indexes || []).map((i) => [i.name, i]));
+    const afterIndexes = new Map((afterTable.indexes || []).map((i) => [i.name, i]));
+    for (const name of afterIndexes.keys()) {
+      if (!beforeIndexes.has(name)) {
+        indexChanges.push({ table: tableName, name, change: "added" });
+      }
+    }
+    for (const name of beforeIndexes.keys()) {
+      if (!afterIndexes.has(name)) {
+        indexChanges.push({ table: tableName, name, change: "removed" });
+      }
+    }
+  }
+  return {
+    added: { tables: addedTables, columns: addedColumns },
+    removed: { tables: removedTables, columns: removedColumns },
+    modified: { columns: modifiedColumns, indexes: indexChanges },
+    summary: {
+      added: addedTables.length + addedColumns.length,
+      removed: removedTables.length + removedColumns.length,
+      modified: modifiedColumns.length + indexChanges.length
+    }
+  };
+}
+var diffCommand = new Command().name("diff").description("Compare schema snapshots to detect changes").option("--snapshot <path>", "Save current schema snapshot to file").option("--against <path>", "Compare current schema against a snapshot file").option("--format <format>", "Output format: json (default) or table", "json").option("--config <path>", "Path to .dbcli config file", ".dbcli").action(diffAction);
+async function diffAction(options) {
+  try {
+    if (!options.snapshot && !options.against) {
+      console.error("Specify --snapshot <path> to save, or --against <path> to compare");
+      process.exit(1);
+    }
+    const config = await configModule.read(options.config);
+    if (!config.connection) {
+      console.error("Database not configured. Run: dbcli init");
+      process.exit(1);
+    }
+    const adapter = AdapterFactory.createAdapter(config.connection);
+    await adapter.connect();
+    try {
+      const tables = await adapter.listTables();
+      const currentSnapshot = {
+        tables: {},
+        createdAt: new Date().toISOString()
+      };
+      for (const t7 of tables) {
+        if (t7.tableType === "view")
+          continue;
+        const schema = await adapter.getTableSchema(t7.name);
+        currentSnapshot.tables[t7.name] = {
+          name: schema.name,
+          columns: schema.columns,
+          indexes: schema.indexes || []
+        };
+      }
+      if (options.snapshot) {
+        await Bun.write(options.snapshot, JSON.stringify(currentSnapshot, null, 2));
+        console.error(`Snapshot saved to ${options.snapshot} (${Object.keys(currentSnapshot.tables).length} tables)`);
+        return;
+      }
+      if (options.against) {
+        const beforeFile = Bun.file(options.against);
+        if (!await beforeFile.exists()) {
+          console.error(`Snapshot file not found: ${options.against}`);
+          process.exit(1);
+        }
+        const beforeSnapshot = JSON.parse(await beforeFile.text());
+        const result = compareSnapshots(beforeSnapshot, currentSnapshot);
+        if (options.format === "json") {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(`
+Schema diff (${beforeSnapshot.createdAt} -> ${currentSnapshot.createdAt}):`);
+          if (result.added.tables.length > 0)
+            console.log(`
+  Added tables: ${result.added.tables.join(", ")}`);
+          if (result.removed.tables.length > 0)
+            console.log(`
+  Removed tables: ${result.removed.tables.join(", ")}`);
+          if (result.added.columns.length > 0) {
+            console.log(`
+  Added columns:`);
+            for (const c of result.added.columns)
+              console.log(`    ${c.table}.${c.column} (${c.type})`);
+          }
+          if (result.removed.columns.length > 0) {
+            console.log(`
+  Removed columns:`);
+            for (const c of result.removed.columns)
+              console.log(`    ${c.table}.${c.column} (${c.type})`);
+          }
+          if (result.modified.columns.length > 0) {
+            console.log(`
+  Modified columns:`);
+            for (const c of result.modified.columns)
+              console.log(`    ${c.table}.${c.column}: ${c.before.type} -> ${c.after.type}`);
+          }
+          if (result.modified.indexes.length > 0) {
+            console.log(`
+  Index changes:`);
+            for (const i of result.modified.indexes)
+              console.log(`    ${i.table}.${i.name}: ${i.change}`);
+          }
+          console.log(`
+  Summary: +${result.summary.added} -${result.summary.removed} ~${result.summary.modified}`);
+        }
+      }
+    } finally {
+      await adapter.disconnect();
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(error.message);
+      if (error instanceof ConnectionError) {
+        error.hints.forEach((hint) => console.error(`   Hint: ${hint}`));
+      }
+    }
+    process.exit(1);
+  }
+}
+
 // src/cli.ts
 var program2 = new Command().name("dbcli").description("Database CLI for AI agents").version(package_default.version).option("--config <path>", "Path to .dbcli config file", ".dbcli");
 program2.addCommand(initCommand);
@@ -50125,6 +50609,8 @@ program2.command("skill").description(t("skill.description")).option("--install
   }
 });
 program2.addCommand(blacklistCommand);
+program2.addCommand(checkCommand);
+program2.addCommand(diffCommand);
 if (!process.argv.slice(2).length) {
   program2.outputHelp();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carllee1983/dbcli",
-  "version": "0.2.0-beta",
+  "version": "0.3.1-beta",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {