sqlseed 0.2.4__tar.gz → 0.2.5__tar.gz

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

@@ -9,6 +9,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.5}/CHANGELOG.zh-CN.md

@@ -9,6 +9,57 @@
 
 ## [Unreleased]
 
+## [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.5/PKG-INFO

@@ -0,0 +1,326 @@
+Metadata-Version: 2.5
+Name: sqlseed
+Version: 0.2.5
+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: 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) · [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. Interface packages
+install Core as a dependency.
+
+This README describes version 0.2.5. 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.
+
+| I want to… | Install | Start here |
+| --- | --- | --- |
+| Generate data from Python | `python -m pip install sqlseed` | [Quick start](#quick-start) |
+| Use a browser | `python -m pip install sqlseed-web` | [Web workbench](#web-workbench) |
+| Work in a terminal | `python -m pip install sqlseed-cli` | [Command line](#command-line) |
+| Ask a model to suggest or repair rules | `python -m pip install sqlseed-ai` | [AI assistance](#optional-ai-assistance) |
+| Use rule-driven tools from an MCP client | `python -m pip install mcp-server-sqlseed` | [MCP setup](https://sunbos.github.io/sqlseed/guide/#mcp-server) |
+
+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.
+
+In 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)**, connect to an existing database
+(such as the `demo.db` above), select tables, edit rules, preview, and generate.
+The `sqlseed-web` command is installed with the package; no custom startup script
+or source checkout is required.
+
+The workbench includes saved configurations, relationship views, and run history.
+AI is optional, and manual editing, preview, and generation work without it.
+Version 0.2.5 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.
+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, 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/).
+For model-assisted MCP tools, use the separate server provided by `sqlseed-ai[mcp]`;
+[MCP setup](https://sunbos.github.io/sqlseed/guide/#mcp-server) explains both servers.
+
+## 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).