dlt Workspace Profiles 全解析用 TOML 档案实现 dev/prod 环境隔离与密钥管理【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt在 dltdata load tool的 dltHub Workspace 中Profile档案是一套面向环境的配置与密钥管理机制它让你用同一套管道代码通过.dlt目录下的 TOML 档案文件切换开发dev、测试tests和生产prod环境无需改动任何业务代码。读完本文你将掌握 Profile 的完整配置方法、内置档案与自定义档案的差异、profile 的 pin/切换操作以及一套「本地 DuckDB → 生产 MotherDuck」的实战切换方案并能从源码层面理解档案解析的优先级机制。什么是 Profile环境隔离的配置层dlt 中的 Profile 为每个执行环境提供相互隔离的配置configuration、凭据credentials和工作目录working directories。这意味着同一台机器上可以同时存在dev档案指向的本地数据目录与管道状态prod档案指向的云端数据源与对应的状态测试期间tests档案占用的独立沙箱。Profile 通过.dlt目录中的 TOML 文件 定义和管理与 OSS dlt 中你已经熟悉的secrets.toml和config.toml完全兼容——在 Workspace 中可以直接运行未经修改的 OSS dlt 代码。从源码看档案机制的实现集中在 Workspace 模块默认档案名、pin 文件名、内置档案表都在 dlt/_workspace/profile.py 中声明DEFAULT_PROFILE dev PIN_FILE_NAME profile-name BUILT_IN_PROFILES { dev: dev profile, workspace default, prod: production profile, assumed by pipelines deployed in Runtime, tests: profile assumed when running tests, access: ( production profile, assumed by interactive notebooks in Runtime, typically with limited access rights ), } LOCAL_PROFILES [dev, tests] Profiles used in local workspace其中LOCAL_PROFILES配合is_local_profile()函数用于区分永不同步到 dltHub 云端的本地档案。dltHub 平台会自动选择特定档案来部署和运行管道与 notebook批处理作业用prod交互式 notebook 用access。启用 Workspace 与 Profile使用 Profile 前需要两个前置条件按照安装指南完成安装启用 Workspace 模式安装指南中「enable workspace mode」一节Workspace 特性包含 Profiles。dltHub Workspace 是覆盖本地开发到生产的统一环境。用uvx dlthub-initlatest搭建scaffold一个 workspace 后在 workspace 内添加一个管道dlthub pipeline init pokemon_api duckdb初始化完成后workspace 会暴露扩展的 CLI 命令面其中包括 profile 相关的命令dlthub profile dlthub local定义 Profile共享 TOML 与档案专属 TOMLWorkspace 脚手架会在.dlt目录下生成两个熟悉的 TOML 文件secrets.toml和config.toml其用法与 OSSdlt完全一致。关键规则一共享文件对所有档案可见。例如把log_levelINFO写进config.toml它对所有档案生效。只有当某个设置需要在档案间取不同值时例如开发环境INFO、生产环境WARNING才需要创建档案专属的 TOML 文件。这个「档案专属文件优先、共享文件兜底」的行为由档案感知的 TOML provider 实现。dlt/_workspace/providers.py 中的ProfilePathMixin._resolve_toml_paths对每一个配置目录都会先追加{profile}.secrets.toml/{profile}.config.toml再追加不带前缀的secrets.toml/config.tomldef _resolve_toml_paths(self, file_name: str, resolvable_dirs: List[str]) - List[str]: resolvable_files [] for d in resolvable_dirs: # append each a profile and a base file name for each directory # profile name is always first resolvable_files.append(os.path.join(d, f{self._profile}.{file_name})) resolvable_files.append(os.path.join(d, file_name)) return resolvable_files也就是说dev档案会依次探测dev.secrets.toml→secrets.tomlconfig 同理档案专属值天然覆盖共享值。这些 provider 的装配位置见 WorkspaceRunContext._initial_providers环境变量 provider 排最前随后是ProfileSecretsTomlProvider与ProfileConfigTomlProvider。内置档案及其同步范围dltHub Workspace 预定义了若干档案。dev和tests是本地专用never uploadedprod、access以及任何在 job 装饰器中引用的自定义档案都会在每次dlthub deploy时同步到云端配置。Profile范围说明dev本地专用本地开发的默认档案tests本地专用自动化测试与 CI/CD 使用的档案prod同步至云端生产档案dltHub 平台运行批处理管道时自动选用access同步至云端只读生产档案供平台上的交互式 notebook 使用注意创建 workspace 时dev档案默认激活其他档案要么在本地被 pin要么由 dltHub 平台自动选中批处理作业选prod交互式作业选access。查看当前可用的档案dlthub profile listlist命令的实现见 dlt/_workspace/cli/dlthub/_profile_command.py它会对每个档案标注(current)、(local)、(configured)三类标记分别表示当前激活、本地专用、以及已有配置或管道。列表来源available_profiles()的逻辑在 WorkspaceRunContext先取全部内置档案再追加 pin 文件中记录的非内置档案名。切换 ProfilePin 机制在本地切换pin 指定档案要在本地切换环境pin 目标档案即可pin 后的档案会成为后续dlthub local …命令的默认档案dlthub local profile use prod验证当前档案dlthub profile info解除 pin 只需删除 pin 文件pin 就是一个普通文本文件内容即档案名rm .dlt/profile-name源码印证了这一点save_profile_pin / read_profile_pin 把档案名写入/读取.dlt/profile-name文件名由PIN_FILE_NAME profile-name决定dlthub local profile use对应的 pin_profile 在未指定名称时还会提示当前的 pin 状态和解除 pin 的方式Currently pinned profile is: dev. To unpin remove .dlt/profile-name file.提示你可以 pin任意名称的档案不限于预定义列表从而创建任意多的档案可以先 pin 一个还没有档案专属 TOML 文件的档案之后再补建这些文件dlthub -v local info会列出 dlt 读取 profile 设置的所有预期文件位置方便排查配置到底从哪个文件加载。pin 之后像平常一样通过本地 runner 运行管道即可dlthub local pipeline run pokemon_api_pipelineworkspace 会自动使用激活档案的配置、密钥和数据位置来执行。Profile 隔离的不只是配置还有运行状态每个档案拥有独立的工作目录.dlt/state/profile/和本地数据目录.dlt/data/profile/。这一布局在 dlt/_workspace/run_context.py 中可以直接验证DEFAULT_WORKSPACE_WORKING_FOLDER state DEFAULT_LOCAL_FOLDER data def default_working_dir(run_dir: str, name: str, profile: str, default_folder: str) - str: data_dir os.path.join(run_dir, default_folder) if not is_folder_writable(run_dir): # fallback to temp dir which should be writable, project name is used to separate projects data_dir os.path.join(tempfile.gettempdir(), dlt, default_folder, name) return os.path.join(data_dir, profile)即默认路径为run_dir/state/profile与run_dir/data/profile当run_dir不可写时回退到系统临时目录。这种隔离带来两个实用能力用dlthub local clean清理当前档案的工作空间从头开始而不影响其他档案运行pytest时切换到tests档案例如通过 fixture使交互式开发dev与并行测试tests完全隔离。在代码中切换 Profile除了 CLI也可以直接操作 workspace 运行上下文import dlt workspace dlt.current.workspace() workspace.switch_profile(test)底层调用链见 WorkspaceRunContext.switch_profile它委托给 switch_profile本质是对当前上下文的run_dir重新执行switch_context(profile...)刷新出一个绑定到新档案的 run context若当前上下文不支持 profile 会抛出RunContextNotAvailable。切换后WorkspaceRunContext会重建 provider 链_initial_providers(self.profile)使新档案的 TOML 立即生效。实战示例用 Profile 切换目的地DuckDB → MotherDuck下面走一遍完整流程dev档案使用本地 DuckDBprod档案使用MotherDuck管道代码完全相同。第一步配置 dev 档案为了彻底隔离档案在.dlt/dev.secrets.toml中定义本地目的地带dev.前缀的档案专属文件[destination.warehouse] destination_type duckdb在管道脚本中使用命名目的地warehouseimport dlt pipeline dlt.pipeline( pipeline_namepokemon_api_pipeline, destinationwarehouse, dataset_namepokemon_api_data, )本地运行dlthub local pipeline run pokemon_api_pipeline此时数据存储在.dlt/data/dev/warehouse.duckdb管道状态存储在.dlt/state/dev/。第二步配置 prod 档案创建.dlt/prod.secrets.toml[destination.warehouse] destination_type motherduck credentials md:///dlt_data?motherduck_token....pin 并激活档案dlthub local profile use prod可选先测试连接运行生产管道之前可以先验证凭据与数据集配置是否可用dlthub --debug local pipeline sync pokemon_api_pipeline --destination warehouse --dataset-name pokemon_api_data警告sync会丢弃本地管道工作目录并从目的地恢复。只在prod档案的本地状态是全新时才执行本例刚切换档案正好符合。该命令会连接目的地、校验凭据并从目的地引导bootstrap一份本地管道状态副本。若凭据无效或配置有误dlt 会抛出带完整堆栈的详细异常方便你在部署前定位问题。如果连接成功但MotherDuck中尚无该数据集会看到类似提示ERROR: Pipeline pokemon_api_pipeline was not found in dataset pokemon_api_data in warehouse这只是说明目标数据集尚未创建无需任何操作。接着运行管道脚本把数据写入 MotherDuckdlthub local pipeline run pokemon_api_pipeline数据将存入 MotherDuck管道状态存入.dlt/state/prod/。打开 Workspace Dashboard管道完成后用以下命令打开 Workspace Dashboarddlthub local show你会看到管道已连接到远端 MotherDuck 数据集随时可以继续探索数据。部署到 dltHub 平台定时运行至此可以把 Workspace 部署到 dltHub 平台并设置定时运行。注意dltHub 平台会自动使用你刚创建的prod档案。检查与管理 Profile 的常用命令汇总日常运维会用到的命令列出档案dlthub profile list查看当前档案加-v可列出全部配置 provider 及其文件位置dlthub profile info切换档案pin 到指定档案dlthub local profile use profile_name清理工作空间在 dev 档案下尤其有用dlthub local clean这些命令的行为都有测试覆盖例如 tests/workspace/cli/dlthub/test_profile_command.py 验证了内置档案dev/tests/prod/access全部出现在列表中、dev与tests被正确标记为 local、pin 文件存在与否影响profile info的输出等。最佳实践本地测试与实验使用dev档案。dltHub 平台上的生产作业使用prod档案。密钥一律放在独立的profile.secrets.toml文件中绝不要写进代码。使用命名目的地如示例中的warehouse简化环境切换——管道代码引用逻辑名具体实现由档案 TOML 决定。config.toml可以提交到版本库但所有.secrets.toml文件必须排除。对于不适合放进仓库的进程级环境变量请设置 workspace 环境变量档案范围内的值会覆盖该档案运行时的共享 workspace 环境值。小结与延伸Profile 机制在 dltHub Workspace 中把「环境」变成了一个一等的配置维度TOML 层负责档案级配置与密钥的覆盖优先级档案专属文件优先、共享文件兜底运行上下文层负责状态与数据的按档案隔离.dlt/state/profile/、.dlt/data/profile/CLI 层负责 pin/查询/切换操作。围绕这套机制可以进一步阅读配置 Workspace部署管道监控与调试管道Workspace 环境变量【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 dlt Workspace Profiles 全解析：用 TOML 档案实现 dev/prod 环境隔离与密钥管理
dlt Workspace Profiles 全解析用 TOML 档案实现 dev/prod 环境隔离与密钥管理【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt在 dltdata load tool的 dltHub Workspace 中Profile档案是一套面向环境的配置与密钥管理机制它让你用同一套管道代码通过.dlt目录下的 TOML 档案文件切换开发dev、测试tests和生产prod环境无需改动任何业务代码。读完本文你将掌握 Profile 的完整配置方法、内置档案与自定义档案的差异、profile 的 pin/切换操作以及一套「本地 DuckDB → 生产 MotherDuck」的实战切换方案并能从源码层面理解档案解析的优先级机制。什么是 Profile环境隔离的配置层dlt 中的 Profile 为每个执行环境提供相互隔离的配置configuration、凭据credentials和工作目录working directories。这意味着同一台机器上可以同时存在dev档案指向的本地数据目录与管道状态prod档案指向的云端数据源与对应的状态测试期间tests档案占用的独立沙箱。Profile 通过.dlt目录中的 TOML 文件 定义和管理与 OSS dlt 中你已经熟悉的secrets.toml和config.toml完全兼容——在 Workspace 中可以直接运行未经修改的 OSS dlt 代码。从源码看档案机制的实现集中在 Workspace 模块默认档案名、pin 文件名、内置档案表都在 dlt/_workspace/profile.py 中声明DEFAULT_PROFILE dev PIN_FILE_NAME profile-name BUILT_IN_PROFILES { dev: dev profile, workspace default, prod: production profile, assumed by pipelines deployed in Runtime, tests: profile assumed when running tests, access: ( production profile, assumed by interactive notebooks in Runtime, typically with limited access rights ), } LOCAL_PROFILES [dev, tests] Profiles used in local workspace其中LOCAL_PROFILES配合is_local_profile()函数用于区分永不同步到 dltHub 云端的本地档案。dltHub 平台会自动选择特定档案来部署和运行管道与 notebook批处理作业用prod交互式 notebook 用access。启用 Workspace 与 Profile使用 Profile 前需要两个前置条件按照安装指南完成安装启用 Workspace 模式安装指南中「enable workspace mode」一节Workspace 特性包含 Profiles。dltHub Workspace 是覆盖本地开发到生产的统一环境。用uvx dlthub-initlatest搭建scaffold一个 workspace 后在 workspace 内添加一个管道dlthub pipeline init pokemon_api duckdb初始化完成后workspace 会暴露扩展的 CLI 命令面其中包括 profile 相关的命令dlthub profile dlthub local定义 Profile共享 TOML 与档案专属 TOMLWorkspace 脚手架会在.dlt目录下生成两个熟悉的 TOML 文件secrets.toml和config.toml其用法与 OSSdlt完全一致。关键规则一共享文件对所有档案可见。例如把log_levelINFO写进config.toml它对所有档案生效。只有当某个设置需要在档案间取不同值时例如开发环境INFO、生产环境WARNING才需要创建档案专属的 TOML 文件。这个「档案专属文件优先、共享文件兜底」的行为由档案感知的 TOML provider 实现。dlt/_workspace/providers.py 中的ProfilePathMixin._resolve_toml_paths对每一个配置目录都会先追加{profile}.secrets.toml/{profile}.config.toml再追加不带前缀的secrets.toml/config.tomldef _resolve_toml_paths(self, file_name: str, resolvable_dirs: List[str]) - List[str]: resolvable_files [] for d in resolvable_dirs: # append each a profile and a base file name for each directory # profile name is always first resolvable_files.append(os.path.join(d, f{self._profile}.{file_name})) resolvable_files.append(os.path.join(d, file_name)) return resolvable_files也就是说dev档案会依次探测dev.secrets.toml→secrets.tomlconfig 同理档案专属值天然覆盖共享值。这些 provider 的装配位置见 WorkspaceRunContext._initial_providers环境变量 provider 排最前随后是ProfileSecretsTomlProvider与ProfileConfigTomlProvider。内置档案及其同步范围dltHub Workspace 预定义了若干档案。dev和tests是本地专用never uploadedprod、access以及任何在 job 装饰器中引用的自定义档案都会在每次dlthub deploy时同步到云端配置。Profile范围说明dev本地专用本地开发的默认档案tests本地专用自动化测试与 CI/CD 使用的档案prod同步至云端生产档案dltHub 平台运行批处理管道时自动选用access同步至云端只读生产档案供平台上的交互式 notebook 使用注意创建 workspace 时dev档案默认激活其他档案要么在本地被 pin要么由 dltHub 平台自动选中批处理作业选prod交互式作业选access。查看当前可用的档案dlthub profile listlist命令的实现见 dlt/_workspace/cli/dlthub/_profile_command.py它会对每个档案标注(current)、(local)、(configured)三类标记分别表示当前激活、本地专用、以及已有配置或管道。列表来源available_profiles()的逻辑在 WorkspaceRunContext先取全部内置档案再追加 pin 文件中记录的非内置档案名。切换 ProfilePin 机制在本地切换pin 指定档案要在本地切换环境pin 目标档案即可pin 后的档案会成为后续dlthub local …命令的默认档案dlthub local profile use prod验证当前档案dlthub profile info解除 pin 只需删除 pin 文件pin 就是一个普通文本文件内容即档案名rm .dlt/profile-name源码印证了这一点save_profile_pin / read_profile_pin 把档案名写入/读取.dlt/profile-name文件名由PIN_FILE_NAME profile-name决定dlthub local profile use对应的 pin_profile 在未指定名称时还会提示当前的 pin 状态和解除 pin 的方式Currently pinned profile is: dev. To unpin remove .dlt/profile-name file.提示你可以 pin任意名称的档案不限于预定义列表从而创建任意多的档案可以先 pin 一个还没有档案专属 TOML 文件的档案之后再补建这些文件dlthub -v local info会列出 dlt 读取 profile 设置的所有预期文件位置方便排查配置到底从哪个文件加载。pin 之后像平常一样通过本地 runner 运行管道即可dlthub local pipeline run pokemon_api_pipelineworkspace 会自动使用激活档案的配置、密钥和数据位置来执行。Profile 隔离的不只是配置还有运行状态每个档案拥有独立的工作目录.dlt/state/profile/和本地数据目录.dlt/data/profile/。这一布局在 dlt/_workspace/run_context.py 中可以直接验证DEFAULT_WORKSPACE_WORKING_FOLDER state DEFAULT_LOCAL_FOLDER data def default_working_dir(run_dir: str, name: str, profile: str, default_folder: str) - str: data_dir os.path.join(run_dir, default_folder) if not is_folder_writable(run_dir): # fallback to temp dir which should be writable, project name is used to separate projects data_dir os.path.join(tempfile.gettempdir(), dlt, default_folder, name) return os.path.join(data_dir, profile)即默认路径为run_dir/state/profile与run_dir/data/profile当run_dir不可写时回退到系统临时目录。这种隔离带来两个实用能力用dlthub local clean清理当前档案的工作空间从头开始而不影响其他档案运行pytest时切换到tests档案例如通过 fixture使交互式开发dev与并行测试tests完全隔离。在代码中切换 Profile除了 CLI也可以直接操作 workspace 运行上下文import dlt workspace dlt.current.workspace() workspace.switch_profile(test)底层调用链见 WorkspaceRunContext.switch_profile它委托给 switch_profile本质是对当前上下文的run_dir重新执行switch_context(profile...)刷新出一个绑定到新档案的 run context若当前上下文不支持 profile 会抛出RunContextNotAvailable。切换后WorkspaceRunContext会重建 provider 链_initial_providers(self.profile)使新档案的 TOML 立即生效。实战示例用 Profile 切换目的地DuckDB → MotherDuck下面走一遍完整流程dev档案使用本地 DuckDBprod档案使用MotherDuck管道代码完全相同。第一步配置 dev 档案为了彻底隔离档案在.dlt/dev.secrets.toml中定义本地目的地带dev.前缀的档案专属文件[destination.warehouse] destination_type duckdb在管道脚本中使用命名目的地warehouseimport dlt pipeline dlt.pipeline( pipeline_namepokemon_api_pipeline, destinationwarehouse, dataset_namepokemon_api_data, )本地运行dlthub local pipeline run pokemon_api_pipeline此时数据存储在.dlt/data/dev/warehouse.duckdb管道状态存储在.dlt/state/dev/。第二步配置 prod 档案创建.dlt/prod.secrets.toml[destination.warehouse] destination_type motherduck credentials md:///dlt_data?motherduck_token....pin 并激活档案dlthub local profile use prod可选先测试连接运行生产管道之前可以先验证凭据与数据集配置是否可用dlthub --debug local pipeline sync pokemon_api_pipeline --destination warehouse --dataset-name pokemon_api_data警告sync会丢弃本地管道工作目录并从目的地恢复。只在prod档案的本地状态是全新时才执行本例刚切换档案正好符合。该命令会连接目的地、校验凭据并从目的地引导bootstrap一份本地管道状态副本。若凭据无效或配置有误dlt 会抛出带完整堆栈的详细异常方便你在部署前定位问题。如果连接成功但MotherDuck中尚无该数据集会看到类似提示ERROR: Pipeline pokemon_api_pipeline was not found in dataset pokemon_api_data in warehouse这只是说明目标数据集尚未创建无需任何操作。接着运行管道脚本把数据写入 MotherDuckdlthub local pipeline run pokemon_api_pipeline数据将存入 MotherDuck管道状态存入.dlt/state/prod/。打开 Workspace Dashboard管道完成后用以下命令打开 Workspace Dashboarddlthub local show你会看到管道已连接到远端 MotherDuck 数据集随时可以继续探索数据。部署到 dltHub 平台定时运行至此可以把 Workspace 部署到 dltHub 平台并设置定时运行。注意dltHub 平台会自动使用你刚创建的prod档案。检查与管理 Profile 的常用命令汇总日常运维会用到的命令列出档案dlthub profile list查看当前档案加-v可列出全部配置 provider 及其文件位置dlthub profile info切换档案pin 到指定档案dlthub local profile use profile_name清理工作空间在 dev 档案下尤其有用dlthub local clean这些命令的行为都有测试覆盖例如 tests/workspace/cli/dlthub/test_profile_command.py 验证了内置档案dev/tests/prod/access全部出现在列表中、dev与tests被正确标记为 local、pin 文件存在与否影响profile info的输出等。最佳实践本地测试与实验使用dev档案。dltHub 平台上的生产作业使用prod档案。密钥一律放在独立的profile.secrets.toml文件中绝不要写进代码。使用命名目的地如示例中的warehouse简化环境切换——管道代码引用逻辑名具体实现由档案 TOML 决定。config.toml可以提交到版本库但所有.secrets.toml文件必须排除。对于不适合放进仓库的进程级环境变量请设置 workspace 环境变量档案范围内的值会覆盖该档案运行时的共享 workspace 环境值。小结与延伸Profile 机制在 dltHub Workspace 中把「环境」变成了一个一等的配置维度TOML 层负责档案级配置与密钥的覆盖优先级档案专属文件优先、共享文件兜底运行上下文层负责状态与数据的按档案隔离.dlt/state/profile/、.dlt/data/profile/CLI 层负责 pin/查询/切换操作。围绕这套机制可以进一步阅读配置 Workspace部署管道监控与调试管道Workspace 环境变量【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考