Django接金仓数据库我踩过的坑和填坑指南开头的故事去年做一个内部管理系统后端用Django客户后来要求数据库换成金仓。当时我心里挺没底的——Django的ORM很依赖数据库方言支持金仓不是Django官方支持的数据库万一跑不起来怎么办查了一圈资料发现金仓官方提供了Django方言包。赶紧搭了个demo验证从环境配置到跑通CRUD前后折腾了小半天。中间踩了几个坑今天就把过程完整的记下来。一、准备工作方言包和驱动1.1 两个东西都得装Django要连金仓需要两样东西ksycopg2金仓的Python驱动底层负责和数据库通信Kingbase方言包告诉Django的ORM怎么生成金仓能认的SQL方言包依赖ksycopg2所以得先装驱动。另外要注意ksycopg2对Python版本有要求我用的是Python 3.8Django 2.2.14这个组合官方测试过比较稳。1.2 找到Django的安装路径方言包要放到Django的backends目录下。可以用pip查看Django装在哪pip show django输出里找Location那一行比如Location: /usr/local/lib/python3.8/site-packages然后把方言包整个目录拷贝到/usr/local/lib/python3.8/site-packages/django/db/backends/kingbase如果backends目录下没有kingbase文件夹新建一个就行。1.3 装对ksycopg2版本方言包是Python写的不分平台。但ksycopg2不同操作系统版本不一样Linux用ksycopg2Windows用ksycopg2-win64。# Linuxpipinstallksycopg2# Windowspipinstallksycopg2-win64装完之后验证一下能不能导入python-cimport ksycopg2; print(ksycopg2.__version__)不报错就说明驱动装好了。二、配置数据库连接2.1 settings.py配置DATABASES{default:{ENGINE:django.db.backends.kingbase,NAME:testdb,# 数据库名USER:system,# 用户名PASSWORD:123456,# 密码HOST:192.168.1.100,# IPPORT:54321,# 端口OPTIONS:{threaded:True,# 多线程环境要开},}}几个关键点ENGINE必须写成django.db.backends.kingbase大小写不能错数据库要提前建好Django不会帮你建如果用连接池或高并发threaded: True建议加上2.2 提前建库Django不会自动创建数据库需要手动连上去建CREATEDATABASEtestdb;建库的时候注意字符集Django默认用UTF-8不配也行。2.3 用DSN字符串代替HOST和PORT如果不想分开写HOST和PORT可以把HOST和PORT都留空在NAME里写完整连接串# 简单格式NAME:192.168.1.100:54321/testdb# 完整DSN格式连RAC时用NAME:(DESCRIPTION(ADDRESS(PROTOCOLTCP)(HOST192.168.1.100)(PORT54321))(CONNECT_DATA(SERVICE_NAMEtestdb)))三、迁移时的注意事项3.1 表名和字段名的长度限制金仓对名称长度限制是30个字符。Django自动生成的表名有时会超比如appname_very_long_model_name。方言包的处理方式是超长就截断最后4个字符用MD5哈希值替换。如果不想让Django改你的表名可以用db_table强制指定classLongModelName(models.Model):namemodels.CharField(max_length50)classMeta:# 用双引号包起来Django就不做转换了db_tablemy_custom_table_name3.2 字段名避开关键字Django会自己处理SQL注入问题但如果字段名刚好是金仓的关键字还是会翻车。特别要注意这几个date、timestamp、number、float。# 容易出问题的写法classEvent(models.Model):datemodels.DateField()# date是关键字timestampmodels.DateTimeField()# timestamp也是关键字改成别的名字或者手动指定db_columnclassEvent(models.Model):event_datemodels.DateField(db_columnevent_date)3.3 NULL和空字符串踩坑Django习惯用空字符串表示空值但金仓把空字符串和NULL当成两回事。方言包的处理逻辑是建表时字段如果允许空字符串会隐式加上nullTrue读数据时如果字段值是NULL自动转成空字符串大多数时候不用操心但如果有业务逻辑依赖区分None和在Django里可能不好实现。一个绕过的方式是给字段设个默认值比如defaultunknown。3.4 TextField的限制金仓的TextField在底层是NCLOB类型这东西有几个限制不能做主键不能建索引不能用在DISTINCT查询里如果模型里有TextField又调用了distinct()会直接报错。绕过去的方法是查的时候先去掉TextField# 会报错User.objects.values(name,bio).distinct()# 先defer掉TextField字段User.objects.defer(bio).values(name).distinct()四、连接池和性能4.1 持久连接配置Django默认每次请求结束就关连接。如果并发量上来频繁开关连接开销不小。可以考虑开启持久连接DATABASES{default:{ENGINE:django.db.backends.kingbase,NAME:testdb,USER:system,PASSWORD:123456,HOST:192.168.1.100,PORT:54321,CONN_MAX_AGE:600,# 连接保持600秒}}CONN_MAX_AGE按秒算设成600就是10分钟。如果数据库服务器有空闲连接超时策略这个值要设得比数据库的小一些。注意Django自带开发服务器每个请求新建一个线程持久连接反而会建很多连接开发环境别开。4.2 多线程配置在生产环境跑Django比如用uWSGI或Gunicorn每个worker是一个独立进程。要加上threaded: TrueOPTIONS:{threaded:True,}这个参数告诉驱动使用线程安全的连接模式。不加的话高并发时候可能会崩。五、代码示例配置文件没问题之后Django的ORM用法和连PostgreSQL/MySQL完全一样。下面是一个完整的例子。models.pyfromdjango.dbimportmodelsclassUser(models.Model):namemodels.CharField(max_length50,uniqueTrue)agemodels.IntegerField()emailmodels.EmailField()created_atmodels.DateTimeField(auto_now_addTrue)classMeta:db_tableapp_user# 表名不要超30字符ordering[-created_at]def__str__(self):returnf{self.name}({self.age})执行迁移python manage.py makemigrations python manage.py migrate如果迁移时报错说表已存在检查一下Meta.db_table是不是和已有表重了。增删改查操作# 插入userUser(name张三,age25,emailzhangsanexample.com)user.save()# 批量插入User.objects.bulk_create([User(name李四,age30,emaillisiexample.com),User(name王五,age28,emailwangwuexample.com),])# 查询usersUser.objects.filter(age__gte18).order_by(-age)foruinusers:print(f{u.name}-{u.age}岁)# 更新User.objects.filter(name张三).update(age26)# 删除User.objects.filter(age__lt18).delete()原生SQL方言包支持fromdjango.dbimportconnectionwithconnection.cursor()ascursor:cursor.execute(SELECT * FROM app_user WHERE age %s,[18])rowscursor.fetchall()forrowinrows:print(row)六、常见问题排查驱动装不上Linux下报错缺少pg_config实际上金仓驱动需要的是ksycopg2不是psycopg2。确认是不是装错了包名。Windows下报编译错误直接装预编译的ksycopg2-win64别从源码编译。迁移时报“relation already exists”可能是之前迁移失败留下残留表。手动删了表再重新迁移或者python manage.py migrate --fake标记为已完成。连接数太多持久连接多线程高并发每个线程都会保持一个连接。适当调低CONN_MAX_AGE或者限制Django Worker数量。时区问题Django的USE_TZTrue默认打开。如果金仓数据库存的是无时区时间查出来会和预期差8小时。要么统一用带时区字段要么设置USE_TZ False。七、总结金仓对Django的适配做得比较完整方言包覆盖了大部分常用场景迁移和ORM基本都能正常工作持多线程和连接池表名、字段名的转换规则比较灵活对金仓特有的类型如CLOB做了一层封装需要注意的地方主要是长度限制、TextFiled的限制、NULL和空字符串的差异。把这些提前了解清楚基本不会卡住。如果你的团队用Django做Web开发数据库要换金仓不用太担心。找个测试环境先跑一遍把项目里超长的表名和关键字字段名处理一下其他大概率能平滑迁移。