Psycopg2与NumPy 2.0类型适配问题解析

在数据库编程中，Python的Psycopg2库与PostgreSQL的交互是一个常见场景。近期随着NumPy 2.0的发布，一些原本在NumPy 1.x版本下正常工作的Psycopg2代码出现了异常行为，这值得开发者关注。

问题现象

在NumPy 1.26版本中，以下代码可以正常工作：

cursor.execute(
    "INSERT INTO test_np (val) VALUES (%(val)s);",
    {"val": np.float64(1.0)},
)

但在升级到NumPy 2.0.1后，这段代码会抛出psycopg2.errors.InvalidSchemaName异常，提示"schema 'np' does not exist"，这个错误信息相当晦涩难懂。

更有趣的是，如果将类型改为np.float32，则会得到另一个更明确的异常信息psycopg2.ProgrammingError: can't adapt type 'numpy.float32'。

问题根源

深入分析这个问题，主要有两个技术原因：

1. 类型表示变化：NumPy 2.0改变了这些类型的repr()方法输出格式。在1.x版本中，np.float64的表示与Python原生float兼容，而在2.0中则包含了模块名前缀。

2. 继承关系变化：NumPy 2.0中float32类型不再继承自Python的float基类，导致Psycopg2无法自动识别和适配。

值得注意的是，在Psycopg2中，NumPy 1.x的支持实际上是"意外"工作的，并非官方有意为之的兼容性设计。它之所以能工作，完全是因为这些NumPy类型在表示方式和继承关系上恰好与Python原生类型兼容。

解决方案

正确的解决方式是显式注册类型适配器：

from psycopg2.extensions import register_adapter, AsIs

def adapt_numpy_float(numpy_float):
    return AsIs(str(numpy_float))  # 显式转换为字符串更安全

register_adapter(np.float32, adapt_numpy_float)
register_adapter(np.float64, adapt_numpy_float)

这种方案不仅解决了当前问题，而且更加健壮可靠。使用str(numpy_float)而不仅仅是AsIs(numpy_float)可以确保类型表示的一致性。

版本兼容性建议

对于正在使用或计划升级到NumPy 2.0的项目，有以下建议：

1. Psycopg2用户：应当为所有NumPy标量类型显式注册适配器，不要依赖"偶然"的兼容性。

2. 考虑升级到Psycopg3：Psycopg 3.2版本已经官方支持NumPy标量类型，并且针对NumPy 2.0和更早版本都进行了测试，是更可靠的选择。

3. 测试覆盖：在升级NumPy大版本时，应当全面测试所有数据库交互代码，特别是涉及数值类型处理的部分。

总结

这个问题很好地展示了底层库升级时可能带来的微妙兼容性问题。作为开发者，我们应当：

1. 理解依赖库之间的隐式关系
2. 不要依赖于"偶然"工作的实现细节
3. 对于关键功能使用显式、官方支持的方式
4. 保持依赖库版本的同步更新和测试

通过正确注册类型适配器，我们可以确保代码在NumPy 2.0环境下稳定工作，同时也为未来的升级维护打下良好基础。