zodbupdate 2.0

自定义软件/鸡蛋

将此egg安装在与您的软件安装相同的解释器/环境中非常重要。如果您使用的是常规Python安装或virtualenv，仅使用easy_install安装包应该就可以了。

如果您使用buildout，可以使用此配置的egg配方进行安装

[buildout]
parts += zodbupdate

[zodbupdate]
recipe = zc.recipe.egg
eggs = zodbupdate
    <list additional eggs here>

如果您没有与必要的软件一起安装zodbupdate，它将报告缺少的类，并且不会触摸您的数据库。

非-FileStorage配置

您可以通过提供ZConfig配置文件（类似于zope.conf）来配置您的ZODB安装中已知的任何存储。例如，您可以通过提供配置文件zeo.conf来连接到ZEO服务器。

<zeoclient>
    server 127.0.0.1:8100
    storage 1
</zeoclient>

然后运行

$ zodbupdate -c zeo.conf

预定义重命名规则

可以使用名为zodbupdate的入口点定义重命名规则

setup(...
      entry_points = """
      [zodbupdate]
      renames = mypackage.mymodule:rename_dict
      """)

这些也可以在python中定义

setup(...
      entry_points={
        'zodbupdate': ['renames = mypackage.mymodule:rename_dict'],
      })

这些入口点必须指向将旧类名映射到新类名的字典

rename_dict = {
    'mypackage.mymodule ClassName':
    'otherpackage.othermodule OtherClass'}

一旦定义了规则，就可以删除其中提到的旧导入位置。

打包

选项--pack将在成功后打包存储。 （您应该告诉用户使用该选项。如果他们从不打包存储，这是一个好机会）。

转换为Python 3

zodbupdate可用于将使用Python 2应用程序创建的数据库迁移到可用于相同应用程序的Python 3。要完成此任务，您需要

1. 停止您的应用程序。迁移运行时不应向数据库写入任何内容。

2. 更新您的Python 2应用程序以使用最新的ZODB版本。它不与ZODB 3一起工作。

3. 使用Python 2，运行zodbupdate --pack --convert-py3。

如果您使用Data.fs，建议您使用-f选项指定数据库。转换后，数据库的神奇头将更新，这样您就可以使用Python 3打开数据库。

如果您使用不同的存储（如RelStorage），请确保迁移后使用Python 3应用程序连接到它。您仍然可以连接到数据库并使用Python 2应用程序而不会出错，但那时您需要再次将其转换为Python 3。

打包不是必需的，但强烈推荐。

转换将处理以下任务

• 更新存储的Python datetime、date和时间对象以使用Python 3字节

• 更新ZODB引用以使用Python 3字节

• 可选将存储的字符串转换为Unicode或字节，具体取决于您的配置。

如果您的应用程序在Python 3中期望使用字节，它们必须在数据库中作为字节存储，而所有其他字符串必须存储为Unicode字符串，如果它们包含非ASCII字符。

当使用 --convert-py3 时，zodbupdate 将从入口点加载一组解码器。

setup(...
      entry_points = """
      [zodbupdate.decode]
      decodes = mypackage.mymodule:decode_dict
      """)

解码器是字典，指定为键是持久化类上的属性，这些属性必须以字节编码（如果值是 binary）或使用值作为编码解码为Unicode（例如，这里使用 utf-8）。

decode_dict = {
   'mypackage.mymodule ClassName attribute': 'binary',
   'otherpackage.othermodule OtherClass other_attribute': 'utf-8'}

请注意，目前仅支持持久化类上的属性。

请注意，这些转换规则仅适用于在pickle中引用的类，超类的规则不适用。这意味着您必须将注解规则推送到具有需要此注解的字段的超类所有子类。

在Python 3中转换为Python 3

zodbupdate 还可以从Python 3中运行，以将使用Python 2创建的数据库转换为在Python 3中可用的数据库。然而，这与使用Python 2运行转换的方式略有不同。在Python 3中，您必须指定在反序列化字符串时要使用的默认编码：zodbupdate --pack --convert-py3 --encoding utf-8。

对于数据库中的每个字符串，zodbupdate 将按以下方式转换：

1. 如果它是通过上述解码器明确配置的属性，它将被解码或编码为指定内容。

2. 否则，值将使用命令行上指定的编码进行解码。

3. 如果在使用命令行上指定的编码解码时出现错误，值将作为字节存储。

问题和解决方案

2.0 (2023-02-09)

• 支持Python 3.9、3.10、3.11。

• 弃用对Python 2.7、3.5、3.6的支持。

• 使用无历史记录和记录历史记录的 RelStorage 进行测试。注意，记录历史记录的 RelStorage 需要 RelStorage 3.3 或更高版本，以及 Python 2.7 或 Python 3.6 及以上版本。（#30）

1.5 (2020-07-28)

• 修复与 ZODB 5.6 的不兼容性（#35）

• 添加了对无历史记录的 RelStorage 的支持（#28）

• 在测试中支持 zope.interface >= 5。（问题 32）

1.4 (2019-08-23)

• 在Python 3上以 –dry-run 运行时，打开Python 2 ZODB 将失败并显示说明（#22）

1.3 (2019-07-30)

• 支持从古老的Python 2版本转换 sets.Set() 对象。（问题 23）

• 在不依赖 ZODB.broken.rebuild 的情况下将集合对象转换为 builtins.set。（问题 25）

1.2 (2019-05-09)

• 启用旧/增长ZODB的Python 3转换的回退编码，使用新的命令行选项 --encoding-fallback。（#15）

• 切换到使用 argparse，因为 optparse 已弃用。

• 添加在运行Python 3迁移时为 str 对象使用默认编码的能力。（#14）

• 修复引用已损坏接口的记录更新，当接口顶层模块缺失时。

• 修复了跳过blob记录的问题，以便在blob引用中仍能转换oids。

• 添加对Python 3.8a3的支持。

• 停止支持Python 3.4。

1.1 (2018-10-05)

• 迁移数据库到Python 3时跳过ZODB.blob的记录，以避免破坏blob文件的引用。

• 迁移数据库到Python 3时，在转换包含None的属性时不会失败。

• 修复了在Python 2上运行ZODB >= 5.4.0时的测试，该版本现在使用pickle协议3。

• 修复了旧式类实例的is_broken检查。

• 添加对Python 3.7的支持。

• 停止对PyPy的支持。

1.0 (2018-02-13)

• 支持Python 2.7和3.4、3.5和3.6以及pypy 3。弃用任何旧版本的Python。

• 移除了选择pickler（--pickler）的选项。这仅在您有Python 2.5或更早版本的扩展类时才有用。

• 添加了将数据库转换为Python 3的选项。

0.5 (2010-10-07)

• 更多的调试日志现在显示正在处理的OID（这对于确定哪个对象缺少工厂非常有帮助）。

• 改进了对缺失工厂的支持：如果pickle需要更新并且包含对缺失类的引用（不是此类的实例），则以前会引发错误。现在已修复此情况。

• Python 2.4不再受支持。如果您需要Python 2.4支持，请坚持使用版本0.3。

0.4 (2010-07-14)

• 添加了调试损坏记录的选项。

• 添加了跳过记录的选项。

• 添加了使用Python unPickler而不是C unPickler的选项。这可以让您调试记录。此外，Python unPickler还可以更新过去有特殊修复的旧ExtensionClass记录。

• 现在很好地支持了损坏的接口（如果您也提供了它们）。

0.3 (2010-02-02)

• 重新解包和重新打包代码以重命名对已移动类的引用。这使得脚本可以在使用较旧版本的ZODB创建的数据库上运行。

• 如果您直接与FileStorage工作，会报告POSKeyError，但不会导致失败。

• 移除了尝试防止无变更提交的冗余代码：ZODB已经自行处理了这一点。

0.2 (2009-06-23)

• 添加了将重命名规则存储到文件的选项。

• 不要提交没有变更的事务。

• 从entry points zodbupdate加载重命名规则。

• 与Python 2.4兼容。

• 将名称从zodbupgrade更改为zodbupdate。

• 添加了‘verbose’选项。

• 改进了日志记录。

• 抑制重复的日志消息（例如，如果多个对象中缺少相同的类）。

• 改进了更新过程：重写pickle操作码而不是盲目修改一个类。这还允许更新由于缺少类而无法解包的pickle。

0.1 (2009-06-08)

• 第一个版本。