1. 问题背景与现象
在Django 4.2及更高版本中，CICharField已被弃用，推荐使用CharField配合db_collation参数来定义不区分大小写的字段。为了实现这一功能，开发者通常会创建数据库排序规则（collation），例如一个名为case_insensitive的排序规则。
一个典型的模型定义可能如下所示，其中name字段使用了自定义的case_insensitive排序规则：
from django.db import models
class MyModel(models.Model):
name = models.CharField(
"Name",
max_length=255,
unique=True,
blank=False,
null=False,
db_collation="case_insensitive"
)
description = models.TextField("Description", blank=True, null=True)
created_at = models.DateTimeField(
"Created at", editable=False, auto_now_add=True, null=True
)
updated_at = models.DateTimeField("Updated at", auto_now=True, null=True)
def __str__(self):
return self.name为了在PostgreSQL数据库中创建这个排序规则，通常会编写一个数据迁移文件，使用django.contrib.postgres.operations.CreateCollation操作。以下是一个最初尝试的迁移代码示例：
# module/migrations/0001_create_case_insensitive_collation.py
from django.db import migrations
from django.contrib.postgres.operations import CreateCollation
def create_collaction(apps, schema_editor):
try:
# 尝试实例化 CreateCollation
CreateCollation(
'case_insensitive',
provider='icu',
locale='und-u-ks-level2',
deterministic=False
)
except Exception as e:
# 错误处理，但这种方式不会实际执行数据库操作
print(f"Error during CreateCollation instantiation: {e}")
class Migration(migrations.Migration):
dependencies = [
('module', ''), # 替换为实际的依赖
]
operations = [
migrations.RunPython(create_collaction),
]在开发或生产环境中运行python manage.py migrate时，这个迁移可能看似成功，因为CreateCollation的实例化过程本身不会抛出错误。然而，当执行python manage.py test时，系统会尝试创建测试数据库并应用所有迁移。此时，会遇到以下错误：
django.db.utils.ProgrammingError: collation "case_insensitive" for encoding "UTF8" does not exist
这表明在测试数据库中，case_insensitive这个排序规则并未被成功创建，导致后续的字段迁移（例如MyModel中的name字段）失败。
2. 问题根源分析：RunPython与CreateCollation的正确用法
上述问题发生的原因在于对migrations.RunPython操作的理解和CreateCollation的误用。
- migrations.RunPython的作用： RunPython操作旨在允许开发者在迁移过程中执行任意的Python代码，通常用于数据迁移或执行复杂的逻辑。它接收一个可调用的函数，这个函数会在迁移应用时被调用，并传入apps和schema_editor两个参数。
- CreateCollation作为迁移操作： CreateCollation本身是一个Django的迁移操作类，它设计用于直接作为operations列表中的一个元素，由Django的迁移系统来解析并生成对应的SQL语句执行。当它直接出现在operations列表中时，Django的SchemaEditor会负责将其转换为数据库命令。
- 误用之处： 在create_collaction函数中，CreateCollation(...)仅仅是实例化了一个Python对象，并没有实际指示schema_editor去执行任何数据库操作。schema_editor对象才是与数据库交互的接口。因此，即使CreateCollation对象被创建了，其对应的SQL语句也未被发送到数据库。
在测试数据库创建过程中，Django会从头开始应用所有迁移。当它到达包含MyModel的迁移时，由于case_insensitive排序规则尚未在测试数据库中创建，便会抛出ProgrammingError。
3. 解决方案：通过schema_editor.execute()创建排序规则
要解决此问题，我们需要在RunPython操作中，利用传入的schema_editor对象直接执行创建排序规则的SQL语句。这样可以确保在迁移函数被调用时，实际的数据库操作会被执行。
以下是修正后的迁移代码：
# module/migrations/0001_create_case_insensitive_collation.py
from django.db import migrations
def create_collaction(apps, schema_editor):
"""
在数据库中创建 'case_insensitive' 排序规则。
"""
try:
# 直接使用 schema_editor.execute() 执行 SQL 语句
schema_editor.execute(
'CREATE COLLATION case_insensitive (provider = icu, locale = und-u-ks-level2, deterministic = false)'
)
print("Collation 'case_insensitive' created successfully.")
except Exception as e:
# 打印错误信息，以便调试
print(f"Error creating collation 'case_insensitive': {e}")
def reverse_collaction(apps, schema_editor):
"""
在回滚迁移时删除 'case_insensitive' 排序规则。
"""
try:
schema_editor.execute('DROP COLLATION IF EXISTS case_insensitive')
print("Collation 'case_insensitive' dropped successfully during rollback.")
except Exception as e:
print(f"Error dropping collation 'case_insensitive': {e}")
class Migration(migrations.Migration):
dependencies = [
# 确保这里包含你的应用模块的最新依赖，例如 ('your_app_name', '0000_initial')
# 如果这是你应用中的第一个迁移，可以留空或指向上一个应用的最后一个迁移
# 例如：('auth', '0012_alter_user_first_name_max_length'),
]
operations = [
migrations.RunPython(create_collaction, reverse_collaction),
]代码解析：
- schema_editor.execute(...)： 这是关键所在。schema_editor对象提供了直接执行SQL命令的能力。我们将CREATE COLLATION的完整SQL语句作为字符串传递给它。
-
CREATE COLLATION语句：
- case_insensitive：要创建的排序规则的名称。
- provider = icu：指定排序规则的提供者为ICU（International Components for Unicode）。ICU提供了更全面和语言感知的排序功能。
- locale = und-u-ks-level2：定义了排序规则的语言环境和行为。und表示未指定语言，u-ks-level2是Unicode扩展，表示不区分大小写（case-insensitive）和不区分重音（accent-insensitive）的排序，通常用于实现精确的不区分大小写比较。
- deterministic = false：设置为false表示该排序规则是不确定的，即对于某些字符，其排序结果可能不唯一或依赖于上下文。对于不区分大小写的比较，通常需要设置为false，因为它意味着'a'和'A'被认为是相等的。如果设置为true，则会强制严格的二进制比较，可能导致不区分大小写比较失效。
- reverse_collaction函数： 为了使迁移可逆，我们添加了一个reverse_collaction函数，它在回滚此迁移时会删除之前创建的排序规则。这是RunPython操作的最佳实践。
- try...except块： 捕获可能发生的数据库错误，提高代码的健壮性。
应用此修正后，当你再次运行python manage.py test时，测试数据库在应用此迁移时会正确创建case_insensitive排序规则，从而解决ProgrammingError。
4. 注意事项
- PostgreSQL ICU支持： 确保你的PostgreSQL服务器已安装并配置了ICU支持。如果PostgreSQL没有ICU支持，provider = icu将导致错误。在大多数现代PostgreSQL安装中，ICU支持是默认提供的，但如果遇到问题，请检查PostgreSQL的安装和配置。
- 迁移顺序： 包含CREATE COLLATION的迁移必须在任何使用该排序规则的字段迁移之前执行。Django的迁移系统通常会处理好依赖关系，但如果排序规则的创建和使用在不同的应用中，或者依赖关系复杂，需要手动检查dependencies。
- 命名约定： 排序规则的名称应具有描述性且在数据库中唯一。
- deterministic参数： 理解deterministic参数对排序行为的影响至关重要。对于不区分大小写的比较，通常需要deterministic = false。
- locale参数： locale参数的精确值可能因PostgreSQL版本和操作系统而异。und-u-ks-level2是一个通用的Unicode ICU locale，但你也可以根据具体语言需求调整，例如en-u-ks-level2表示英文不区分大小写。
5. 总结
在Django项目中，当从CICharField迁移到CharField并使用db_collation定义不区分大小写的字段时，确保在测试环境中正确创建自定义排序规则是至关重要的。通过在migrations.RunPython操作中，利用schema_editor.execute()直接执行CREATE COLLATION SQL语句，可以有效解决测试数据库中排序规则缺失的问题。同时，理解CREATE COLLATION语句的参数含义以及迁移的可逆性，是编写健壮Django应用的关键。
