Django+PostgreSQL测试时出现gin_trgm_ops操作符类不存在错误

问题根源 #

生产环境正常但测试环境报错，核心原因是测试数据库初始化时，创建GIN索引的迁移先于pg_trgm扩展的创建迁移执行，或者测试数据库根本没加载pg_trgm扩展。Django测试运行时会重新构建数据库，迁移执行顺序如果不对，就会导致索引创建时找不到对应的操作类。

解决方案 #

1. 调整迁移顺序，确保pg_trgm扩展先被创建

Django的迁移按文件名顺序执行，你需要保证创建pg_trgm扩展的操作在创建GIN索引之前执行：

• 生成空迁移文件用于创建扩展：

  python manage.py makemigrations --empty your_app_name
  

• 打开生成的空迁移文件，修改内容如下：

  from django.db import migrations
  from django.contrib.postgres.operations import CreateExtension
  
  class Migration(migrations.Migration):
      dependencies = [
          # 填写你当前最新的迁移依赖，比如('your_app_name', '0001_initial')
      ]
  
      operations = [
          CreateExtension('pg_trgm'),
      ]
  

• 修改迁移文件名前缀，让它比创建GIN索引的迁移排序更靠前（比如索引迁移是0003_add_gin_index，扩展迁移就命名为0002_create_pg_trgm），确保执行顺序正确。

2. 把创建扩展和索引放在同一个迁移文件里

如果创建索引的迁移是你自定义的，直接在该迁移的operations列表开头加上创建扩展的操作：

from django.db import migrations, models
from django.contrib.postgres.indexes import GinIndex
from django.contrib.postgres.operations import CreateExtension

class Migration(migrations.Migration):
    dependencies = [
        # 填写迁移依赖项
    ]

    operations = [
        CreateExtension('pg_trgm'),
        migrations.AddIndex(
            model_name='your_model',
            index=GinIndex(fields=['your_string_field'], name='yourmodel_str_field_gin_trgm_idx', opclasses=['gin_trgm_ops']),
        ),
    ]

3. 临时验证测试数据库的扩展状态

如果上述方法无效，可以手动检查测试数据库：

• 连接测试数据库后执行SQL查询：

  SELECT * FROM pg_extension WHERE extname = 'pg_trgm';
  

• 如果无结果，手动创建扩展：

  CREATE EXTENSION IF NOT EXISTS pg_trgm;
  

注：此方法为临时方案，建议优先通过迁移持久化解决问题。

额外提示 #

django-cookiecutter默认测试配置会在每次测试时重建数据库，因此必须通过迁移流程确保pg_trgm扩展被自动创建，而非手动操作。

内容的提问来源于stack exchange，提问作者Ubaydullo Ibrohimov