sqlseed 0.2.4__tar.gz → 0.2.6__tar.gz

{sqlseed-0.2.4 → sqlseed-0.2.6}/.gitignore

@@ -59,6 +59,16 @@ dmypy.json
 *.db
 *.sqlite
 *.sqlite3
+# SQLite runtime sidecars
+*.db-wal
+*.db-shm
+*.db-journal
+*.sqlite-wal
+*.sqlite-shm
+*.sqlite-journal
+*.sqlite3-wal
+*.sqlite3-shm
+*.sqlite3-journal
 .sqlseed_cache/
 snapshots/
 .env

{sqlseed-0.2.4 → sqlseed-0.2.6}/CHANGELOG.md

@@ -9,6 +9,82 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.6] - 2026-10-07
+
+### Changed
+
+- Refine Web surface hierarchy, contrast and selection motion, keeping data panels opaque and applying translucent materials to navigation and overlays. Preserve reduced-motion, reduced-transparency and unsupported-filter fallbacks.
+- Make workbench guidance more compact, collapse the table directory on narrow screens, enlarge touch targets and keep generation status, blocking reasons and keyboard focus easier to follow. Shorten the English navigation label from Configurations to Configs without changing its page or actions.
+- Provide English and Simplified Chinese documentation with localized navigation, refreshed package guidance and macOS setup instructions. Expand native macOS regression coverage across Apple Silicon and Intel.
+- Retire obsolete standalone defect probes in favor of the maintained regression suite, and ignore SQLite runtime journal and shared-memory sidecars in the repository.
+
+### Fixed
+
+- Align dependency controls and display generation-locale labels without diagnostic prefixes. Prevent open dropdowns from throwing a `Node.contains` error on window resize.
+- Resolve equivalent macOS SQLite path spellings to the same target without folding distinct filenames or opening an extra database descriptor.
+- Distinguish Apple unified memory from Intel/shared or dedicated GPU memory. Report unified-memory model capacity as a heuristic budget rather than measured free VRAM or verified backend compatibility.
+- Close AI clients, response streams and failed HTTP probes on error paths.
+- Install all five local packages together in the quickstart environment, reject unusable virtual environments and print correctly quoted commands for the selected interpreter and shell.
+- Distinguish AI rule-cache column sets containing separator characters. Use a versioned, unambiguous column-name hash; legacy hashes are safely invalidated and refreshed on the next suggestion request.
+- Adapt terminal progress rendering when the output stream or encoding changes, including UTF-8 capture returning to GBK, and safely display non-ASCII descriptions in narrow terminals without replacing the original generation error.
+- Retain ownership of a newly started Web worker if its resume acknowledgement fails, drain it before returning to maintenance, and restore the recovery page after delayed shutdown. Preserve startup diagnostics for service-only recovery without repeating the component installation.
+
+### Compatibility
+
+- Retain the plugin requirement for Core `>=0.2.5.dev0,<0.3`; install matching package versions. Existing Python, CLI and configuration entry points remain unchanged, while AI rule-cache entries with the old column hash are refreshed on demand.
+- SQLite cycle appends still require existing non-NULL single-column parent keys and retain the 100,000-key source-pool limit. Ordinary acyclic appends still commit batch by batch; a later failure can leave earlier batches committed. This release does not change those generation or transaction boundaries.
+
+## [0.2.5] - 2026-10-02
+
+### Added
+
+- Add reusable `FillOptions` for single-table generation. Existing `fill()` keyword calls and defaults remain supported; explicit keywords override shared settings.
+- Add Simplified Chinese and English interface switching across the Web workbench, configurations, run history and settings, preserving edits and keeping interface language separate from generated-data locale. Bundled message resources also translate supported backend diagnostics.
+- Add light, dark and system appearance, browser-local defaults for new configurations, and a shared Web component reference with bundled fonts.
+- Support managed component changes on Windows and reviewed updates of optional components with fixed dependencies, wheel hashes and service recovery.
+- Add editable AI suggestions and contextual preview-rule editing, keeping unapplied changes separate from active generation rules.
+- Support Web preview and atomic append for SQLite cross-table cycles when every internal edge is a single-column foreign key with existing non-NULL parent keys. Freeze the available keys before insertion, recheck sources and rules before writing, and roll back all newly inserted rows in the selected scope if any batch fails.
+
+### Changed
+
+- Split complex AI parsing and graph layout stages into focused helpers, and merge duplicate CSS declarations while preserving rendering and interaction behavior. `fill()` introspection now shows grouped options and typed compatibility keywords; the complete parameter reference remains in the API guide.
+- Simplify workbench guidance, configuration actions and relationship views; add pointer-centered graph zoom, stable hover geometry and actionable cycle locations.
+- Add editable graph zoom percentages, clearer node and relationship legends, and brief selection feedback for tabs, workflow stages and checkboxes. Respect reduced-motion preferences and keep dependency arrows static rather than implying an active data transfer.
+- Guide SQLite clear-and-regenerate failures through a reviewed downstream-table expansion while preserving the selected write mode and final confirmation.
+- Deliver Core, CLI, AI, Core MCP and Web together at version 0.2.5. Plugins require Core `>=0.2.5.dev0,<0.3` for shared connection parsing and credential redaction; the 0.2.4 release retains its original dependency metadata.
+- Refresh bilingual package and architecture documentation, update the wordmark, and replace obsolete audit logs with concise historical decision records.
+
+### Fixed
+
+- Make both Core MCP tools explicitly use Faker, matching their generated YAML templates and avoiding a fallback to Base when optional Mimesis is absent. The existing target-table-only YAML execution scope is unchanged.
+- Close tutorial SQLite connections and explicitly clean up temporary Notebook databases and cache settings, with complete offline execution checks for four affected notebooks.
+- Preserve SQLite `mode=memory` connection-pool behavior explicitly across SQLAlchemy 2.0/2.1, avoiding a deprecated implicit default without changing URI parsing or thread policy.
+- Reject non-object AI tool arguments through the normal format-error path, apply strict output-limit checks to streaming refinement, and ignore malformed suggestion cache envelopes.
+- Bound Web update checks across DNS and response-header waits, retain in-flight request limits after timeouts, and prevent late responses from replacing the active cache result.
+- Publish a terminal component-operation failure when temporary-file cleanup fails, preserving installer exit information and service recovery without automatically retrying installation.
+- Reject missing or columnless AI refinement targets before reading cached suggestions or calling a model, preserving valid empty tables and SQLite identifier resolution.
+- Keep AI-refined suggestions and cached configurations bound to the requested table; retry wrong-target model responses and ignore mismatched caches without silently renaming them.
+- Preserve quoted colon identifiers in database sampling, column-value and row-count queries without treating them as SQL parameters or changing sampled JSON/date values.
+- Refresh the installer snapshot when reviewing a new component operation plan, so temporary pip/uv detection changes do not permanently block installation; environment and dependency changes are still checked before execution.
+- Preserve SQLite file URL identity across encoded and special-character paths; opening an existing file or restoring a session cannot create a missing replacement database.
+- Restore each database connection's own unsaved workbench state when switching connections. Distinguish a configuration/database mismatch from a connection failure, offer a route back to the current database or to the matching target, and ignore stale responses after switching.
+- Report invalid generator bounds before applying rules; recover empty schemas after a refresh and restore keyboard focus after failed connections or background run polling.
+- Keep database credentials out of connection responses, validation errors, exception messages and diagnostic logs without changing runtime connection targets.
+- Treat invalid date ranges as configuration errors instead of exhausting random-generation retries; clarify the existing date/time contract in AI prompts and validate malformed JSON containers normally.
+- Distinguish malformed AI JSON from empty configurations and feed safe format diagnostics into existing bounded retries; unknown generators follow the existing validation recovery path.
+- Constrain strict local AI responses with LM Studio JSON-schema mode or Ollama JSON-object mode. Allow one text-mode compatibility attempt only when the server explicitly rejects the requested format; preserve strict parsing, output-limit checks, authentication failures and unrelated server errors.
+- Connect local AI services at `localhost` and loopback IP addresses directly when environment proxies are present, without changing remote proxy routing or HTTPS certificate settings.
+- Explain unsupported generation scopes, missing previews and disabled identity-reset controls with their actual cause. Preserve successfully returned samples and keep existing database records separately available for read-only inspection.
+- Preserve frontend error feedback and interaction state after failed asynchronous operations; improve light-theme control contrast, selected checkboxes, inspector spacing and diagnostic/example typography.
+- Update the PyPI uploader for Core Metadata 2.5 and allow the maintained workflow to publish an existing release tag without changing its source commit.
+- Use the shared `pypi` environment for all five existing packages while retaining separate upload jobs and post-publication acceptance; verify publisher permissions using unchanged public release files.
+- Upload only the measured Python coverage report, verify the Codecov signer in an isolated keyring, and deploy documentation through the supported GitHub Pages API with artifact provenance checks, bounded polling and cancellation.
+
+### Compatibility
+
+- SQLite cycle appends reuse existing parent records; newly generated cyclic records do not reference one another. Each source pool contains at most 100,000 distinct non-NULL keys. This does not bypass UNIQUE/CHECK constraints or add cross-table backfill. Empty-source cycles, cycles involving composite/overlapping foreign keys or configured associations, PostgreSQL cycles, and clearing cyclic tables before regeneration remain unsupported in the Web workbench.
+- Selecting every table or resetting IDs cannot remove an unsupported cycle. Ordinary acyclic appends process tables sequentially and commit each batch, so a later failure can leave earlier batches committed. Atomic rollback applies to the supported SQLite cycle-append and clear-and-regenerate paths. See the [Web workbench guide](docs/web-workbench.md) for the full boundaries.
+
 ## [0.2.4] - 2026-09-13
 
 ### Added

{sqlseed-0.2.4 → sqlseed-0.2.6}/CHANGELOG.zh-CN.md

@@ -9,6 +9,82 @@
 
 ## [Unreleased]
 
+## [0.2.6] - 2026-10-07
+
+### 变更
+
+- 优化 Web 界面的材质层级、对比度和选择动效，数据面板保持实色，导航与浮层使用半透明材质；保留减少动态效果、减少透明度及不支持背景滤镜时的降级显示。
+- 压缩工作台流程引导，在窄屏折叠数据表目录、扩大触控区域，并改善生成状态、阻塞原因与键盘焦点的呈现。英文导航将 Configurations 简写为 Configs，页面与操作保持不变。
+- 文档站提供英文和简体中文导航，同步包安装说明与 macOS 使用指南；扩展 Apple Silicon 和 Intel Mac 的原生回归覆盖。
+- 用维护中的回归测试替代过期独立缺陷探针，并在仓库中忽略 SQLite 运行时日志及共享内存旁文件。
+
+### 修复
+
+- 对齐依赖视图控件，移除数据语言选项中误加的诊断前缀；修复下拉展开时调整窗口大小触发的 `Node.contains` 异常。
+- 将 macOS 上指向同一 SQLite 文件的不同路径写法识别为同一目标，不混淆不同文件，也不额外打开数据库文件描述符。
+- 正确区分 Apple 统一内存、Intel 共享显存与独立显存；统一内存的模型容量仅作为估算预算，不等同于实测可用显存或已验证的后端兼容性。
+- 在异常路径关闭 AI 客户端、响应流和失败的 HTTP 探测。
+- Quickstart 在同一次解析中安装五个本地包，拒绝无法使用的虚拟环境，并按实际解释器和 shell 输出正确引用的后续命令。
+- 修复 AI 规则缓存对包含分隔符的不同列名集合判断相同的问题，改用带版本且无歧义的列名 hash；旧 hash 安全失效，在下次请求规则建议时重新生成缓存。
+- 终端进度条在输出流或编码变化时重新选择可显示的字符，覆盖 UTF-8 捕获结束后恢复 GBK 的情况；中文描述与窄终端显示也不会因编码异常覆盖原始生成错误。
+- Web 新业务进程启动后若恢复确认失败，继续保留其管理权，安全排空并停止后再返回维护状态，延迟退出后也会重新提供恢复页面；保留启动诊断，重试仅恢复服务，不重复安装组件。
+
+### 兼容性
+
+- 插件沿用 Core `>=0.2.5.dev0,<0.3` 的依赖要求，请使用匹配的包版本。Python、CLI 和配置入口保持兼容，旧列名 hash 对应的 AI 规则缓存会按需重新生成。
+- SQLite 循环追加仍要求已有非空单列父键，来源池上限仍为 100,000 个键。普通无跨表循环的追加仍逐批提交，后续失败可能保留先前已提交的批次；本版不改变这些生成与事务边界。
+
+## [0.2.5] - 2026-10-02
+
+### 新增
+
+- 增加可复用的 `FillOptions` 单表生成参数。既有 `fill()` 关键字调用和默认值保持兼容，显式关键字优先于共享设置。
+- Web 工作台、配置管理、运行记录与设置支持简体中文和 English 切换，保留编辑状态，界面语言与生成数据的 locale 分离；随包分发的消息资源同时翻译受支持的后端诊断。
+- 增加浅色、深色及跟随系统外观、保存在浏览器中的新建配置偏好，以及包含分发字体的 Web 共用组件样板。
+- 支持 Windows 受管组件变更；可选组件更新需审阅依赖、固定其他包版本、核验 wheel 哈希，并恢复服务。
+- AI 建议支持应用前微调，预览可在保留上下文的情况下编辑字段规则；未应用修改与当前生成规则分开保存。
+- Web 支持 SQLite 已有来源的跨表循环预览与原子追加：环内每条关系必须是已有非空父键的单列外键。生成前固定引用来源，写入前重新核对来源与规则，任一批次失败时回滚整个所选范围的本次新增记录。
+
+### 变更
+
+- 将复杂 AI 解析与关系图布局阶段拆分为职责明确的辅助函数，合并重复 CSS 声明并保持渲染与交互行为。`fill()` 签名内省改为分组参数和带类型的兼容关键字，API 指南保留完整参数参考。
+- 简化工作台引导、配置操作与关系图；增加鼠标位置缩放、稳定的悬停几何和可定位到具体表的循环问题。
+- 关系图支持手动输入缩放比例，明确节点与关系图例；标签页、流程阶段和复选框提供短暂选择反馈并遵循减少动态效果设置。依赖箭头保持静态，避免暗示正在传输数据。
+- SQLite 清空重建受阻时，引导审阅并补齐下游关联表，保留已选写入方式和最后确认步骤。
+- Core、CLI、AI、Core MCP 与 Web 统一以 0.2.5 版本交付。插件要求 Core `>=0.2.5.dev0,<0.3`，使用共享连接解析与凭据脱敏；0.2.4 发行包保留原有依赖元数据。
+- 同步双语包说明与架构文档，更新品牌标识；用简明历史决策记录替换过期验收日志。
+
+### 修复
+
+- 两个 Core MCP 工具显式使用 Faker，与生成的 YAML 模板一致，避免未安装可选 Mimesis 时回退到 Base；YAML 仍只执行工具指定目标表的既有配置范围。
+- 关闭教程 SQLite 连接，显式清理 Notebook 临时数据库并恢复缓存设置；四份受影响示例增加完整离线执行验收。
+- 显式保留 SQLAlchemy 2.0/2.1 下 SQLite `mode=memory` 的连接池行为，消除已弃用的隐式选择，不改变 URI 解析或线程策略。
+- AI 工具参数为非对象 JSON 时进入正常格式错误处理；流式优化同样严格检查输出截断，结构损坏的建议缓存按失效处理。
+- Web 检查更新的等待预算覆盖 DNS 与响应头阶段；超时后保留在途请求数量限制，迟到响应不会覆盖当前缓存结果。
+- 组件操作临时文件清理失败时仍发布明确失败终态，保留安装器退出信息并恢复服务，不自动重试安装。
+- AI 单表配置优化在读取建议缓存或调用模型前拒绝不存在或没有列的目标，保留合法空表及 SQLite 标识符解析行为。
+- AI 优化建议与缓存配置必须属于请求的同一张表；目标错误的模型响应进入重试，错目标缓存重新生成，不静默改名。
+- 数据库采样、列值与行数查询保留已引用的冒号标识符，不再将其误判为 SQL 参数，并保持 JSON 与日期采样值的既有表示。
+- 重新审阅组件操作计划时更新安装器快照，避免 pip/uv 临时探测变化持续阻塞安装；执行前仍核验环境与依赖是否改变。
+- 保留编码及特殊字符 SQLite 文件 URL 的真实目标身份；打开已有文件或恢复会话时，不会创建已丢失数据库的替代空库。
+- 切换数据库时恢复各自未保存的工作台状态；区分配置与数据库不匹配和连接失败，提供返回当前数据库或选择对应目标的入口，切换后的迟到响应不会覆盖新状态。
+- 应用规则前定位非法生成器边界；重新读取空库结构后能进入新表；连接失败或运行记录轮询后恢复键盘焦点。
+- 连接响应、参数校验错误、异常与诊断日志不再回显数据库凭据；实际运行连接目标保持原样。
+- 无效日期范围按配置错误报告，不再耗尽随机取值重试；AI 提示明确既有日期时间合同，错误 JSON 容器交给正常配置校验。
+- 区分 AI 的非法 JSON 与空配置，在既有有界重试中反馈安全的格式诊断；未知生成器进入已有配置校验恢复路径。
+- 本地 AI 严格输出使用 LM Studio JSON-schema 模式或 Ollama JSON-object 模式。仅在服务器明确拒绝指定格式时尝试一次文本兼容请求；仍执行严格解析与截断检查，认证失败及无关服务器错误不会因此降级。
+- 配置了环境代理时，`localhost` 与回环 IP 上的本地 AI 服务仍直接连接；远程服务代理与 HTTPS 证书设置保持不变。
+- 按实际原因说明不支持的生成范围、缺失的新样例与自增重置禁用状态；保留其他已成功返回的样例，并将数据库已有记录作为独立只读入口。
+- 异步操作失败后保留前端错误反馈与交互状态；改善浅色主题控件对比度、复选框选中状态、检查区间距及诊断和示例字体。
+- 升级 PyPI 上传工具以支持 Core Metadata 2.5，并允许通过维护后的工作流发布现有版本 tag，保持其源码提交不变。
+- 五个已创建的包统一使用 `pypi` 发布环境，保留各包独立上传任务及发布后验收，并通过保持不变的公开发行文件核验发布权限。
+- 覆盖率只上传实际测量的 Python 报告，并在独立密钥环中核验 Codecov 签名者；文档通过受支持的 GitHub Pages API 部署，核对产物来源并限制轮询与取消的等待时间。
+
+### 兼容性
+
+- SQLite 循环追加引用已有父表记录，新生成的循环表记录不会互相引用；每个来源最多使用 100,000 个非空不同键，不绕过 UNIQUE/CHECK 约束，也不增加跨表回填。来源为空、涉及组合或重叠外键或配置关联、PostgreSQL 循环，以及清空循环表后重建，仍不属于当前 Web 工作台支持范围。
+- 全选数据表或重置 ID 不能解除不支持的循环。普通无跨表循环的追加保持逐表执行、逐批提交，后续失败可能保留先前已提交的批次；原子回滚适用于已支持的 SQLite 循环追加与清空重建流程。完整边界见 [Web 工作台指南](docs/web-workbench.md)。
+
 ## [0.2.4] - 2026-09-13
 
 ### 新增

sqlseed-0.2.6/PKG-INFO

@@ -0,0 +1,385 @@
+Metadata-Version: 2.5
+Name: sqlseed
+Version: 0.2.6
+Summary: Offline declarative SQLite and PostgreSQL test data generation for Python
+Project-URL: Homepage, https://github.com/sunbos/sqlseed
+Project-URL: Documentation, https://sunbos.github.io/sqlseed/
+Project-URL: Repository, https://github.com/sunbos/sqlseed
+Project-URL: Issues, https://github.com/sunbos/sqlseed/issues
+Author-email: SunBo <1443584939@qq.com>
+License-Expression: AGPL-3.0-or-later
+License-File: LICENSE
+Keywords: data-generation,database,seed,sqlite,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: faker>=30.0
+Requires-Dist: pluggy>=1.3
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rstr>=3.2
+Requires-Dist: simpleeval>=1.0
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: sqlglot>=25.0
+Requires-Dist: structlog>=24.0
+Requires-Dist: typing-extensions>=4.4
+Provides-Extra: all
+Requires-Dist: mimesis>=18.0; extra == 'all'
+Requires-Dist: psycopg[binary]>=3.0; extra == 'all'
+Requires-Dist: sqlseed-cli<0.3,>=0.2.4.dev0; extra == 'all'
+Requires-Dist: testcontainers>=4.0; extra == 'all'
+Requires-Dist: tqdm>=4.66; extra == 'all'
+Provides-Extra: cli
+Requires-Dist: sqlseed-cli<0.3,>=0.2.4.dev0; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: import-linter>=2.0; extra == 'dev'
+Requires-Dist: mutmut<3,>=2.5; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: psycopg[binary]>=3.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-benchmark>=4.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: sqlseed-cli<0.3,>=0.2.4.dev0; extra == 'dev'
+Requires-Dist: testcontainers>=4.0; extra == 'dev'
+Requires-Dist: tqdm>=4.66; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocs-static-i18n<2,>=1.3.1; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
+Provides-Extra: mimesis
+Requires-Dist: mimesis>=18.0; extra == 'mimesis'
+Provides-Extra: notebook
+Requires-Dist: tqdm>=4.66; extra == 'notebook'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.0; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/sunbos/sqlseed/main/docs/assets/brand/sqlseed-wordmark-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/sunbos/sqlseed/main/docs/assets/brand/sqlseed-wordmark-light.svg">
+    <img src="https://raw.githubusercontent.com/sunbos/sqlseed/main/docs/assets/brand/sqlseed-wordmark-light.svg" width="256" height="80" alt="sqlseed">
+  </picture>
+</h1>
+
+**Test data for SQLite and PostgreSQL, from your existing schema.**
+
+[English](https://github.com/sunbos/sqlseed/blob/main/README.md) · [简体中文](https://github.com/sunbos/sqlseed/blob/main/README.zh-CN.md)
+
+[![PyPI](https://img.shields.io/pypi/v/sqlseed.svg)](https://pypi.org/project/sqlseed/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-3776ab.svg)](https://www.python.org/downloads/)
+[![CI](https://github.com/sunbos/sqlseed/actions/workflows/ci.yml/badge.svg)](https://github.com/sunbos/sqlseed/actions/workflows/ci.yml)
+[![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](https://github.com/sunbos/sqlseed/blob/main/LICENSE)
+
+[Quick start](#quick-start) · [Web workbench](#web-workbench) · [CLI](#command-line) · [MCP](#mcp-tools) · [Documentation](https://sunbos.github.io/sqlseed/)
+
+</div>
+
+sqlseed fills existing database tables with generated test data. Start with inferred
+rules for common columns such as names and email addresses, then specify the ranges,
+choices, or relationships your application needs in Python or YAML.
+
+- **Prepare development and test databases:** generate rows in batches and coordinate supported foreign-key dependencies.
+- **Keep data rules reusable:** save configuration, preview samples, and use a seed to reproduce a run under the same conditions.
+- **Choose your interface:** use the Python API, terminal, browser, or MCP tools. The Core runs offline; AI assistance is optional.
+
+## Choose an entry point
+
+Requires **Python 3.10+**. Use a virtual environment and install the package for the
+interface you want; you do not need to install every row below. `sqlseed` is the
+offline Core library. The other four packages provide optional interfaces and
+capabilities, and install Core as a dependency.
+
+This README describes version 0.2.6. Check [Releases](https://github.com/sunbos/sqlseed/releases)
+for publication status; the [source installation guide](https://sunbos.github.io/sqlseed/guide/#source-installation)
+covers unpublished candidates.
+
+| Package and purpose | Install | Start here |
+| --- | --- | --- |
+| **Core — `sqlseed`**: infer rules, preview, and generate data through Python or configuration files | `python -m pip install sqlseed` | [Quick start](#quick-start) |
+| **Web — `sqlseed-web`**: edit rules, inspect relationships, preview, and review runs in a browser | `python -m pip install sqlseed-web` | [Web workbench](#web-workbench) |
+| **CLI — `sqlseed-cli`**: inspect schema, fill tables, and save or replay configurations from a terminal | `python -m pip install sqlseed-cli` | [Command line](#command-line) |
+| **AI — `sqlseed-ai`**: use a configured model to suggest or repair generation rules | `python -m pip install sqlseed-ai` | [AI assistance](#optional-ai-assistance) |
+| **MCP — `mcp-server-sqlseed`**: expose rule-driven YAML generation and data filling to an MCP client | `python -m pip install mcp-server-sqlseed` | [MCP tools](#mcp-tools) |
+
+Web and the rule-driven MCP server can each be installed without CLI or AI.
+Installing AI also installs CLI and adds its AI commands. The Core `sqlseed[all]`
+extra groups optional dependencies; it does not install all four packages above.
+
+On macOS, start with the [macOS setup guide](https://sunbos.github.io/sqlseed/macos/)
+for native Python, virtual environments, Intel dependencies, and desktop MCP paths.
+
+Faker is included with Core and is selected explicitly in the examples below.
+Mimesis is optional: install it with `python -m pip install 'sqlseed[mimesis]'`.
+For an older installation, see the [upgrade guide](https://sunbos.github.io/sqlseed/migration/).
+
+## Quick start
+
+Install Core in your Python environment:
+
+```bash
+python -m pip install sqlseed
+```
+
+Save the following as `demo.py` in a new directory and run `python demo.py`.
+It creates a SQLite table and adds 100 users. It needs no repository checkout,
+API key, or external database server.
+
+```python
+import sqlite3
+from contextlib import closing
+
+import sqlseed
+
+with closing(sqlite3.connect("demo.db")) as conn:
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS users (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            name TEXT NOT NULL,
+            email TEXT NOT NULL
+        )
+    """)
+    conn.commit()
+
+result = sqlseed.fill(
+    "demo.db",
+    table="users",
+    count=100,
+    provider="faker",
+    seed=42,
+)
+print(result.count, result.errors)  # 100 []
+```
+
+Names and email addresses are inferred from the columns. The database assigns the
+primary keys. Each run appends another 100 rows; it does not clear the table.
+Check both `result.count` and `result.errors` after generation.
+
+Since version 0.2.5, `sqlseed.FillOptions(provider="faker", seed=42)`
+can share generation settings across `fill(..., options=settings)` calls.
+Existing individual keywords remain supported; see the
+[Python API reference](https://sunbos.github.io/sqlseed/api/#filloptions).
+
+To inspect samples without writing rows:
+
+```python
+import sqlseed
+
+rows = sqlseed.preview("demo.db", table="users", count=3, provider="faker")
+for row in rows:
+    print(row)
+```
+
+### Reuse your rules with YAML
+
+For the same `demo.db`, save this as `generate.yaml`. Here the column generators
+are explicit, so the rules can be reviewed and reused:
+
+```yaml
+db_path: demo.db
+provider: faker
+locale: en_US
+tables:
+  - name: users
+    count: 100
+    seed: 42
+    columns:
+      - name: name
+        generator: name
+      - name: email
+        generator: email
+```
+
+Run it from the same directory:
+
+```python
+import sqlseed
+
+for result in sqlseed.fill_from_config("generate.yaml"):
+    print(result.count, result.errors)
+```
+
+The [configuration guide](https://sunbos.github.io/sqlseed/guide/#yaml-configuration)
+covers value ranges, weighted choices, derived columns, and relationships between
+tables. See the [generator reference](https://sunbos.github.io/sqlseed/guide/#generators)
+for supported names and parameters.
+
+## Web workbench
+
+```bash
+python -m pip install sqlseed-web
+sqlseed-web
+```
+
+Open **[http://127.0.0.1:8630](http://127.0.0.1:8630)** and connect to an existing
+SQLite or PostgreSQL database, such as the `demo.db` above.
+For PostgreSQL, install the driver in the same Python environment before starting
+the workbench: `python -m pip install 'sqlseed[postgres]'`.
+The `sqlseed-web` command is installed with the package; no custom startup script
+or source checkout is required.
+
+Select the tables to generate, set row counts, and edit column rules. Use the
+relationship view to inspect foreign keys and check dependencies. Preview samples
+without writing to the database, then review the generation plan and confirm the
+write. Save configurations for reuse and inspect the results in run history.
+
+![English Web workbench relationship view for a fictional SQLite order demo](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-en-light.png)
+
+The actual 0.2.5 interface with the repository's
+[fictional SQLite order example](https://github.com/sunbos/sqlseed/tree/main/examples/order_workflow).
+[Open the full-size PNG](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-en-light.png)
+or [see the read-only sample preview in the dark theme](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-en-dark.png).
+Previewed samples are generated for inspection and are not inserted into the database.
+
+Since version 0.2.5, the workbench offers Simplified Chinese and English from the top
+bar. Changing the interface language keeps your edits and does not change the
+data language and region used for generation. Light and dark themes are also available.
+
+Manual editing, preview, and generation work without AI. To add the optional
+configuration assistant, install AI in the same environment:
+
+```bash
+python -m pip install 'sqlseed-web[ai]'
+```
+
+Then configure a model service in settings. AI suggestions remain available for
+review before you apply them; generation uses the rules you have confirmed.
+See the [Web guide](https://sunbos.github.io/sqlseed/web-workbench/) for connection
+settings, optional components, and deployment requirements.
+
+## Command line
+
+Install the CLI, then use the database created in the quick start:
+
+```bash
+python -m pip install sqlseed-cli
+sqlseed inspect demo.db --table users --show-mapping
+sqlseed preview demo.db -t users -n 5 --provider faker
+sqlseed fill demo.db -t users -n 100 --provider faker --no-ai
+```
+
+Use `sqlseed --help` or `sqlseed <command> --help` for options. The CLI also supports
+configuration templates, configuration snapshots, and replay; see the
+[CLI reference](https://sunbos.github.io/sqlseed/guide/#cli-reference).
+Installing Core alone provides the Python API; `sqlseed-cli` supplies the `sqlseed`
+command.
+
+## PostgreSQL
+
+Install the PostgreSQL driver extra:
+
+```bash
+python -m pip install 'sqlseed[postgres]'
+```
+
+For an existing database and table, supply the connection URL explicitly:
+
+```python
+import sqlseed
+
+result = sqlseed.fill(
+    url="postgresql+psycopg://user:password@localhost:5432/app",
+    table="users",
+    count=100,
+    provider="faker",
+)
+print(result.count, result.errors)
+```
+
+Do not pass both a SQLite path and `url`. For supported foreign-key layouts and
+entry-point differences, read the [support scope](https://sunbos.github.io/sqlseed/maintainable-release/).
+
+## Optional AI assistance
+
+`sqlseed-ai` adds commands for suggesting generation rules and repairing existing
+configurations. Install it, then configure a model backend using the
+[AI setup guide](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/README.md).
+
+| Command | Use it to… |
+| --- | --- |
+| `sqlseed ai-suggest` | Suggest rules for one table |
+| `sqlseed ai-analyze` | Analyze selected tables or a database |
+| `sqlseed auto-heal` | Repair rules in an existing, structurally valid YAML configuration |
+
+The analysis and repair workflow can infer rules for supported CHECK patterns,
+such as enums, ranges, and relationships between columns. Other constraints can
+require explicit rules or model suggestions; this is not a solver for arbitrary
+SQL CHECK expressions. Review the candidate configuration and verify the data
+before relying on it.
+
+See the [AI command reference](https://sunbos.github.io/sqlseed/guide/#ai-suggest)
+and [backend and validation guide](https://sunbos.github.io/sqlseed/gemma4-integration/).
+
+## MCP tools
+
+For rule-driven tools that need no model service, install and start the stdio server:
+
+```bash
+python -m pip install mcp-server-sqlseed
+mcp-server-sqlseed
+```
+
+Configure your MCP client to launch `mcp-server-sqlseed` from that environment;
+use the executable's absolute path if the client does not inherit its PATH.
+The server provides `sqlseed_generate_yaml` to prepare rules for review and
+`sqlseed_execute_fill` to write data to the specified existing table. Check the
+returned `count` and `errors` after a fill.
+
+Model-assisted tools use a separate stdio server supplied by the AI package:
+
+```bash
+python -m pip install 'sqlseed-ai[mcp]'
+mcp-server-sqlseed-ai
+```
+
+Configure the AI backend for that process using the [AI setup guide](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/README.md).
+It provides AI YAML suggestions, table analysis, an analyze-and-fill tool, and
+model/backend availability information. Installing AI does not add these tools
+to the rule-driven server; configure both processes if you want both tool sets.
+See [MCP setup](https://sunbos.github.io/sqlseed/guide/#mcp-server) for client
+configuration and tool details.
+
+## Working with your own database
+
+- **Create tables first.** sqlseed reads existing schemas. Required parent rows must already exist or be generated earlier in the configuration.
+- **Check the outcome.** A failed Core or CLI run can retain earlier committed batches. Inspect `count` and `errors` before retrying.
+- **Keep reproducibility conditions consistent.** A seed alone does not guarantee identical output across dependency versions, providers, configurations, or initial database contents.
+
+Complex CHECK constraints and composite foreign keys have database-specific limits.
+See [support and maintenance](https://sunbos.github.io/sqlseed/maintainable-release/)
+for the supported scope and write behavior.
+
+## Documentation
+
+| Next step | Read |
+| --- | --- |
+| Configure generators, expressions, and multi-table data | [User guide](https://sunbos.github.io/sqlseed/guide/) |
+| Use `fill`, `FillOptions`, `preview`, `connect`, `fill_from_config`, or `load_config` | [Python API reference](https://sunbos.github.io/sqlseed/api/) |
+| Try a complete multi-table example | [Order workflow](https://github.com/sunbos/sqlseed/tree/main/examples/order_workflow) |
+| Understand package boundaries and extension hooks | [Architecture](https://sunbos.github.io/sqlseed/architecture/) |
+| Upgrade an existing installation | [Migration guide](https://sunbos.github.io/sqlseed/migration/) |
+| Check published changes | [Releases](https://github.com/sunbos/sqlseed/releases) |
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/sunbos/sqlseed/blob/main/CONTRIBUTING.md) for
+source installation, development checks, and contribution guidelines. Report bugs
+with a minimal schema, your configuration, package versions, and the full error in
+[GitHub Issues](https://github.com/sunbos/sqlseed/issues).
+
+## License
+
+[AGPL-3.0-or-later](https://github.com/sunbos/sqlseed/blob/main/LICENSE).