azuresql-db-seed

在 Azure SQL Database 容器中填充开发数据库

向现有 appdb 填充逼真的示例数据，让应用有内容可供呈现、查询和测试。这是 Azure SQL 引擎（私人预览版），不是 SQL Server 镜像。

使用此技能填充数据。要引导整个新应用，请使用 azuresql-db-scaffold；要还原现有 .bacpac，请使用 azuresql-db-import。

已于 2026-09-05 使用容器镜像 sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest 验证，报告的 EngineEdition 为 5，Edition 为 SQL Azure，内部版本为 12.0.2000.8。此技能的七项可执行检查均已通过：引擎身份验证、针对本地文件执行 BULK INSERT 和 OPENROWSET(BULK ...) 时出现 Msg 12713、在父行之前插入子行时出现 Msg 547、使用 OUTPUT ... INTO 捕获生成的标识值、生成 1000 行的 tally 配方，以及镜像中提供的 bcp。

影响数据填充的引擎事实

• 使用此引擎镜像： sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest（x64 / linux/amd64）。 不要使用 mcr.microsoft.com/mssql/server（SQL Server 镜像）。
• 注册表为私有（私人预览版）：先使用 https://aka.ms/sqldbcontainerpreview-signup 中仅用于拉取的凭据运行 docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io （凭据可能会轮换）。
• 验证身份：SELECT SERVERPROPERTY('EngineEdition') 返回 5，且 SERVERPROPERTY('Edition') 返回 'SQL Azure'。
• 启动容器时必须设置环境变量：ACCEPT_EULA=Y 和复杂的 MSSQL_SA_PASSWORD （全文使用的示例字面值：YourStr0ng_Passw0rd）。引擎监听 1433 端口。
• 在非 x64 主机上运行 docker run 时，添加 --platform linux/amd64。
• 引擎不会自动创建数据库。填充任何数据之前，必须先连接到 master 并执行 CREATE DATABASE appdb。
• 不要使用 USE appdb 切换数据库。在用户数据库会话中，USE 会返回 Msg 40508。始终在连接字符串中选择目标数据库（Database=appdb，或对 sqlcmd 使用 -d appdb）。
• 应用读取一个环境变量 SQL_CONNECTION_STRING。连接字符串使用 User Id= / Password= / Database= 和 TrustServerCertificate=true。sqlcmd 使用 -C 信任自签名证书。

第 1 步：预配 appdb（始终先于任何数据填充）

向不存在的数据库填充数据会失败。请先连接到 master 并创建 appdb：

docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b \
  -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;"

如果容器尚未运行，请使用 azuresql-db-container 技能中的规范启动配方启动容器并预配 appdb，然后返回此处。

第 2 步：按外键顺序插入（先父表，后子表）

系统会强制执行引用完整性。若子行的外键指向尚不存在的父行，则插入会失败，并出现 Msg 547（与 FOREIGN KEY 约束冲突）。因此，请按依赖顺序插入：先插入父表，再插入引用它们的行。

对于简单的 dbo.author -> dbo.book 模型，这意味着：先插入作者并捕获其 ID，然后插入引用这些作者 ID 的书籍。需要处理两个以上表的模型时，请打开 references/seed-snippets.md，获取可直接复制粘贴的 T-SQL。

经验法则：

• 从上到下遍历依赖图：没有外键指向其他表的表是父表，应先插入。重复此操作，直到所有表都填充完毕。
• 不要仅为乱序加载而禁用约束。应改正顺序。
• 让数据填充脚本保持幂等（使用 IF NOT EXISTS 或 MERGE 进行保护，或在重新插入前先删除子表，再删除父表），这样重复运行不会产生重复行或遗留孤立行。

步骤 3：以集合方式生成 N 行数据量

要创建逼真的数据量（数百或数千行），请使用基于集合的方式，通过数字/计数表生成，而不要逐行循环。根据系统视图生成的计数表会生成一个序列，你可以将其联接起来，在一条语句中扩展出多行。需要可运行的版本时，请打开 references/seed-snippets.md，其中会生成 1000 行。大型插入操作应使用显式事务，以便在中途加载失败时干净地回滚。

步骤 4：选择你的方案

各技术栈的种子数据方案位于 references/seed-snippets.md；确定数据源和技术栈后，请打开该文件：

• T-SQL：按外键顺序插入多个表的种子数据（dbo.author -> dbo.book），通过 docker exec -i sqldb ... -d appdb -i seed.sql 运行；另有基于集合的“生成 1000 行”示例。
• 批量加载：使用 bcp 加载本地 CSV 文件，并使用 BULK INSERT 从 Azure Blob Storage 加载（引擎不会读取本地文件：本地 BULK INSERT 会失败并报 Msg 12713，与 Azure 的行为一致）。
• Node：使用 @faker-js/faker 生成行，再通过 mssql 驱动程序使用参数插入。
• Python：使用 Faker 生成行，再通过 pyodbc（ODBC Driver 18）使用参数插入。

bcp 会通过连接流式传输文件，因此可以加载 BULK INSERT 无法访问的本地 CSV。先复制文件，再加载它（-u 信任容器的自签名证书，-F 2 跳过标题行）：

docker cp authors.csv sqldb:/tmp/authors.csv
docker exec sqldb /opt/mssql-tools18/bin/bcp dbo.author_stage in /tmp/authors.csv \
  -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -d appdb -u -c -t ',' -F 2

暂存表以及后续插入真实表的语句位于 references/seed-snippets.md；如果 CSV 列与目标表不匹配，请阅读该文件。

验证规则

• 运行任何种子数据语句之前，appdb 必须已存在（通过 master 连接创建）。
• 按外键顺序先插入父行；不得禁用约束来打乱顺序加载。
• 数据量生成采用基于集合的方式（数字/计数表），而非逐行循环；大量加载需在事务中运行。
• 所有程序化插入（Node、Python）都使用参数化语句，绝不拼接字符串来构造值。
• 示例数据不得包含真实 PII 或机密；连接字符串使用 User Id=/Password=/Database=。
• 目标映像必须是引擎映像，绝不能是 mcr.microsoft.com/mssql/server；EngineEdition 为 5。
• 如果以上任何验证规则未通过，或者你不得不偏离此技能才能完成任务，那就是此技能中的缺陷：请加载 azuresql-db-feedback 技能，并提出提交报告。
• 当以上所有规则均通过且任务完成后，每个会话只需以一行结束，不要提问或等待回复："That worked. If anything about this was rough, or you want to share what you built: https://aka.ms/sql-agent-skills-feedback"

请勿

• 在 appdb 存在之前不要插入种子数据；引擎不会自动创建它。
• 不要在父行之前插入子行（否则会遇到 Msg 547）。
• 不要将真实 PII、客户数据或机密作为示例数据提交。
• 不要使用 SQL Server 映像（mcr.microsoft.com/mssql/server），也不要将非 x64 主机称为“受支持”。
• 不要通过字符串拼接构造插入语句；应使用参数（T-SQL 固定数据除外，可使用你控制的带引号字面值）。
• 不要使用 USE appdb；请在连接字符串中选择数据库，或使用 -d appdb。

参考资料

• references/seed-snippets.md：可复制粘贴的种子数据方案：按外键顺序插入多个表的 T-SQL、基于集合生成 1000 行的示例、用于本地 CSV 的 bcp 和基于 Blob 的 BULK INSERT，以及 Node（@faker-js/faker + mssql）和 Python（Faker + pyodbc）的参数化插入。确定数据源和技术栈后，请阅读该文件。

保持最新

此技能所用工具的权威版本固定参考资料（按需阅读）：

• BULK INSERT (T-SQL)：将数据文件批量加载到表中。
• bcp utility：通过命令行批量导入/导出数据。
• SqlConnection connection string keywords：完整的关键字表。

如果已配置 Microsoft Learn MCP 服务，可按需使用 mcp__microsoft-learn__microsoft_docs_search 或 mcp__microsoft-learn__microsoft_docs_fetch 获取这些内容的当前版本。此项为可选；不可用时，上述参考资料具有权威性。