KingbaseES客户端编程开发框架-Django.pdf

KingbaseES 客户端编程开发框架-Django 金仓数据库管理系统 KingbaseES 文档版本：V9（V009R001C001B0024） 发布日期：2023 年 10 月 12 日 北京人大金仓信息技术股份有限公司 目 目 录 录 第 1 章 前言 1 1.1 适用读者 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.3 术语 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.4 手册约定 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 2 章 概述 3 2.1 框架说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2 支持情况 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.3 配置说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 第 3 章 使用说明 5 3.1 连接数据库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.2 完整的 DSN 和 Easy Connet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.3 线程选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.4 命名问题 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.5 NULL 和空字符串 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.6 TextField 限制 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 第 4 章 通用注意事项 8 4.1 持久连接 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.2 连接管理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.3 附加说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.4 编码 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 版权声明 10 服务周期承诺 11 I 第 1 章 前言 1 第 章 前言 本文档描述了 Django 框架的基本介绍，和 Kingbase 数据库对其兼容和配置使用方法。 前言部分包含以下主题： • 适用读者 • 相关文档 • 术语 • 手册约定 1.1 适用读者 《KingbaseES Django 指南》面向所有使用 KingbaseES 数据库的用户，主要是数据库管理员和应用程序开发人 员。 1.2 相关文档 有关 Django 的更多信息，请参阅以下资源： Django 文档 1.3 术语 无 1 第 1 章 前言 1.4 手册约定 本文档中可能出现“注意、提示、警告、另请参阅”等标志，它们所代表的含义如下： 注意: 用于突出重要/关键信息、最佳实践等。 提示: 用于突出小窍门、捷径等。 警告: 用于传递设备或环境安全警示信息，若不避免，可能会导致设备损坏、数据丢失、设备性能降低或其 它不可预知的结果。 另请参阅: 用于突出参考、参阅等。 以下程序代码书写约定适用于本文档： 符号 说明 [] 表示包含一个或多个可选项。不需要输入中括号本身。 {} 表示包含两个以上（含两个）的候选，必须在其中选取一个。不需要输入花括号本身。 | 分割中括号或者花括号中的两个或两个以上选项。不需要输入“|”本身。 ... 表示其之前的元素可以被重复。 斜体 表示占位符或者需要提供特定值的变量。 大写 表示系统提供的元素，以便与用户定义的元素相互区分。除出现在方括号中的元素外，应当按 照顺序逐字输入。当然，部分元素在系统中是大小写不敏感的，因此用户可以根据系统说明以 小写形式输入。 小写 表示由用户提供的元素。 2 第 2 章 概述 2 第 章 概述 • 框架说明 • 支持情况 • 配置说明 2.1 框架说明 Django 是一个高水准的 Python 编程语言驱动的开源模型，是视图、控制器风格的 Web 应用程序框架，它起源 于开源社区。使用这种架构，程序员可以方便快捷地创建高品质、易维护、数据库驱动的应用程序。 相关的官方文档可以访问 https://docs.djangoproject.com 。 本章主要说明了 Django 的 KingbaseES 方言包如何使用以及方言包使用时应当注意的情况。 2.2 支持情况 由于 Django 的 KingbaseES 方言包依赖 ksycopg2，因此方言包的支持情况与 ksycopg2 一致，如下表所示： 表 2.2.1: Django 方言包支持情况 Python 版本 系统架构 说明 Python2.7 Linux amd64 仅提供 64 位支持 Linux aarch64 仅提供 64 位支持 Linux mips64le 仅提供 64 位支持 Windows 提供 32 和 64 位支持，32 位需要 VC9 运行时，64 位需要 VC12 运行时 见续表 3 第 2 章 概述 表 2.2.1 – 续表 Python 版本 系统架构 说明 Python3.5 Linux amd64 仅提供 64 位支持 Linux aarch64 仅提供 64 位支持 Linux mips64le 尚不支持该版本 Windows 提供 32 和 64 位支持，都需要 VC12 运行时 目前提供两个 Django 方言包，一个基于 Django1.11.29(支持 Python2.7 和 Python3) 制作，另一个基于 Django2.2.14(仅支持 Python3)，在 Django 其他版本上并没有进行充分测试，可能有不支持的情况。 2.3 配置说明 首先，需要安装 Django，由于 KingbaseES 方言包依赖 ksycopg2，还需要配置 ksycopg2，配置的文档可以参考 KingbaseES 客户端编程接口指南-Python 。 将 KingbaseES 方言包放入 Django 下的 dialects 文件夹中即可，如果不确定 Django 的安装路径，可以在命令行 中执行以下语句查看： pip show django 图 2.3.1: 命令行中执行语句 如图 1.3.1 所示，其中 Location 的位置即 Django 的安装路径，则需要将方言包放至” D: \Program Files\Python35\Lib\site-packages\django\db\backends”。 4 第3章 使用说明 3 第 章 使用说明 • 连接数据库 • 完整的 DSN 和 Easy Connet • 线程选项 • 命名问题 • NULL 和空字符串 • TextField 限制 3.1 连接数据库 打开 settings.py 文件，然后修改 DATABASE 下的 default 键值进行修改即可。 DATABASES = { 'default': { 'ENGINE': 'django.db.backends.kingbase', 'NAME': 'TEST', 'USER': 'SYSTEM', 'PASSWORD': '123456', 'HOST': '127.0.0.1', 'PORT': '54321', } } Django 不会自动创建数据库，因此需要手动创建数据库，即在数据库命令行交互模式执行以下命令： CREATE DATABASE TEST; 5 第3章 3.2 使用说明 完整的 DSN 和 Easy Connet 如果 HOST 和 PORT 都为空，则可以在 NAME 中使用一个完整的 DSN 或者 Easy Connet 。例如，在使用没 有 tnsnames.ora 的 RAC 或可插入数据库时，需要使用这种格式。 Easy Connet 字符串示例： 'NAME': 'localhost:1521/kdb1', 完整的 DSN 字符串示例： 'NAME':( '(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521)))' '(CONNECT_DATA=(SERVICE_NAME=kdb1))' ), 3.3 线程选项 如果你准备在一个多线程环境中运行 Django （例如，在任何现有操作系统上使用默认 MPM 模块的 Apache）， name 必须将 KingbaseES 数据库设置的 threaded 选项设置为 True： 'OPTIONS':{ 'threaded':True, }, 3.4 命名问题 KingbaseES 规定名称长度限制为 30 个字符。为了适应这一限制，后端将截断数据库标识符，用可重复的 MD5 散列值替换截断后的名称的最后四个字符。此外，后端将数据库标识符转换为全大写。 为了防止这些转换（通常只在处理遗留数据库或访问属于其他用户的表时），使用一个带引号的名称作为 db_table 的值： class LegacyModle(models.Model): class Meta: da_table = '"name_left_in_lowercase"' class ForeignModel(modles.Model): class Meta: da_table = '"OTHER_USER"."NAME_ONLY_SEEMS_OVER_30"' 6 第3章 使用说明 当运行 migrate 时，如果某些 KingbaseES 关键字被用作 model 字段的名称或 db_column 选项的值，可能会发 生错误。Django 引用查询中使用的所有标识符，来防止大多数此类问题，但当使用 KingbaseES 数据类型作为列名 时，仍然可能发生错误。特别要避免使用日期、时间戳、数字或浮点数作为字段名。 3.5 NULL 和空字符串 Django 通常使用空字符串 (’ ’) 而不是 NULL，但是 KingbaseES 对两者的处理是相同的。为了解决这个问题， KingbaseES 服务端会忽略有空字符串作为可能值的字段上的显式 null 选项，并生成 DDL，就像 null=True 一样。 当从数据库中取值时，会假设这些字段之一中的 NULL 值确实表示空字符串，并且数据被静默转换以反映此假设。 3.6 TextField 限制 KingbaseES 服务端将 TextFields 存储为 NCLOB 列，并且通常对此类 LOB 列的使用附加了一些限制： • LOB 列不能用作主键。 • LOB 列不能再索引中使用。 • LOB 列不能再列表中使用。这意味着在 Kingbase 上运行时，尝试在包含 TextField 列的模型上使用 QuerySet. distinct 方法将导致发生错误。一种解决办法是，将 QuerySet.defer 方法与 distinct() 结合使用，以防止 TextField 列包含在 SELECT DISTINCT 列表中。 7 第4章 4 第 章 通用注意事项 通用注意事项 • 持久连接 • 附加说明 • 编码 4.1 持久连接 持久连接避免了在每次请求中重新建立数据库连接的开销。这由 CONN_MAX_AGE 参数控制，该参数定义了 一个连接的最大时长。该参数可以为每个数据库独立设置。 默认值为 0，每次请求结束时关闭数据库连接。要启动持久连接，可将 CONN_MAX_AGE 设置为正整数，单 位为秒。需要无限制的持久连接，则将其设置为 None 。 4.2 连接管理 当 Django 第一次进行数据库查询时，就会打开一个与数据库的连接。它保持这个连接的开放性，并在以后的请 求中重复使用。一旦连接超过了 CONN_MAX_AGE 定义的最大时长，或者当它不再可用时，Django 就会关闭这个 连接。 当 Django 需要连接数据库时，如果此时还没有连接，或者上一个连接已关闭，Django 就会自动打开一个与数据 库的连接。 在每次请求开始时，如果连接已达到最大时长，Django 就会关闭连接。如果需要数据库在一段时间后终止空闲 的连接，应该将 CONN_MAX_AGE 设置为一个较低的值，这样 Djang 就不会尝试使用一个已经被数据库服务器终 止的连接。 在每个请求结束时，如果连接已达到最大时长，或者连接处于不可恢复的错误状态，Django 就会关闭连接。如 果在处理请求的过程中发生了任何数据库错误，Django 会检查连接是否还能使用。如果不能使用，则关闭连接。因 此，数据库错误最多影响一个请求；如果连接变得不可用，下一个请求就会得到一个新的连接。 8 第4章 4.3 通用注意事项 附加说明 由于每个线程都要保持一个自己的连接，所以数据库必须支持至少与工作线程数一样多的同时连接。 如 果 是 外 部 系 统 的 数 据 库， 或 者 由 于 缓 存 的 原 因， 数 据 库 不 会 被 太 多 视 图 访 问。 这 时， 应 该 将 ** CONN_MAX_AGE** 设置为一个较小的值，甚至是 0。因为保持一个不太可能被重复使用的连接是没有意义 的。这样就能保持这个数据库的同时连接数较少。 开发服务器每处理一个请求都会创建一个新的线程，消除了持久连接的影响。在开发过程中不要启用持久连接。 当 Django 建立与数据库的连接时，它会根据所使用的后端来设置相应的参数。如果启用持久连接，则将不再在 每个请求中重复此设置。如果您修改了连接的隔离级别或者时区等参数，应该在每个请求结束时恢复 Django 的默认 值，在每个请求开始时强制设定一个适当的值，或禁用持久连接。 4.4 编码 Django 默认所有数据库都是用的 UTF-8 编码。对于在 Django 中有效的数据，使用其它编码可能会导致意外情 况。例如，数据库中的“值过长”错误。 9 版权声明 版权声明 北京人大金仓信息技术股份有限公司（简称：人大金仓）版权所有，并保留对本手册及本声明的一切权利。 未得到人大金仓的书面许可，任何人不得以任何方式或形式对本手册内的任何部分进行复制、摘录、备份、修 改、传播、翻译成其他语言、将其全部或部分用于商业用途。 免责声明 本手册内容依据现有信息制作，由于产品版本升级或其他原因，其内容有可能变更。人大金仓保留在没有任何通 知或者提示的情况下对手册内容进行修改的权利。 本手册仅作为使用指导，人大金仓在编写本手册时已尽力保证其内容准确可靠，但并不确保手册内容完全没有错 误或遗漏，本手册中的所有信息也不构成任何明示或暗示的担保。 技术支持 • 人大金仓官方网站：http://www.kingbase.com.cn/ • 人大金仓文档中心：http://help.kingbase.com.cn/ • 全国服务热线：400-601-1188 • 人大金仓技术支持与反馈信箱：support@kingbase.com.cn 10 服务周期承诺 服务周期承诺 由于市场需求在不断变化，技术创新和发展的进程不断加剧，产品的版本更迭不可避免。人大金仓对于产品版本 生命周期的有效管理，有助于您提前规划项目，更好地从产品服务终止上过渡。 表 1: KingbaseES 产品生命周期里程碑 关键里程碑点 定义 产品发布日期 产品正式发布版本，即 GA（general availability）版本的发布日期。 停止销售日期 正式停止销售的日期，版本停止接受订单日。该日之后，产品将不再销售。 停止功能升级日期 在该日期之后，不再提供新特性和新硬件支持。但依旧提供错误修复、安全修复、功 能维护等服务。 停止功能维护日期 在该日期之后，不再维护功能，修复问题。但依旧提供安全修复等服务 停止安全维护日期 在该日期之后，不再发布补丁版本修复中高风险漏洞，仅提供有限的支持。 产品服务终止日期 停止提供产品服务和支持的日期。包括软件维护版本，缺陷修复，以及针对该产品的 所有服务支持（包括服务热线和远程/现场支持）。 服务周期策略 金仓数据库管理系统 KingbaseES 产品确保以下的服务周期： 1）产品自发布之日起至产品停止功能升级（包含新特性、新硬件支持）之日不少于 5 年。 2）产品停止功能升级之日起至产品停止功能维护（主要包括问题修复）之日不少于 4 年。 3）产品功能维护停止之日起至产品停止安全维护（包括中高风险漏洞修复）之日不少于 2 年。 服务终止策略 金仓数据库管理系统 KingbaseES 产品确保在销售后，至少提供 6 年的服务支持。 注意: 人大金仓将会综合各方因素来确定产品服务终止日期。并将在实际产品服务终止日期之前至少 90 天，通过公 11 服务周期承诺 开方式宣布产品服务终止日期。 12