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

KingbaseES 客户端编程开发框架-SQLAlchemy 金仓数据库管理系统 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 支持情况 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.3 配置说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 第 3 章 使用说明 6 第 4 章 程序示例 7 4.1 连接数据库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.2 ORM 基本操作 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 版权声明 10 服务周期承诺 11 I 第 1 章 前言 1 第 章 前言 本文档描述了使用 SQLAlchemy 框架连接和使用操作 KingbaseES 数据库的方法和配置。 前言部分包含以下主题： • 适用读者 • 相关文档 • 术语 • 手册约定 1.1 适用读者 《KingbaseES SQLAlchemy 指南》面向所有使用 KingbaseES 数据库的用户，主要是数据库管理员和应用程序 开发人员。 1.2 相关文档 有关 SQLAlchemy 的更多信息，请参阅以下资源： SQLAlchemy 1.3 Documentation 1.3 术语 无 1 第 1 章 前言 1.4 手册约定 本文档中可能出现“注意、提示、警告、另请参阅”等标志，它们所代表的含义如下： 注意: 用于突出重要/关键信息、最佳实践等。 提示: 用于突出小窍门、捷径等。 警告: 用于传递设备或环境安全警示信息，若不避免，可能会导致设备损坏、数据丢失、设备性能降低或其 它不可预知的结果。 另请参阅: 用于突出参考、参阅等。 以下程序代码书写约定适用于本文档： 符号 说明 [] 表示包含一个或多个可选项。不需要输入中括号本身。 {} 表示包含两个以上（含两个）的候选，必须在其中选取一个。不需要输入花括号本身。 | 分割中括号或者花括号中的两个或两个以上选项。不需要输入“|”本身。 ... 表示其之前的元素可以被重复。 斜体 表示占位符或者需要提供特定值的变量。 大写 表示系统提供的元素，以便与用户定义的元素相互区分。除出现在方括号中的元素外，应当按 照顺序逐字输入。当然，部分元素在系统中是大小写不敏感的，因此用户可以根据系统说明以 小写形式输入。 小写 表示由用户提供的元素。 2 第 2 章 概述 2 第 章 概述 • 框架说明 • 支持情况 • 配置说明 2.1 框架说明 SQLAlchemy 是一个基于 Python 实现的 ORM 框架，该框架建立在 Python DB API 之上，使用关系对象映射 进行数据库操作。 SQLAlchemy 本身无法操作数据库，其必须使用第三方插件，Dialect 用于和数据库交互，根据配置的不同而调 用不同的数据库 API 从而实现对数据库的操作。 3 第 2 章 概述 本章主要说明了 SQLAlchemy 的 Kingbase 方言包如何使用以及方言包使用时应当注意的情况。 2.2 支持情况 由于 SQLAlchemy 的 Kingbase 方言包依赖 ksycopg2，因此方言包的支持情况与 ksycopg2 一致，如下表所示： 表 2.2.1: SQLAlchemy 方言包支持情况 Python 版本 系统架构 说明 Python2.7 Linux amd64 仅提供 64 位支持 Linux aarch64 仅提供 64 位支持 Linux mips64le 仅提供 64 位支持 Windows 提供 32 和 64 位支持，32 位需要 VC9 运行时，64 位需要 VC12 运行时 Linux amd64 仅提供 64 位支持 Linux aarch64 仅提供 64 位支持 Linux mips64le 尚不支持该版本 Python3.5 见续表 4 第 2 章 概述 表 2.2.1 – 续表 Python 版本 系统架构 说明 Windows 提供 32 和 64 位支持，都需要 VC12 运行时 目前提供的 SQLAlchemy 方言包基于 SQLAlchemy1.3.17 制作，在 SQLAlchemy 其他版本上并没有进行充分测 试，可能有不支持的情况。 2.3 配置说明 首先，需要安装 SQLAlchemy，由于 Kingbase 方言包依赖 ksycopg2，还需要配置 ksycopg2，配置的文档可以参 考 KingbaseES 客户端编程接口指南-Python 。 将 Kingbase 方言包放入 SQLAlchemy 下的 dialects 文件夹中即可，如果不确定 SQLAlchemy 的安装路径，可以 在命令行中执行以下语句查看： pip show sqlalchemy 图 2.3.1: 安装路径 如图 1.3.1 所示，其中 Location 的位置即 SQLAlchemy 的安装路径，则需要将方言包放置至” D: \Program Files\Python35\Lib\site-packages\sqlalchemy\dialects”。 5 第3章 使用说明 3 第 章 使用说明 可以使用以下语句连接到数据库： engine = create_engine('kingbase+ksycopg2://SYSTEM:123456@127.0.0.1:54321/TEST') 或 engine = create_engine('kingbase://SYSTEM:123456@127.0.0.1:54321/TEST') 其中，连接串格式为”dialect+driver://username:password@host:port/database”，由于 Kingbase 使用 ksycopg2 作为默认驱动，因此 driver 部分可以省略。 6 第4章 程序示例 4 第 章 程序示例 • 连接数据库 • ORM 基本操作 4.1 连接数据库 from sqlalchemy import create_engine database = "TEST" user = "SYSTEM" password = "123456" host = "127.0.0.1" port = "54321" conn_str = 'kingbase+ksycopg2://{}:{}@{}:{}/{}'.format(user, password, host, port, database) engine = create_engine(conn_str) conn = engine.connect() res = conn.execute("select version()") rows = res.fetchall() print("database version:", rows) 4.2 ORM 基本操作 import sqlalchemy from sqlalchemy.ext.declarative import declarative_base from sqlalchemy import Column, Integer, String from sqlalchemy.orm import sessionmaker 7 第4章 程序示例 from sqlalchemy import create_engine database = "TEST" user = "SYSTEM" password = "123456" host = "127.0.0.1" port = "54321" def getengine(): conn_str = 'kingbase+ksycopg2://{}:{}@{}:{}/{}'.format(user, password, host, port, database) engine = create_engine(conn_str) return engine class test_sqlalchemy(declarative_base()): __tablename__ = 'test_sqlalchemy' num = Column(Integer, primary_key=True) val = Column(String) def __repr__(self): return "(Column: num={}, val={})".format(self.num, self.val) if __name__ == "__main__": engine = getengine() classa1 = declarative_base() classa1.metadata.create_all(engine) session = sessionmaker(bind=engine)() # insert data0 = test_sqlalchemy(num='1', val='ABCDEF123') data1 = test_sqlalchemy(num='100', val='ORM 方式插入数据') data2 = test_sqlalchemy(num='110', val='中文测试数据') session.add(data0) session.add(data1) session.add(data2) # update session.query(test_sqlalchemy).filter(test_sqlalchemy.num == 1).update( {"val": test_sqlalchemy.val + "(append data)"}, synchronize_session=False ) session.commit() 8 第4章 程序示例 # select results = session.query(test_sqlalchemy).all() print(results) session.close() 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