从内置Python迁移到sqlc-gen-python插件指南

从内置Python迁移到sqlc-gen-python插件指南

sqlc 项目地址: https://gitcode.com/gh_mirrors/sql/sqlc

前言

在sqlc项目1.16.0版本中，官方宣布将逐步弃用内置的Python支持功能，并将在1.17.0版本中完全移除。取而代之的是全新的sqlc-gen-python插件系统。本文将详细介绍如何从旧版迁移到新的插件架构。

迁移背景

sqlc作为一个强大的SQL查询编译器，能够将SQL语句转换为类型安全的代码。随着项目发展，官方决定将语言支持功能插件化，这带来了几个优势：

1. 独立更新：各语言支持可以独立于核心更新
2. 灵活配置：可以针对不同项目选择不同版本的插件
3. 性能优化：插件系统经过专门优化

迁移步骤详解

第一步：添加sqlc-gen-python插件

首先需要在配置文件中声明插件依赖。根据你使用的配置文件格式（JSON或YAML），添加以下配置：

{
  "version": "2",
  "plugins": [
    {
      "name": "py",
      "wasm": {
        "url": "https://downloads.sqlc.dev/plugin/sqlc-gen-python_1.0.0.wasm",
        "sha256": "aca83e1f59f8ffdc604774c2f6f9eb321a2b23e07dc83fc12289d25305fa065b"
      }
    }
  ]
}

version: "2"
plugins:
  - name: "py"
    wasm:
      url: "https://downloads.sqlc.dev/plugin/sqlc-gen-python_1.0.0.wasm"
      sha256: "aca83e1f59f8ffdc604774c2f6f9eb321a2b23e07dc83fc12289d25305fa065b"

配置说明：

• name字段指定插件名称，Python插件固定为"py"
• wasm部分包含插件二进制文件的下载地址和校验值
• 版本号必须设置为"2"，表示使用新版配置格式

第二步：改造包配置

原有的Python生成配置需要迁移到新的插件架构。以下是新旧配置对比：

旧版JSON配置示例:

"gen": {
  "python": {
    "out": "src",
    "package": "foo",
    "emit_sync_querier": true,
    "emit_async_querier": true,
    "query_parameter_limit": 5
  }
}

新版JSON配置示例:

"codegen": [
  {
    "out": "src",
    "plugin": "py",
    "options": {
      "package": "authors",
      "emit_sync_querier": true,
      "emit_async_querier": true,
      "query_parameter_limit": 5
    }
  }
]

主要变更点：

1. gen节点改为codegen数组
2. 原python节点拆分为：
   • plugin字段：指定使用"py"插件
   • options对象：包含所有原Python特定配置
3. 支持多语言同时生成（通过添加多个codegen项）

YAML配置的变更方式类似，保持相同的结构即可。

第三步：重新生成代码

完成配置迁移后，只需执行常规生成命令：

sqlc generate

注意事项：

1. 首次运行会下载插件，耗时稍长
2. 后续生成速度与之前相当
3. 生成的代码结构保持不变，无需修改业务代码

迁移验证建议

为确保迁移成功，建议进行以下验证：

1. 检查生成代码是否与之前一致
2. 运行项目测试套件
3. 特别验证同步和异步查询器功能（如果启用）

常见问题解答

Q：为什么需要迁移到插件系统？ A：插件架构提供了更好的灵活性和可维护性，允许独立更新Python支持而不影响核心功能。

Q：迁移后功能会有变化吗？ A：功能完全一致，只是生成方式变化，对使用者透明。

Q：如果同时使用多种语言怎么办？ A：新的codegen数组支持同时配置多个语言插件，只需添加相应的配置项即可。

结语

本次迁移虽然涉及配置变更，但整体过程简单明了。插件化架构为sqlc的未来发展奠定了更好基础，建议用户尽快完成迁移以获取持续的技术支持。如果在迁移过程中遇到任何问题，可以参考官方文档或社区讨论。

sqlc 项目地址: https://gitcode.com/gh_mirrors/sql/sqlc