sqlseed 0.1.11__tar.gz → 0.1.12__tar.gz

{sqlseed-0.1.11 → sqlseed-0.1.12}/CHANGELOG.md

@@ -17,7 +17,7 @@
 - `DataProvider` Protocol，含 `BaseProvider`、`FakerProvider`、`MimesisProvider`
 - `DataStream` 流式数据生成器，内存高效的批量处理
 - `RelationResolver` 外键依赖拓扑排序
-- 基于 `pluggy` 的插件系统，10 个 Hook 点
+- 基于 `pluggy` 的插件系统，11 个 Hook 点
 - CLI 命令：`fill`、`preview`、`inspect`、`init`、`replay`、`ai-suggest`
 - Python API：`sqlseed.fill()`、`sqlseed.connect()`、`sqlseed.fill_from_config()`、`sqlseed.preview()`
 - YAML/JSON 配置文件支持
@@ -81,5 +81,6 @@
 - `ProviderRegistry.register_from_entry_points()` 修正 provider 类与普通插件入口点的区分逻辑，非 provider 入口点（如 `sqlseed_ai:plugin`）不再产生误报 warning
 
 ### 变更
+- README / 开发文档与当前实现对齐：MCP tool 名称、Provider 协议示例、`sqlseed_shared_pool_loaded` 触发时机与 `UnknownGeneratorError` 行为说明已同步
 - 移除 `suggest.py`（`ColumnSuggester`）和 `nl_config.py`（`NLConfigGenerator`），其功能由 `SchemaAnalyzer` + `AiConfigRefiner` 完全替代。如有外部代码直接 `from sqlseed_ai.suggest import ColumnSuggester` 或 `from sqlseed_ai.nl_config import NLConfigGenerator`，将产生 `ImportError`
 - `plugins/sqlseed-ai/README.md` 功能描述与当前实际入口对齐，移除未对外提供的 "Column-level Suggestions" / "Natural Language Config" 描述

{sqlseed-0.1.11 → sqlseed-0.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlseed
-Version: 0.1.11
+Version: 0.1.12
 Summary: Declarative SQLite test data generation toolkit
 Project-URL: Homepage, https://github.com/sunbos/sqlseed
 Project-URL: Documentation, https://github.com/sunbos/sqlseed#readme
@@ -89,7 +89,7 @@ print(result)
 | 零配置智能生成    |    ✅    |    ❌   |       ❌      |
 | 外键自动维护     |    ✅    |   手动   |      手动      |
 | 10 万行 + 数据 |   ✅ 流式  | ⚠️ OOM |       ❌      |
-| 列语义推断      | ✅ 8 级策略 |    ❌   |       ❌      |
+| 列语义推断      | ✅ 9 级策略 |    ❌   |       ❌      |
 | 可重复生成      |  ✅ seed |  ⚠️ 手动 |       ✅      |
 | AI 智能调优    |  ✅ LLM  |    ❌   |       ❌      |
 | 配置热重用      |  ✅ YAML |    ❌   |       ❌      |
@@ -102,7 +102,7 @@ print(result)
 
 **🚀 零配置智能生成**
 
-自动推断数据库 Schema，通过 8 级策略链为每列选择最佳生成器。列名是 `email`？生成邮箱。列名是 `*_at`？生成时间戳。完全不需要配置。
+自动推断数据库 Schema，通过 9 级策略链为每列选择最佳生成器。列名是 `email`？生成邮箱。列名是 `*_at`？生成时间戳。完全不需要配置。
 
 </td>
 <td width="50%">
@@ -686,7 +686,7 @@ python -m mcp_server_sqlseed
 
 > "分析 `app.db` 中 `bank_cards` 表的结构，生成 YAML 配置，然后填充 5000 行数据。"
 
-AI 助手会依次调用 `inspect_schema` → `generate_yaml` → `execute_fill`，无需你手动编写任何代码。
+AI 助手会依次调用 `sqlseed_inspect_schema` → `sqlseed_generate_yaml` → `sqlseed_execute_fill`，无需你手动编写任何代码。
 
 ***
 
@@ -699,6 +699,8 @@ AI 助手会依次调用 `inspect_schema` → `generate_yaml` → `execute_fill`
 from __future__ import annotations
 from typing import Any
 
+from sqlseed.generators import UnknownGeneratorError
+
 class MyCustomProvider:
     """实现 DataProvider Protocol 即可。不需要继承任何基类。"""
 
@@ -715,13 +717,19 @@ class MyCustomProvider:
     def set_seed(self, seed: int) -> None:
         ...
 
-    def generate_string(self, *, min_length: int = 1, max_length: int = 100, charset: str | None = None) -> str:
-        return "custom_string"
+    def generate(self, type_name: str, **params: Any) -> Any:
+        if type_name == "string":
+            return "custom_string"
+        if type_name == "email":
+            return "user@example.com"
+        raise UnknownGeneratorError(type_name)
 
-    # ... 实现其余 generate_* 方法
+    # ... 按需处理你要支持的 generator 名称
     # 完整 Protocol 参见：src/sqlseed/generators/_protocol.py
 ```
 
+如果你想复用内置的 generator name 分发逻辑，而不是手写 `generate()` 的路由，也可以直接继承 `BaseProvider` 后覆盖局部行为。
+
 **注册方式 1：通过** **`pyproject.toml`** **entry-point（推荐）**
 
 ```toml
@@ -750,7 +758,7 @@ class MyPlugin:
 # 📋 数据生成
 # ═══════════════════════════════════════
 
-# 零配置填充
+# 填充数据（--count 在非 --config 模式下必填）
 sqlseed fill app.db --table users --count 10000
 
 # 完整参数
@@ -762,12 +770,15 @@ sqlseed fill app.db -t users -n 100000 \
     --clear \
     --snapshot
 
-# YAML 配置驱动
+# YAML 配置驱动（count 来自配置文件）
 sqlseed fill --config generate.yaml
 
 # Transform 脚本
 sqlseed fill app.db -t users -n 10000 --transform transform.py
 
+# 开启 debug 日志
+SQLSEED_LOG_LEVEL=DEBUG sqlseed fill app.db -t users -n 10
+
 # ═══════════════════════════════════════
 # 🔍 查看与预览
 # ═══════════════════════════════════════
@@ -802,34 +813,37 @@ sqlseed ai-suggest app.db -t users -o users.yaml --model gpt-4o --verify
 
 ***
 
-## 🧠 8 级智能列映射
+## 🧠 9 级智能列映射
 
-sqlseed 的核心亮点之一是 `ColumnMapper` 的 8 级策略链。每一列都会按以下优先级尝试匹配：
+sqlseed 的核心亮点之一是 `ColumnMapper` 的 9 级策略链。每一列都会按以下优先级尝试匹配：
 
 ```
 Level 1 │ 用户配置          columns={"email": "email"} 最高优先级
         ▼
 Level 2 │ 自定义精确匹配    通过插件 Hook 注册的规则
         ▼
-Level 3 │ 内置精确匹配      67 条规则：email→email, phone→phone, age→integer...
+Level 3 │ 内置精确匹配      68 条规则：email→email, phone→phone, age→integer...
+        ▼
+Level 4 │ DEFAULT 检查      有默认值 → skip（精确匹配优先于 DEFAULT）
         ▼
-Level 4 │ 自定义模式匹配    通过插件 Hook 注册的正则规则
+Level 5 │ 自定义模式匹配    通过插件 Hook 注册的正则规则
         ▼
-Level 5 │ 内置模式匹配      25 条正则：*_at→datetime, *_id→foreign_key, is_*→boolean...
+Level 6 │ 内置模式匹配      25 条正则：*_at→datetime, *_id→foreign_key, is_*→boolean...
         ▼
-Level 6 │ 跳过              有默认值或可 NULL → skip
+Level 7 │ NULLABLE 回退     可 NULL → skip
         ▼
-Level 7 │ 类型忠实回退      VARCHAR(32)→最长32字符, INT8→0~255, BLOB(1024)→1024字节
+Level 8 │ 类型忠实回退      VARCHAR(32)→最长32字符, INT8→0~255, BLOB(1024)→1024字节
         ▼
-Level 8 │ 默认              string (min=5, max=50)
+Level 9 │ 默认              string (min=5, max=50)
 ```
 
 这意味着：
 
-- 列名 `user_email` → Level 5 模式匹配 `*_email` → `email` 生成器 ✅
-- 列名 `is_verified` → Level 5 模式匹配 `is_*` → `boolean` 生成器 ✅
-- 列类型 `VARCHAR(20)` → Level 7 类型回退 → 最长 20 字符的字符串 ✅
-- 列有 `DEFAULT 1` → Level 6 → 跳过生成 ✅
+- 列名 `user_email` → Level 6 模式匹配 `*_email` → `email` 生成器 ✅
+- 列名 `is_verified` → Level 6 模式匹配 `is_*` → `boolean` 生成器 ✅
+- 列类型 `VARCHAR(20)` → Level 8 类型回退 → 最长 20 字符的字符串 ✅
+- 列有 `DEFAULT 1` → Level 4 → 跳过生成 ✅
+- 列名 `gender` 有 `DEFAULT 'male'` → Level 3 精确匹配 → `choice` 生成器（精确匹配优先于 DEFAULT）✅
 
 ***
 
@@ -849,7 +863,7 @@ sqlseed 通过 [pluggy](https://pluggy.readthedocs.io/) 提供 11 个 Hook 点
 | `sqlseed_transform_batch`         |    <br />   | 逐批变换（支持链式处理）           |
 | `sqlseed_before_insert`           |    <br />   | 每批写入 DB 前              |
 | `sqlseed_after_insert`            |    <br />   | 每批写入 DB 后              |
-| `sqlseed_shared_pool_loaded`      |    <br />   | 跨表共享池加载完成              |
+| `sqlseed_shared_pool_loaded`      |    <br />   | SharedPool 注册后（值池已可读）     |
 
 ***
 
@@ -860,7 +874,7 @@ src/sqlseed/
 ├── __init__.py              # 公共 API (fill, connect, fill_from_config, preview)
 ├── core/                    # ===== 核心编排层 =====
 │   ├── orchestrator.py      # DataOrchestrator 主引擎
-│   ├── mapper.py            # ColumnMapper 8 级策略链
+│   ├── mapper.py            # ColumnMapper 9 级策略链
 │   ├── schema.py            # SchemaInferrer — 推断列、索引、数据分布
 │   ├── relation.py          # RelationResolver + SharedPool — FK 与跨表共享
 │   ├── column_dag.py        # ColumnDAG — 列依赖图 + 拓扑排序
@@ -869,12 +883,12 @@ src/sqlseed/
 │   ├── transform.py         # TransformLoader — 用户脚本动态加载
 │   └── result.py            # GenerationResult 数据类
 ├── generators/              # ===== 数据生成层 =====
-│   ├── _protocol.py         # DataProvider Protocol (24 个 generate_* 方法)
+│   ├── _protocol.py         # DataProvider Protocol + UnknownGeneratorError
 │   ├── registry.py          # ProviderRegistry (entry-point 自动发现)
 │   ├── base_provider.py     # 内置基础生成器（零依赖）
 │   ├── faker_provider.py    # Faker 适配器
 │   ├── mimesis_provider.py  # Mimesis 适配器
-│   └── stream.py            # DataStream 流式生成 + 约束回溯
+│   └── stream.py            # DataStream 流式生成 + 约束回溯 + choice/foreign_key 特判
 ├── database/                # ===== 数据库层 =====
 │   ├── _protocol.py         # DatabaseAdapter Protocol (ColumnInfo, ForeignKeyInfo, IndexInfo)
 │   ├── sqlite_utils_adapter.py   # 默认适配器
@@ -900,7 +914,7 @@ plugins/
 ├── sqlseed-ai/              # AI 插件 — LLM 驱动的智能配置
 │   └── src/sqlseed_ai/      # SchemaAnalyzer, AiConfigRefiner, Few-shot 示例...
 └── mcp-server-sqlseed/      # MCP 服务器 — AI 助手交互
-    └── src/mcp_server_sqlseed/   # FastMCP 工具 (inspect/generate_yaml/execute_fill)
+    └── src/mcp_server_sqlseed/   # FastMCP 工具 (sqlseed_inspect_schema/sqlseed_generate_yaml/sqlseed_execute_fill)
 ```
 
 ***

{sqlseed-0.1.11 → sqlseed-0.1.12}/README.md

@@ -36,7 +36,7 @@ print(result)
 | 零配置智能生成    |    ✅    |    ❌   |       ❌      |
 | 外键自动维护     |    ✅    |   手动   |      手动      |
 | 10 万行 + 数据 |   ✅ 流式  | ⚠️ OOM |       ❌      |
-| 列语义推断      | ✅ 8 级策略 |    ❌   |       ❌      |
+| 列语义推断      | ✅ 9 级策略 |    ❌   |       ❌      |
 | 可重复生成      |  ✅ seed |  ⚠️ 手动 |       ✅      |
 | AI 智能调优    |  ✅ LLM  |    ❌   |       ❌      |
 | 配置热重用      |  ✅ YAML |    ❌   |       ❌      |
@@ -49,7 +49,7 @@ print(result)
 
 **🚀 零配置智能生成**
 
-自动推断数据库 Schema，通过 8 级策略链为每列选择最佳生成器。列名是 `email`？生成邮箱。列名是 `*_at`？生成时间戳。完全不需要配置。
+自动推断数据库 Schema，通过 9 级策略链为每列选择最佳生成器。列名是 `email`？生成邮箱。列名是 `*_at`？生成时间戳。完全不需要配置。
 
 </td>
 <td width="50%">
@@ -633,7 +633,7 @@ python -m mcp_server_sqlseed
 
 > "分析 `app.db` 中 `bank_cards` 表的结构，生成 YAML 配置，然后填充 5000 行数据。"
 
-AI 助手会依次调用 `inspect_schema` → `generate_yaml` → `execute_fill`，无需你手动编写任何代码。
+AI 助手会依次调用 `sqlseed_inspect_schema` → `sqlseed_generate_yaml` → `sqlseed_execute_fill`，无需你手动编写任何代码。
 
 ***
 
@@ -646,6 +646,8 @@ AI 助手会依次调用 `inspect_schema` → `generate_yaml` → `execute_fill`
 from __future__ import annotations
 from typing import Any
 
+from sqlseed.generators import UnknownGeneratorError
+
 class MyCustomProvider:
     """实现 DataProvider Protocol 即可。不需要继承任何基类。"""
 
@@ -662,13 +664,19 @@ class MyCustomProvider:
     def set_seed(self, seed: int) -> None:
         ...
 
-    def generate_string(self, *, min_length: int = 1, max_length: int = 100, charset: str | None = None) -> str:
-        return "custom_string"
+    def generate(self, type_name: str, **params: Any) -> Any:
+        if type_name == "string":
+            return "custom_string"
+        if type_name == "email":
+            return "user@example.com"
+        raise UnknownGeneratorError(type_name)
 
-    # ... 实现其余 generate_* 方法
+    # ... 按需处理你要支持的 generator 名称
     # 完整 Protocol 参见：src/sqlseed/generators/_protocol.py
 ```
 
+如果你想复用内置的 generator name 分发逻辑，而不是手写 `generate()` 的路由，也可以直接继承 `BaseProvider` 后覆盖局部行为。
+
 **注册方式 1：通过** **`pyproject.toml`** **entry-point（推荐）**
 
 ```toml
@@ -697,7 +705,7 @@ class MyPlugin:
 # 📋 数据生成
 # ═══════════════════════════════════════
 
-# 零配置填充
+# 填充数据（--count 在非 --config 模式下必填）
 sqlseed fill app.db --table users --count 10000
 
 # 完整参数
@@ -709,12 +717,15 @@ sqlseed fill app.db -t users -n 100000 \
     --clear \
     --snapshot
 
-# YAML 配置驱动
+# YAML 配置驱动（count 来自配置文件）
 sqlseed fill --config generate.yaml
 
 # Transform 脚本
 sqlseed fill app.db -t users -n 10000 --transform transform.py
 
+# 开启 debug 日志
+SQLSEED_LOG_LEVEL=DEBUG sqlseed fill app.db -t users -n 10
+
 # ═══════════════════════════════════════
 # 🔍 查看与预览
 # ═══════════════════════════════════════
@@ -749,34 +760,37 @@ sqlseed ai-suggest app.db -t users -o users.yaml --model gpt-4o --verify
 
 ***
 
-## 🧠 8 级智能列映射
+## 🧠 9 级智能列映射
 
-sqlseed 的核心亮点之一是 `ColumnMapper` 的 8 级策略链。每一列都会按以下优先级尝试匹配：
+sqlseed 的核心亮点之一是 `ColumnMapper` 的 9 级策略链。每一列都会按以下优先级尝试匹配：
 
 ```
 Level 1 │ 用户配置          columns={"email": "email"} 最高优先级
         ▼
 Level 2 │ 自定义精确匹配    通过插件 Hook 注册的规则
         ▼
-Level 3 │ 内置精确匹配      67 条规则：email→email, phone→phone, age→integer...
+Level 3 │ 内置精确匹配      68 条规则：email→email, phone→phone, age→integer...
+        ▼
+Level 4 │ DEFAULT 检查      有默认值 → skip（精确匹配优先于 DEFAULT）
         ▼
-Level 4 │ 自定义模式匹配    通过插件 Hook 注册的正则规则
+Level 5 │ 自定义模式匹配    通过插件 Hook 注册的正则规则
         ▼
-Level 5 │ 内置模式匹配      25 条正则：*_at→datetime, *_id→foreign_key, is_*→boolean...
+Level 6 │ 内置模式匹配      25 条正则：*_at→datetime, *_id→foreign_key, is_*→boolean...
         ▼
-Level 6 │ 跳过              有默认值或可 NULL → skip
+Level 7 │ NULLABLE 回退     可 NULL → skip
         ▼
-Level 7 │ 类型忠实回退      VARCHAR(32)→最长32字符, INT8→0~255, BLOB(1024)→1024字节
+Level 8 │ 类型忠实回退      VARCHAR(32)→最长32字符, INT8→0~255, BLOB(1024)→1024字节
         ▼
-Level 8 │ 默认              string (min=5, max=50)
+Level 9 │ 默认              string (min=5, max=50)
 ```
 
 这意味着：
 
-- 列名 `user_email` → Level 5 模式匹配 `*_email` → `email` 生成器 ✅
-- 列名 `is_verified` → Level 5 模式匹配 `is_*` → `boolean` 生成器 ✅
-- 列类型 `VARCHAR(20)` → Level 7 类型回退 → 最长 20 字符的字符串 ✅
-- 列有 `DEFAULT 1` → Level 6 → 跳过生成 ✅
+- 列名 `user_email` → Level 6 模式匹配 `*_email` → `email` 生成器 ✅
+- 列名 `is_verified` → Level 6 模式匹配 `is_*` → `boolean` 生成器 ✅
+- 列类型 `VARCHAR(20)` → Level 8 类型回退 → 最长 20 字符的字符串 ✅
+- 列有 `DEFAULT 1` → Level 4 → 跳过生成 ✅
+- 列名 `gender` 有 `DEFAULT 'male'` → Level 3 精确匹配 → `choice` 生成器（精确匹配优先于 DEFAULT）✅
 
 ***
 
@@ -796,7 +810,7 @@ sqlseed 通过 [pluggy](https://pluggy.readthedocs.io/) 提供 11 个 Hook 点
 | `sqlseed_transform_batch`         |    <br />   | 逐批变换（支持链式处理）           |
 | `sqlseed_before_insert`           |    <br />   | 每批写入 DB 前              |
 | `sqlseed_after_insert`            |    <br />   | 每批写入 DB 后              |
-| `sqlseed_shared_pool_loaded`      |    <br />   | 跨表共享池加载完成              |
+| `sqlseed_shared_pool_loaded`      |    <br />   | SharedPool 注册后（值池已可读）     |
 
 ***
 
@@ -807,7 +821,7 @@ src/sqlseed/
 ├── __init__.py              # 公共 API (fill, connect, fill_from_config, preview)
 ├── core/                    # ===== 核心编排层 =====
 │   ├── orchestrator.py      # DataOrchestrator 主引擎
-│   ├── mapper.py            # ColumnMapper 8 级策略链
+│   ├── mapper.py            # ColumnMapper 9 级策略链
 │   ├── schema.py            # SchemaInferrer — 推断列、索引、数据分布
 │   ├── relation.py          # RelationResolver + SharedPool — FK 与跨表共享
 │   ├── column_dag.py        # ColumnDAG — 列依赖图 + 拓扑排序
@@ -816,12 +830,12 @@ src/sqlseed/
 │   ├── transform.py         # TransformLoader — 用户脚本动态加载
 │   └── result.py            # GenerationResult 数据类
 ├── generators/              # ===== 数据生成层 =====
-│   ├── _protocol.py         # DataProvider Protocol (24 个 generate_* 方法)
+│   ├── _protocol.py         # DataProvider Protocol + UnknownGeneratorError
 │   ├── registry.py          # ProviderRegistry (entry-point 自动发现)
 │   ├── base_provider.py     # 内置基础生成器（零依赖）
 │   ├── faker_provider.py    # Faker 适配器
 │   ├── mimesis_provider.py  # Mimesis 适配器
-│   └── stream.py            # DataStream 流式生成 + 约束回溯
+│   └── stream.py            # DataStream 流式生成 + 约束回溯 + choice/foreign_key 特判
 ├── database/                # ===== 数据库层 =====
 │   ├── _protocol.py         # DatabaseAdapter Protocol (ColumnInfo, ForeignKeyInfo, IndexInfo)
 │   ├── sqlite_utils_adapter.py   # 默认适配器
@@ -847,7 +861,7 @@ plugins/
 ├── sqlseed-ai/              # AI 插件 — LLM 驱动的智能配置
 │   └── src/sqlseed_ai/      # SchemaAnalyzer, AiConfigRefiner, Few-shot 示例...
 └── mcp-server-sqlseed/      # MCP 服务器 — AI 助手交互
-    └── src/mcp_server_sqlseed/   # FastMCP 工具 (inspect/generate_yaml/execute_fill)
+    └── src/mcp_server_sqlseed/   # FastMCP 工具 (sqlseed_inspect_schema/sqlseed_generate_yaml/sqlseed_execute_fill)
 ```
 
 ***

sqlseed-0.1.12/src/sqlseed/_version.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("sqlseed")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

{sqlseed-0.1.11 → sqlseed-0.1.12}/src/sqlseed/cli/main.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 from typing import Any
 
 import click
@@ -10,12 +11,15 @@ from rich.table import Table as RichTable
 from sqlseed import fill as api_fill
 from sqlseed import fill_from_config
 from sqlseed import preview as api_preview
+from sqlseed._utils.logger import configure_logging, get_logger
 from sqlseed._version import __version__
 from sqlseed.config.loader import generate_template, save_config
 from sqlseed.config.models import GeneratorConfig, ProviderType, TableConfig
 from sqlseed.config.snapshot import SnapshotManager
 from sqlseed.core.orchestrator import DataOrchestrator
 
+logger = get_logger(__name__)
+
 try:
     from sqlseed_ai.analyzer import SchemaAnalyzer
     from sqlseed_ai.config import AIConfig
@@ -30,6 +34,8 @@ except ImportError:
 @click.version_option(version=__version__, prog_name="sqlseed")
 def cli() -> None:
     """sqlseed - Declarative SQLite test data generation toolkit."""
+    log_level = os.environ.get("SQLSEED_LOG_LEVEL", "WARNING").upper()
+    configure_logging(log_level)
 
 
 def _fill_from_config_cmd(config_path: str) -> None:
@@ -67,14 +73,34 @@ def _save_snapshot_cmd(
     click.echo(f"Snapshot saved: {snapshot_path}")
 
 
+_FILL_DEFAULT_COUNT = 1000
+
+
 @cli.command()
 @click.argument("db_path", required=False)
 @click.option("--table", "-t", default=None, help="Target table name")
-@click.option("--count", "-n", default=1000, type=int, help="Number of rows to generate")
-@click.option("--provider", "-p", default="mimesis", help="Data provider (mimesis|faker|base)")
-@click.option("--locale", "-l", default="en_US", help="Locale for data generation")
+@click.option(
+    "--count",
+    "-n",
+    default=None,
+    type=int,
+    help="Number of rows to generate (required when not using --config)",
+)
+@click.option(
+    "--provider",
+    "-p",
+    default="mimesis",
+    help="Data provider: mimesis|faker|base (default: mimesis)",
+)
+@click.option("--locale", "-l", default="en_US", help="Locale for data generation (default: en_US)")
 @click.option("--seed", "-s", default=None, type=int, help="Random seed for reproducibility")
-@click.option("--batch-size", "-b", default=5000, type=int, help="Batch size for insertion")
+@click.option(
+    "--batch-size",
+    "-b",
+    default=5000,
+    type=int,
+    help="Batch size for insertion (default: 5000)",
+)
 @click.option("--clear", is_flag=True, help="Clear table before generating")
 @click.option("--config", "-c", "config_path", default=None, help="YAML/JSON config file path")
 @click.option("--transform", "transform_path", default=None, help="Python transform script path")
@@ -84,14 +110,31 @@ def fill(**kwargs: Any) -> None:
     """Fill a table with generated test data.
 
     Use --config for config-driven generation, or provide db_path + --table
-    for direct generation.
+    + --count for direct generation.
     """
+    count = kwargs.get("count")
+    config_path = kwargs.get("config_path")
+
+    if count is not None and count <= 0:
+        logger.debug("Invalid count value", count=count)
+        raise click.UsageError(f"--count must be greater than 0, got {count}")
+
+    if not config_path and count is None:
+        raise click.UsageError(
+            "--count is required when not using --config. Use -n <number> to specify the number of rows to generate."
+        )
+
+    if config_path and count is None:
+        count = _FILL_DEFAULT_COUNT
+
+    kwargs["count"] = count
     _execute_fill(kwargs)
 
 
 def _execute_fill(opts: dict[str, Any]) -> None:
     config_path = opts.get("config_path")
     if config_path:
+        logger.debug("Using config-driven generation", config_path=config_path)
         _fill_from_config_cmd(config_path)
         return
 
@@ -102,25 +145,32 @@ def _execute_fill(opts: dict[str, Any]) -> None:
     if not table:
         raise click.UsageError("--table is required when not using --config")
 
-    result = api_fill(
-        db_path,
-        table=table,
-        count=opts.get("count", 1000),
-        provider=opts.get("provider", "mimesis"),
-        locale=opts.get("locale", "en_US"),
-        seed=opts.get("seed"),
-        batch_size=opts.get("batch_size", 5000),
-        clear_before=opts.get("clear", False),
-        enrich=opts.get("enrich", False),
-        transform=opts.get("transform_path"),
-    )
+    count = opts.get("count", _FILL_DEFAULT_COUNT)
+    logger.debug("Starting fill", db_path=db_path, table=table, count=count)
+
+    try:
+        result = api_fill(
+            db_path,
+            table=table,
+            count=count,
+            provider=opts.get("provider", "mimesis"),
+            locale=opts.get("locale", "en_US"),
+            seed=opts.get("seed"),
+            batch_size=opts.get("batch_size", 5000),
+            clear_before=opts.get("clear", False),
+            enrich=opts.get("enrich", False),
+            transform=opts.get("transform_path"),
+        )
+    except ValueError as exc:
+        logger.debug("Fill failed with ValueError", error=str(exc))
+        raise click.UsageError(str(exc)) from exc
     click.echo(str(result))
 
     if opts.get("snapshot"):
         _save_snapshot_cmd(
             db_path,
             table,
-            opts.get("count", 1000),
+            count,
             opts.get("provider", "mimesis"),
             opts.get("locale", "en_US"),
             opts.get("seed"),
@@ -132,9 +182,14 @@ def _execute_fill(opts: dict[str, Any]) -> None:
 @cli.command()
 @click.argument("db_path")
 @click.option("--table", "-t", required=True, help="Target table name")
-@click.option("--count", "-n", default=5, type=int, help="Number of rows to preview")
-@click.option("--provider", "-p", default="mimesis", help="Data provider")
-@click.option("--locale", "-l", default="en_US", help="Locale")
+@click.option("--count", "-n", default=5, type=int, help="Number of rows to preview (default: 5)")
+@click.option(
+    "--provider",
+    "-p",
+    default="mimesis",
+    help="Data provider: mimesis|faker|base (default: mimesis)",
+)
+@click.option("--locale", "-l", default="en_US", help="Locale (default: en_US)")
 @click.option("--seed", "-s", default=None, type=int, help="Random seed")
 def preview(
     db_path: str,
@@ -228,7 +283,7 @@ def inspect(db_path: str, table: str | None, show_mapping: bool) -> None:
 
 @cli.command()
 @click.argument("config_path")
-@click.option("--db", default="test.db", help="Database path for template")
+@click.option("--db", default="test.db", help="Database path for template (default: test.db)")
 def init(config_path: str, db: str) -> None:
     """Generate a YAML configuration template."""
     config = generate_template(db)
@@ -274,11 +329,16 @@ def _handle_ai_direct(analyzer: Any, db_path: str, table: str) -> Any:
 @click.argument("db_path")
 @click.option("--table", "-t", required=True, help="Target table name")
 @click.option("--output", "-o", required=True, help="Output YAML file path")
-@click.option("--model", "-m", default=None, help="AI model name (default: qwen3-coder-plus)")
-@click.option("--api-key", envvar="SQLSEED_AI_API_KEY", default=None, help="AI API key")
-@click.option("--base-url", envvar="SQLSEED_AI_BASE_URL", default=None, help="AI API base URL")
-@click.option("--max-retries", default=3, type=int, help="Max refinement retries (0=disable)")
-@click.option("--verify/--no-verify", default=True, help="Enable AI config self-correction")
+@click.option("--model", "-m", default=None, help="AI model name (default: gpt-4o)")
+@click.option("--api-key", envvar="SQLSEED_AI_API_KEY", default=None, help="AI API key (env: SQLSEED_AI_API_KEY)")
+@click.option(
+    "--base-url",
+    envvar="SQLSEED_AI_BASE_URL",
+    default=None,
+    help="AI API base URL (env: SQLSEED_AI_BASE_URL)",
+)
+@click.option("--max-retries", default=3, type=int, help="Max refinement retries, 0=disable (default: 3)")
+@click.option("--verify/--no-verify", default=True, help="Enable AI config self-correction (default: verify)")
 @click.option("--no-cache", is_flag=True, help="Skip cached AI configs")
 def ai_suggest(
     db_path: str,

{sqlseed-0.1.11 → sqlseed-0.1.12}/src/sqlseed/core/mapper.py

@@ -231,6 +231,20 @@ class ColumnMapper:
             return GeneratorSpec(generator_name="skip")
         return None
 
+    def _map_from_default(
+        self, column_info: ColumnInfo, column_type: str, enrich: bool, force_type_infer: bool
+    ) -> GeneratorSpec | None:
+        if column_info.default is not None:
+            if force_type_infer:
+                return self._type_faithful_fallback(column_type)
+            if enrich:
+                return GeneratorSpec(
+                    generator_name="__enrich__",
+                    params={"_default": column_info.default, "_nullable": column_info.nullable},
+                )
+            return GeneratorSpec(generator_name="skip")
+        return None
+
     def map_column(
         self,
         column_info: ColumnInfo,
@@ -255,6 +269,10 @@ class ColumnMapper:
         if exact_match:
             return exact_match
 
+        default_spec = self._map_from_default(column_info, column_type, enrich, force_type_infer)
+        if default_spec:
+            return default_spec
+
         pattern_match = self._match_pattern(column_name)
         if pattern_match:
             return pattern_match

{sqlseed-0.1.11 → sqlseed-0.1.12}/src/sqlseed/core/orchestrator.py

@@ -229,6 +229,8 @@ class DataOrchestrator:
     ) -> GenerationResult:
         self._ensure_connected()
         validate_table_name(table_name)
+        if count <= 0:
+            raise ValueError(f"count must be greater than 0, got {count}")
         start_time = time.monotonic()
         total_inserted = 0
         batch_count = 0

{sqlseed-0.1.11 → sqlseed-0.1.12}/src/sqlseed/database/raw_sqlite_adapter.py

@@ -127,6 +127,7 @@ class RawSQLiteAdapter(BaseSQLiteAdapter):
         validate_table_name(table_name)
         safe_table = quote_identifier(table_name)
         self.conn.execute(f"DELETE FROM {safe_table}")
+        self.conn.execute(f"DELETE FROM sqlite_sequence WHERE name = {safe_table}")
         self.conn.commit()
         logger.debug("Cleared table", table_name=table_name)
 

{sqlseed-0.1.11 → sqlseed-0.1.12}/src/sqlseed/database/sqlite_utils_adapter.py

@@ -134,6 +134,7 @@ class SQLiteUtilsAdapter(BaseSQLiteAdapter):
         validate_table_name(table_name)
         safe_table = quote_identifier(table_name)
         self._db.execute(f"DELETE FROM {safe_table}")
+        self._db.execute(f"DELETE FROM sqlite_sequence WHERE name = {safe_table}")
         logger.debug("Cleared table", table_name=table_name)
 
     def _execute_pragma(self, sql: str) -> None:

sqlseed-0.1.11/src/sqlseed/_version.py

@@ -1,3 +0,0 @@
-from __future__ import annotations
-
-__version__ = "0.1.0"