云数据库 SQL Server COS Bulk Insert 存储过程使用手册

二、功能概述

从腾讯云对象存储 COS 下载指定文件到 SQL Server 实例本地磁盘（D:\\dow_file\\<port>\\），供后续 BULK INSERT 使用。

三、存储过程位置

USE monitor;EXEC dbo.TencentSp_DownloadFromCOS …;

四、参数说明

参数	类型	默认值	必填	说明
@BucketName	VARCHAR(200)	NULL	是（非 CleanupOnly 模式时）	COS 存储桶名称（含 AppId），如 mybucket-1258888888。
@FileName	VARCHAR(500)	NULL	是（非 CleanupOnly 模式时）	COS 对象路径，如 data/test.csv。下载后只保留文件名部分。
@Region	VARCHAR(100)	NULL	是（非 CleanupOnly 模式时）	COS 地域，如 ap-guangzhou、ap-shanghai。
@OverwriteFile	INT	0	否	是否覆盖已存在的同名本地文件。0表示不覆盖（文件存在则跳过）。1表示强制覆盖重新下载。
@ExpectedFileSizeMB	INT	NULL	否	预期文件大小（MB）。设置后会检查 D 盘剩余空间是否充足。为 NULL 时默认要求至少有500MB剩余空间。
@CleanupOnly	BIT	0	否	仅执行清理模式。1表示只清理本地过期文件，不下载。
@CleanupDays	INT	1	否	清理超过指定天数的本地文件。0表示删除所有文件。

五、返回结果

字段	说明
DownloadStatus	下载状态。Success：成功。AlreadyExists：文件已存在未覆盖。
LocalFilePath	文件下载到本地的完整路径，如 D:\\dow_file\\58001\\test.csv。

失败时通过 RAISERROR 抛出错误，不返回结果集。

七、示例1：基本下载

USE monitor;EXEC dbo.TencentSp_DownloadFromCOS @BucketName = 'mybucket-1258888888', @FileName = 'data/sales_2024.csv', @Region = 'ap-guangzhou';

八、示例2：强制覆盖下载 + 磁盘空间检查

EXEC dbo.TencentSp_DownloadFromCOS @BucketName = 'mybucket-1258888888', @FileName = 'data/large_file.csv', @Region = 'ap-guangzhou', @OverwriteFile = 1, @ExpectedFileSizeMB = 2048; — 预期文件约2GB，检查磁盘空间

九、示例3：仅清理过期文件（不下载）

— 清理超过 7 天的本地文件EXEC dbo.TencentSp_DownloadFromCOS @CleanupOnly = 1, @CleanupDays = 7;– 清理所有本地文件EXEC dbo.TencentSp_DownloadFromCOS @CleanupOnly = 1, @CleanupDays = 0;

十、安全机制

·参数非空校验：BucketName / FileName / Region 不能为空。

·长度限制：BucketName ≤ 100，FileName ≤ 500，Region ≤ 50。

·字符白名单：BucketName 仅允许[a-zA-Z0-9.-]；FileName 仅允许[a-zA-Z0-9._/ -]；Region 仅允许[a-zA-Z0-9-]。

·路径穿越防护：FileName 禁止包含..。

·扩展名校验：FileName 必须有文件扩展名。

·固定下载目录：文件只能下载到 D:\\dow_file\\<port>\\，不可自定义路径。

·磁盘空间检查：下载前检查 D 盘剩余空间。

十一、审计日志

每次调用记录到 monitor.dbo.CosDownloadLog 表，包含调用者、桶名、文件、状态、错误信息等。超过180天的日志自动清理。

十三、功能概述

将本地文件（通常由 TencentSp_DownloadFromCOS 下载）通过 BULK INSERT 批量导入到用户指定的数据库表中。

十四、存储过程位置

USE monitor;EXEC dbo.TencentSp_BulkInsertFromFile …;

十六、必选参数

参数	类型	说明
@FileName	VARCHAR(500)	源文件名（不含路径），相对于 D:\\dow_file\\<port>\\ 目录。
@TargetDB	SYSNAME	目标数据库名（禁止系统库：master、model、msdb、tempdb、monitor）。
@TargetSchema	SYSNAME	目标 Schema 名，通常为 dbo。
@TargetTable	SYSNAME	目标表名（表必须已存在）。

十七、可选参数

参数	类型	默认值	说明
@FieldTerminator	VARCHAR(10)	,	字段分隔符。CSV 文件用,，TSV 文件用 \\t。
@RowTerminator	VARCHAR(10)	\\n	行终止符。Linux 格式文件用 \\n，Windows 格式用 \\r\\n。
@FirstRow	INT	1	从第几行开始导入。设为2可跳过 CSV 表头行。
@LastRow	INT	NULL	导入到第几行结束。NULL 表示导入全部。
@Format	VARCHAR(10)	NULL	文件格式，如 CSV。
@CodePage	VARCHAR(20)	NULL	代码页，如65001（UTF-8）、ACP（系统默认）。
@DataFileType	VARCHAR(20)	NULL	数据文件类型：char、native、widechar、widenative。
@FieldQuote	VARCHAR(5)	NULL	字段引号字符，如 "（配合 FORMAT='CSV' 使用）。
@MaxErrors	INT	0	最大允许错误数。超过此数则 BULK INSERT 失败回滚。
@BatchSize	INT	NULL	每批次导入行数。NULL 表示一次性导入全部。
@KeepNulls	BIT	0	1表示空列保持 NULL（不使用表的默认值）。
@KeepIdentity	BIT	0	1表示保留文件中的 IDENTITY 列值。
@TabLock	BIT	0	1表示导入期间对表加锁（提高大批量导入性能）。
@CheckConstraints	BIT	0	1表示导入时检查约束。
@FireTriggers	BIT	0	1表示导入时触发 INSERT 触发器。
@FormatFile	VARCHAR(500)	NULL	格式化文件名（相对于 D:\\dow_file\\<port>\\）。指定后 FieldTerminator 和 RowTerminator 将被忽略。
@OrderHint	VARCHAR(500)	NULL	ORDER 提示，如 col1 ASC, col2 DESC，与聚集索引匹配可提升性能。
@ErrorFile	VARCHAR(500)	NULL	错误行输出文件名（相对于 D:\\dow_file\\<port>\\）。

十八、返回结果

字段	说明
RowsImported	成功导入的行数。

失败时通过 RAISERROR 抛出错误，不返回结果集。

20、示例1：基本 CSV 导入（跳过表头）

USE monitor;EXEC dbo.TencentSp_BulkInsertFromFile @FileName = 'sales_2024.csv', @TargetDB = 'mydb', @TargetSchema = 'dbo', @TargetTable = 'SalesData', @FieldTerminator = ',',

21、示例2：大文件高性能导入

EXEC dbo.TencentSp_BulkInsertFromFile @FileName = 'big_data.csv', @TargetDB = 'mydb', @TargetSchema = 'dbo', @TargetTable = 'BigTable', @FieldTerminator = ',', @FirstRow = 2, @TabLock = 1, — 表级锁提升性能 @BatchSize = 50000, — 每5万行一批 @MaxErrors = 10; — 容错10行

22、示例3：TSV 文件 + 保留 NULL + IDENTITY

EXEC dbo.TencentSp_BulkInsertFromFile @FileName = 'export.tsv', @TargetDB = 'mydb', @TargetSchema = 'dbo', @TargetTable = 'ImportTable', @FieldTerminator = '\\t', @RowTerminator = '\\r\\n', @FirstRow = 1, @KeepNulls = 1, @KeepIdentity = 1;

23、示例4：使用格式化文件

— 先将格式化文件上传到 COS 并下载EXEC dbo.TencentSp_DownloadFromCOS @BucketName = 'mybucket-1258888888', @FileName = 'fmt/myformat.fmt', @Region = 'ap-guangzhou';– 使用格式化文件导入EXEC dbo.TencentSp_BulkInsertFromFile @FileName = 'data.dat', @TargetDB = 'mydb', @TargetSchema = 'dbo', @TargetTable = 'MyTable', @FormatFile = 'myformat.fmt';

24、安全机制

·参数非空校验：FileName / TargetDB / TargetSchema / TargetTable 不能为空。

·长度限制：FileName ≤ 500，TargetDB / TargetSchema / TargetTable ≤ 128。

·字符白名单：FileName 仅允许[a-zA-Z0-9._/ -]；TargetDB / TargetSchema / TargetTable 仅允许[a-zA-Z0-9_]。

·路径穿越防护：FileName / FormatFile / ErrorFile 禁止包含..。

·系统库黑名单：禁止向 master、model、msdb、tempdb、monitor 导入。

·固定源文件目录：只能从 D:\\dow_file\\<port>\\ 读取文件。

·存在性校验：执行前检查源文件和目标表是否存在。

25、审计日志

每次调用记录到 monitor.dbo.BulkInsertLog 表，包含调用者、文件名、目标库表、导入行数、状态、错误信息等。超过180天的日志自动清理。

26、完整工作流示例（下载 + 导入）

USE monitor;– 步骤 1：从 COS 下载 CSV 文件EXEC dbo.TencentSp_DownloadFromCOS @BucketName = 'mybucket-1258888888', @FileName = 'data/sales_2024.csv', @Region = 'ap-guangzhou';– 步骤 2：将文件导入用户数据库表EXEC dbo.TencentSp_BulkInsertFromFile @FileName = 'sales_2024.csv', — 注意：只需文件名，不含路径 @TargetDB = 'mydb', @TargetSchema = 'dbo', @TargetTable = 'SalesData', @FieldTerminator = ',', @FirstRow = 2;– 步骤 3（可选）：清理本地文件EXEC dbo.TencentSp_DownloadFromCOS @CleanupOnly = 1, @CleanupDays = 0;

27、四、注意事项

·COS 访问权限：COS 存储桶需开启公有读或设置匿名访问，因为下载使用 wget 匿名请求。

·目标表需预先创建：BULK INSERT 不会自动创建表，需提前在目标库中建好表结构。

·文件编码：COS 下载的文件通常为 Linux 换行格式（\\n），@RowTerminator 默认已设为 \\n。如果是 Windows 格式文件，需手动设置 @RowTerminator = '\\r\\n'。

·磁盘空间：下载大文件前建议设置 @ExpectedFileSizeMB 参数，避免磁盘空间不足。

·@FileName 参数差异：TencentSp_DownloadFromCOS 的 @FileName 是 COS 对象完整路径（如 data/test.csv）；TencentSp_BulkInsertFromFile 的 @FileName 仅为文件名（如 test.csv），因为下载只保留最后的文件名。