如何通过Django模型为PostgreSQL数据库字段添加描述？

Got it, let's figure out how to add those field descriptions (which show up as the Description column in PostgreSQL's \d+ output) through Django's ORM and sync them to your database. Here are the best ways to do this, depending on your Django version:

1. Django 3.2及以上（最简单的方法） #

Django 3.2引入了db_comment字段参数，它会直接映射到PostgreSQL的字段注释（也就是你在\d+里看到的Description）。

操作步骤： #

• 修改你的模型字段，添加db_comment参数：

  from django.db import models
  
  class DjangoModel(models.Model):
      i = models.IntegerField(db_comment="存储功能X的整数值")
      j = models.IntegerField(db_comment="用于相关记录的排序和筛选")
  

• 生成新的迁移文件：

  python manage.py makemigrations
  

• 执行迁移，将变更同步到数据库：

  python manage.py migrate
  

• 验证效果：在PostgreSQL shell里运行\d+ django_model，你会看到Description列已经填充了设置的文本。

2. Django 3.2以下版本（自定义迁移或字段） #

如果你还在使用旧版Django，有两种可靠的方案：

方案A：用RunSQL自定义迁移 #

创建一个空迁移，手动添加SQL命令来设置字段注释：

1. 为你的应用生成空迁移：

   python manage.py makemigrations your_app_name --empty
   

2. 打开生成的迁移文件，修改为包含RunSQL操作：

   from django.db import migrations
   
   class Migration(migrations.Migration):
       dependencies = [
           # 替换成你上一个迁移文件的名称，比如('your_app', '0001_initial')
           ('your_app', '0001_initial'),
       ]
   
       operations = [
           migrations.RunSQL(
               "COMMENT ON COLUMN django_model.i IS '存储功能X的整数值';",
               # 回滚时清空注释的命令
               reverse_sql="COMMENT ON COLUMN django_model.i IS '';"
           ),
           migrations.RunSQL(
               "COMMENT ON COLUMN django_model.j IS '用于相关记录的排序和筛选';",
               reverse_sql="COMMENT ON COLUMN django_model.j IS '';"
           ),
       ]
   

3. 执行迁移：

   python manage.py migrate
   

方案B：可复用的自定义字段 #

如果你需要给多个模型的字段添加注释，可以创建一个自定义字段类自动处理：

from django.db import models

class DescribedIntegerField(models.IntegerField):
    def __init__(self, description=None, *args, **kwargs):
        self.description = description
        super().__init__(*args, **kwargs)

    def sql_create(self, connection, style):
        sql, params = super().sql_create(connection, style)
        # 只对PostgreSQL生效
        if self.description and connection.vendor == 'postgresql':
            table_name = self.model._meta.db_table
            column_name = self.column
            comment_sql = (
                f"COMMENT ON COLUMN {table_name}.{column_name} IS %s;"
            )
            sql += (comment_sql,)
            params += (self.description,)
        return sql, params

然后在模型中使用这个字段：

class DjangoModel(models.Model):
    i = DescribedIntegerField(description="存储功能X的整数值")
    j = DescribedIntegerField(description="用于相关记录的排序和筛选")

像往常一样生成并执行迁移——创建表或字段时会自动添加注释。

注意事项 #

• 执行迁移前一定要备份数据库，尤其是修改 schema 细节的时候。
• 在PostgreSQL中，字段注释存储在pg_description系统表中，这些变更不会影响数据或性能。

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