如何确保Django数据库采用UTF8排序规则及启动时校验错误排序规则

我来分享两个问题的实用解决方案，都是在Django项目里常用的实践：

1. 确保Django创建的数据库使用UTF8排序规则 #

不同数据库的配置方式略有不同，以下是主流数据库的设置方法：

MySQL/MariaDB #

推荐使用utf8mb4编码（比标准utf8支持更多字符，比如emoji），在settings.py的数据库配置中添加OPTIONS指定编码和排序规则：

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'your_database_name',
        'USER': 'your_db_user',
        'PASSWORD': 'your_db_password',
        'HOST': 'localhost',
        'PORT': '3306',
        'OPTIONS': {
            'charset': 'utf8mb4',
            'collation': 'utf8mb4_unicode_ci',  # 这是UTF8排序规则的常用选项
        },
    }
}

如果是手动创建数据库，也可以提前指定：

CREATE DATABASE your_database_name CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

PostgreSQL #

PostgreSQL默认的UTF-8编码通常就能满足需求，排序规则可以根据语言选择（比如en_US.UTF-8）。确保配置里指定客户端编码：

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'your_database_name',
        'USER': 'your_db_user',
        'PASSWORD': 'your_db_password',
        'HOST': 'localhost',
        'PORT': '5432',
        'OPTIONS': {
            'client_encoding': 'UTF8',
        },
    }
}

如果要手动创建数据库并指定排序规则：

CREATE DATABASE your_database_name WITH ENCODING 'UTF8' LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8';

SQLite #

SQLite默认使用UTF-8编码，一般无需额外配置，若要明确指定：

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
        'OPTIONS': {
            'encoding': 'utf-8',
        },
    }
}

2. 优雅检测已有数据库的排序规则错误并在启动时告警 #

你的临时方案通过查询触发异常的方式虽然有效，但不够直接和清晰。更优雅的做法是利用Django的AppConfig.ready()钩子，在应用启动时主动检查数据库配置：

实现步骤 #

1. 在你的主应用（比如myapp）的apps.py中重写ready()方法，添加排序规则检查逻辑：

from django.apps import AppConfig
from django.db import connection
from django.core.exceptions import ImproperlyConfigured

class MyAppConfig(AppConfig):
    default_auto_field = 'django.db.models.BigAutoField'
    name = 'myapp'

    def ready(self):
        # 启动时执行数据库排序规则检查
        self.validate_database_collation()

    def validate_database_collation(self):
        # 根据你的需求定义所需的排序规则
        required_collation = 'utf8mb4_unicode_ci'
        db_vendor = connection.vendor

        try:
            with connection.cursor() as cursor:
                if db_vendor == 'mysql':
                    # 查询MySQL当前数据库的排序规则
                    cursor.execute("SELECT @@collation_database;")
                elif db_vendor == 'postgresql':
                    # 查询PostgreSQL当前数据库的排序规则
                    cursor.execute("SELECT datcollate FROM pg_database WHERE datname = current_database();")
                elif db_vendor == 'sqlite':
                    # SQLite默认UTF-8，可简化检查
                    cursor.execute("PRAGMA encoding;")
                    result = cursor.fetchone()
                    if result and result[0].upper() != 'UTF-8':
                        raise ImproperlyConfigured(f"SQLite数据库编码错误，当前为{result[0]}，需要UTF-8")
                    return
                else:
                    # 其他数据库类型暂时跳过检查
                    return

                current_collation = cursor.fetchone()[0]
                if current_collation != required_collation:
                    raise ImproperlyConfigured(
                        f"数据库排序规则不匹配！当前为「{current_collation}」，需要「{required_collation}」。"
                        "\n请修改数据库排序规则后重新启动服务。"
                    )
        except Exception as e:
            raise ImproperlyConfigured(f"检查数据库排序规则时发生错误：{str(e)}")

2. 在settings.py的INSTALLED_APPS中替换为自定义的AppConfig：

INSTALLED_APPS = [
    # ... 其他应用
    'myapp.apps.MyAppConfig',  # 替换成你的AppConfig路径
    # ...
]

这种方案的优势 #

• 更直接：主动查询数据库配置，而非依赖间接的查询异常
• 更清晰：抛出Django标准的ImproperlyConfigured异常，错误信息明确，便于排查
• 更符合Django规范：利用ready()钩子完成初始化检查，契合框架启动流程
• 更灵活：可针对不同数据库类型编写适配的检查逻辑

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