云数据库 SQL Server COS Bulk Insert

本使用手册为您介绍一套用于云数据库 SQL Server 的大数据量导入解决方案，通过两个核心存储过程，实现从腾讯云对象存储 COS 高效批量导入数据到数据库表的完整工作流。
TencentSp_DownloadFromCOS — 从 COS 下载文件
功能概述
从腾讯云对象存储 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_BulkInsertFromFile — 从本地文件 BULK INSERT 导入数据
功能概述
将本地文件（通常由 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 抛出错误，不返回结果集。
使用示例
示例1：基本 CSV 导入（跳过表头）
USE monitor;
EXEC dbo.TencentSp_BulkInsertFromFile
    @FileName        = 'sales_2024.csv',
    @TargetDB        = 'mydb',
    @TargetSchema    = 'dbo',
    @TargetTable     = 'SalesData',
    @FieldTerminator = ',',
示例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行
示例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;
示例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';
安全机制
参数非空校验：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>\\ 读取文件。
存在性校验：执行前检查源文件和目标表是否存在。
审计日志
每次调用记录到 monitor.dbo.BulkInsertLog 表，包含调用者、文件名、目标库表、导入行数、状态、错误信息等。超过180天的日志自动清理。
完整工作流示例（下载 + 导入）
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;
四、注意事项
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），因为下载只保留最后的文件名。
部署/卸载：使用 deploy_cos_bulk_insert.sql 部署，undeploy_cos_bulk_insert.sql 卸载（会删除所有相关对象和日志表）。
五、审计日志查询
-- 查看最近 20 条下载日志
SELECT TOP 20 * FROM monitor.dbo.CosDownloadLog ORDER BY ID DESC;
﻿
-- 查看最近 20 条导入日志
SELECT TOP 20 * FROM monitor.dbo.BulkInsertLog ORDER BY ID DESC;
﻿
-- 查看某用户的下载记录
SELECT * FROM monitor.dbo.CosDownloadLog WHERE LoginName = 'your_login';
﻿
-- 查看失败的导入记录
SELECT * FROM monitor.dbo.BulkInsertLog WHERE Status = 'Failed' ORDER BY InsertTime DESC;

COS Bulk Insert 存储过程使用手册

本页目录：

TencentSp_DownloadFromCOS — 从 COS 下载文件

功能概述

存储过程位置

参数说明

返回结果

使用示例

示例1：基本下载

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

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

安全机制

审计日志

TencentSp_BulkInsertFromFile — 从本地文件 BULK INSERT 导入数据

功能概述

存储过程位置

参数说明

必选参数

可选参数

返回结果

使用示例

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

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

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

示例4：使用格式化文件

安全机制

审计日志

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

四、注意事项

五、审计日志查询

参数	类型	默认值	必填	说明
@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。