dlt 目标接入指南使用 data load tool (dlt) 将数据加载到 Microsoft SQL Server【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dltMicrosoft SQL Server下文简称 MS SQL是 data load tooldlt官方支持的关系型数据仓库目标之一本文以仓库文档 mssql.md 为核心骨架结合dlt/destinations/impl/mssql/下的源码实现与测试用例系统讲解从环境准备、凭据配置到数据加载INSERT 与 parquet/ADBC 两种路径的完整流程。读完本文你将能够独立完成dlt流水线到 MS SQL 的初始化、连接配置、增量与全量加载并理解其底层 ODBC 连接、类型映射与写处置策略的工作原理。安装 dlt 与 MS SQL 依赖MS SQL 目标所需的全部能力随dlt的mssqlextra 一同分发安装命令为pip install dlt[mssql]该 extra 会拉取 SQL Server 客户端pyodbc所需的所有依赖。在源码中目标实现位于 dlt/destinations/impl/mssql/ 目录包含factory.py目标工厂与能力声明、configuration.py凭据与配置模型、mssql.py加载作业实现、sql_client.pypyodbc 数据库客户端四个核心模块。环境准备PrerequisitesMicrosoft ODBC Driver for SQL Server 必须单独安装它无法随dlt的 Python 依赖一起分发。支持的驱动版本有两个与源码 configuration.py 中SUPPORTED_DRIVERS常量完全一致ODBC Driver 18 for SQL ServerODBC Driver 17 for SQL Serverdlt在运行时会对驱动做两件事自动探测若不显式指定驱动MsSqlCredentials._get_driver()会调用pyodbc.drivers()枚举系统已安装驱动并优先挑选 18 版源码 configuration.py。若两者均未安装会抛出SystemConfigurationException并提示先安装ODBC Driver 18。白名单校验在on_resolved()中若配置的驱动不在白名单内例如旧版ODBC Driver 13加载会直接失败参见测试 test_mssql_configuration.py 中对不支持的 Driver 13 的断言。你也可以在配置中显式指定驱动名。创建流水线从 dlt init 到首次加载官方推荐的四步上手流程如下。1. 初始化一个加载到 MS SQL 的流水线项目dlt init chess mssql该命令会以chess示例源为模板生成流水线脚本与目录结构。2. 安装依赖pip install -r requirements.txt等价地也可以直接安装pip install dlt[mssql]3. 在.dlt/secrets.toml中填入凭据。分节形式的示例替换为你的真实数据库连接信息[destination.mssql.credentials] database dlt_data username loader password password host loader.database.windows.net port 1433 connect_timeout 15 [destination.mssql.credentials.query] # trust self-signed SSL certificates TrustServerCertificateyes # require SSL connection Encryptyes # send large string as VARCHAR, not legacy TEXT LongAsMaxyes也可以直接使用 SQLAlchemy 风格的连接字符串必须放在 TOML 文件顶部、任何 section 开始之前destination.mssql.credentialsmssql://loader:passwordloader.database.windows.net/dlt_data?TrustServerCertificateyesEncryptyesLongAsMaxyes任何 ODBC 专属设置都可以放进 query 字符串或像上面的分节示例一样放入destination.mssql.credentials.queryTOML 表。从源码看parse_native_representation()会把 query 中的键统一转为小写再做大小写不敏感处理并将driver、connect_timeout从 query 中提取到凭据字段configuration.py。4. 常见连接场景速查。Windows 认证连接串中加入trusted_connectionyesdestination.mssql.credentialsmssql://loader.database.windows.net/dlt_data?trusted_connectionyes使用 Windows 认证时若遇到缺失凭据报错请在 TOML 中把username和password设为空字符串。本地无 SSL 的 SQL Server 实例传入encryptnodestination.mssql.credentialsmssql://loader:loaderlocalhost/dlt_data?encryptno自签名 SSL 证书遇到certificate verify failed: unable to get local issuer certificate时加入TrustServerCertificateyesdestination.mssql.credentialsmssql://loader:loaderlocalhost/dlt_data?TrustServerCertificateyes长字符串8k并避免排序规则报错destination.mssql.credentialsmssql://loader:loaderlocalhost/dlt_data?LongAsMaxyes以代码方式直接传凭据使用显式目标实例pipeline dlt.pipeline( pipeline_namechess, destinationdlt.destinations.mssql(mssql://loader:passwordloader.database.windows.net/dlt_data?connect_timeout15), dataset_namechess_data)dlt.destinations.mssql(...)工厂函数的全部可配置参数create_indexes、has_case_sensitive_identifiers等见 factory.py代码中传入的参数会覆盖环境变量与配置文件。深入凭据模型与 ODBC DSN 的构建MsSqlCredentialsconfiguration.py是 MS SQL 目标的凭据模型其默认值如下字段默认值说明drivernamemssqlSQLAlchemy 风格驱动名固定值database/username/password/hostNone由用户提供port1433SQL Server 默认端口connect_timeout30连接超时秒数driverNone不指定时自动探测to_odbc_dsn()会把这些字段拼装成真正的 ODBC 连接串格式为DRIVER...;SERVERhost,port;DATABASE...;UID...;PWD...query 中的附加键如Encrypt、TrustServerCertificate会被转成大写一并追加configuration.py。值中的特殊字符分号、右花括号会被escape_mssql_odbc_value用 ODBC 花括号语法转义保证连接串可安全解析。这一行为在 test_mssql_configuration.py 中有完整断言包括自定义端口、任意附加键与大小写混写场景。此外若数据库已存在可用的loader账号仓库 dlt/destinations/impl/mssql/README.md 给出了最小授权建议创建数据库CREATE DATABASE dlt_data、创建用户并设置密码、再将数据库所有者授予 loader。实际使用时可按需降低权限。写入策略Write dispositionMS SQL 目标支持全部写处置策略append、replace、merge、scd2等。在源码能力声明中supported_merge_strategies包含delete-insert、upsert、scd2、insert-onlysupported_replace_strategies包含truncate-and-insert、insert-from-staging、staging-optimizedfactory.py。关于 replace 策略 有一个值得注意的特性当设置为staging-optimized时目标表会被删除并用ALTER SCHEMA ... TRANSFER重建该操作是原子性的——MSSQL 支持 DDL 事务。其 SQL 生成逻辑见 mssql.py 中的MsSqlStagingReplaceJob先DROP TABLE IF EXISTS删除目标表再ALTER SCHEMA ... TRANSFER将暂存表移入目标 schema随后用SELECT * INTO ... WHERE 1 0重建空暂存表供下一轮使用。merge 场景下MS SQL 不允许在DELETE FROM中使用别名MsSqlMergeJob为此重写了删除子句的生成方式mssql.py这也是 MS SQL 特有的兼容处理。数据加载MS SQL 目标支持两条加载路径parquet ADBC推荐速度快与INSERT 语句默认兜底。性能提示官方建议优先使用 ADBC parquet 加载相比 INSERT 方法可观测到10x–100x的加载速度提升。只要系统里存在正确的 ADBC 驱动dlt会自动把parquet设为首选文件格式。快速加载parquet ADBCparquet 文件格式通过 ADBC 驱动支持MS SQL 的 ADBC 驱动由 Columnar 提供。安装步骤如下pip install adbc-driver-manager dbc dbc install mssql使用uv时可以直接运行dbcuv tool run dbc searchdlt在运行时检测到驱动后会把 parquet 设为所有输入数据类型的默认首选格式该选择逻辑由make_adbc_parquet_file_format_selector实现factory.py实测速度相比 INSERT 提升 10x–70x。加载实现MssqlParquetCopyJobmssql.py将 parquet 文件按每个 row group 一批复制所有批次在单个事务中提交同时由于 MS SQL ADBC 驱动会把整个输入流缓冲在内存中实现按 row-group 逐批摄取以限制峰值内存、避免大文件 OOM测试 test_mssql_extras.py 专门断言了这一行为。使用该路径时需注意 ADBC 驱动并非支持所有 Arrow 数据类型已知限制包括fixed length binary定长二进制精度非微秒的 time 类型需要说明的是ADBC 驱动底层基于 go-mssqldb其DSN 格式与 ODBC 不同。dlt在odbc_to_go_mssql_dsn()中自动翻译两者重叠的键如Encrypt的yes/no被规范化为 go-mssqldb 的true/disable、TrustServerCertificate的yes/no被规范化为true/falsemssql.py。由于pyodbc和adbc都会忽略未知键你可以在同一个连接串里同时为两者指定参数。如需回退到 INSERT 语句可显式传入loader_file_formatinsert_values# revert to INSERT statements data_iter iter(()) # your data generator pipeline.run(data_iter, dataset_namespeed_test_2, write_dispositionreplace, table_nameunsw_flow, loader_file_formatinsert_values)使用 INSERT 语句加载默认情况下数据通过 INSERT 语句加载。MS SQL 对单条 INSERT 有1000 行上限dlt正是按此上限分批并在一个 batch 中发送多条 SQL 语句能力声明max_rows_per_insert 1000与supports_multiple_statements True见 factory.py。如果你观察到 odbc 驱动出现锁死例如带有未提交事务的连接泄漏到连接池可以尝试两种缓解手段禁用 pyodbc 连接池import pyodbc pyodbc.pooling False关闭 dlt 的多语句批处理dlt.destinations.mssql(mssql://loader:passwordloader.database.windows.net/dlt_data?connect_timeout15, supports_multiple_statementsFalse)在连接层PyOdbcMsSqlClient.open_connection()使用 pyodbc 连接 ODBC DSN并注册-155类型码的 output converter 来正确解码 SQL Server 的datetimeoffset二进制格式sql_client.py事务通过autocommit切换实现begin_transaction/commit_transaction/rollback_transaction错误会映射为DatabaseTransientException可重试与DatabaseTerminalException终止等标准异常。支持的文件格式insert-values默认格式parquet当检测到 MS SQL ADBC 驱动时自动启用model目标内部用于模型化数据项的格式源码supported_loader_file_formats声明factory.py。列提示与标识符MS SQL 会为所有带unique提示的列创建唯一索引但该行为默认关闭源码中active_hints HINT_TO_MSSQL_ATTR if self.config.create_indexes else {}mssql.py。也就是说默认情况下_dlt_id等带unique提示的列不会生成唯一索引。开启方式见下文附加目标选项。表与列标识符SQL Server在默认排序规则下使用大小写不敏感的标识符但会保留存储在 INFORMATION SCHEMA 中的标识符大小写。你可以使用大小写敏感的命名约定来保留标识符大小写需要注意这样做可能产生标识符冲突dlt会检测到冲突并使加载流程失败。如果修改了 SQL Server 服务器/数据库的排序规则为大小写敏感标识符行为也会随之改变。此时请按如下配置目标以便使用大小写敏感命名约定且不产生冲突[destination.mssql] has_case_sensitive_identifierstrue该配置在源码中会同步调整能力声明将caps.has_case_sensitive_identifiers置为True并设置casefold_identifier strfactory.py测试 test_mssql_configuration.py 验证了通过构造参数与环境变量两种方式设置后的效果。dlt state 同步MS SQL 目标完整支持 dlt state 同步可将流水线状态含增量加载水位线等持久化到目标端具体机制见 Syncing state with destination。数据类型与类型映射MS SQL 不支持 JSON 列因此 JSON 对象会以字符串形式存储在nvarchar列中类型映射中json: json会进一步落到nvarchar大文本类型factory.py。MsSqlTypeMapperfactory.py定义了 dlt 标准类型到 MS SQL 数据库类型的映射核心对应关系如下dlt 类型MS SQL 类型备注textnvarchar/nvarchar(n)默认无长度限制doublefloatboolbitbigintbigintbinaryvarbinary(max)/varbinary(n)datedatetimestampdatetimeoffset(n)带时区不带时区时用datetime2(n)timetime(n)decimal/weidecimal(p,s)jsonjson最终落为nvarchar几个值得注意的细节时间精度datetimeoffset/datetime2的精度由列上的precision控制MS SQL 仅支持 0–7 位精度超出范围时自动回退到 7 并告警factory.py。能力声明中timestamp_precision 6、max_timestamp_precision 7。整数按精度分档bigint类型会依据precision映射为tinyint≤8、smallint≤16、int≤32、bigint≤64超过 64 位抛错factory.py。textunique组合MS SQL 不允许在大文本列上建索引因此带unique提示的text列会被改写为nvarchar(n)默认 900否则无法创建唯一索引mssql.py。类型映射测试test_mssql_table_builder.py 用sqlfluff解析 tsql 方言逐列断言建表与 ALTER TABLE 的 SQL 类型如col4 datetimeoffset、col6 decimal(38,9)、col9 json、col11_precision time(3)等。其他能力参数还包括标识符最大长度 128max_identifier_length/max_column_identifier_length、查询长度上限65536 * 10字节、文本类型长度上限约 1 GB2**30 - 1、支持 DDL 事务、不支持CREATE TABLE IF NOT EXISTS、ADBC 驱动不支持字典编码的 Arrow 数组parquet_format.supports_dictionary_encoding FalseSQL 方言为tsqlfactory.py。附加目标选项MS SQL 目标默认不会为带unique提示的列如_dlt_id创建 UNIQUE 索引启用方式[destination.mssql] create_indexestrue开启后所有unique提示列都会生成唯一索引mssql.py这也是test_mssql_extras.py中复杂 JSON 加载测试test_mssql_complex_json_loading以mssql(create_indexesTrue)创建目标的默认前提。指定 ODBC 驱动名显式设置驱动名称[destination.mssql.credentials] driverODBC Driver 18 for SQL Server使用 SQLAlchemy 连接字符串时空格需替换为# Keep it at the top of your TOML file, before any section starts destination.mssql.credentialsmssql://loader:passwordloader.database.windows.net/dlt_data?driverODBCDriver18forSQLServerdbt 支持MS SQL 目标可通过 dbt-sqlserver 与 dbt 集成在加载完成后直接对目标表执行 dbt 模型转换。验证与测试仓库为 MS SQL 目标提供了较为完整的测试覆盖可用于对照验证本文涉及的各项行为tests/load/mssql/test_mssql_configuration.py工厂默认值、凭据默认值端口 1433、超时 30s、指纹基于 host 的 digest128、连接串解析与 ODBC DSN 构建、驱动白名单校验tests/load/mssql/test_mssql_table_builder.py建表与加列 SQL 生成tsql 方言语法解析tests/load/mssql/test_mssql_extras.pyADBC 按 row-group 摄取、多阶段复杂 JSON 数据含嵌套、空值、动态字段在 merge/replace 写处置下的端到端加载验证。这些测试均标记为essential是目标功能稳定性的核心保障。完成配置后即可运行python chess_pipeline.py启动你的第一条 MS SQL 流水线。【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考