mysqlclient 连接 OceanBase 数据库示例程序

本文将介绍如何使用 mysqlclient 和 OceanBase 数据库构建一个应用程序，实现创建表、插入数据和查询数据等基本操作。

点击下载 python-mysqlclient 示例工程 mysqlclient 连接 OceanBase 数据库示例程序（MySQL 模式）

前提条件

• 您已安装 Python 3.x 和 pip。
• 您已安装 OceanBase 数据库并且创建了 MySQL 模式租户。

操作步骤

1. 检查 Python 和 pip 的版本。
2. 安装 mysqlclient 库。
3. 获取 OceanBase 数据库连接信息。
4. 修改 config.py 文件中的数据库连接信息。
5. 运行 main.py 文件。
6. 在交互式命令行界面进行相应的操作。

步骤一：检查 Python 和 pip 的版本

打开命令提示符或 PowerShell 终端，运行 python --version 和 pip --version 命令，确保 Python 和 pip 正常安装。

示例如下：

PS C:\Windows\system32> python --version
Python 3.11.2
PS C:\Windows\system32> pip --version
pip 23.3.1 from C:\Users\xxx\AppData\Local\Programs\Python\Python311\Lib\site-packages\pip (python 3.11)

步骤二：安装 mysqlclient 库

mysqlclient 是一个基于 C 语言实现的 MySQL 客户端库，性能较高，适合对性能要求较高的场景。安装 mysqlclient 库时，需要编译和链接 MySQL C API 来连接 OceanBase 数据库。

步骤三：获取 OceanBase 数据库连接信息

联系 OceanBase 数据库部署人员或者管理员获取相应的数据库连接串。

obclient -h$host -P$port -u$user_name -p$password -D$database_name

参数说明：

• $host：提供 OceanBase 数据库连接 IP。OceanBase 数据库代理（OceanBase Database Proxy，ODP）连接方式使用的是一个 ODP 地址；直连方式使用的是 OBServer 节点的 IP 地址。

• $port：提供 OceanBase 数据库连接端口。ODP 连接的方式默认是 2883，在部署 ODP 时可自定义；直连方式默认是 2881，在部署 OceanBase 数据库时可自定义。

• $database_name：需要访问的数据库名称。

  注意

  连接租户的用户需要拥有该数据库的 CREATE、INSERT 和 SELECT 权限。更多有关用户权限的信息，请参见 MySQL 模式下的权限分类。

• $user_name：提供租户的连接账户。ODP 连接的常用格式：用户名@租户名#集群名 或者 集群名:租户名:用户名；直连方式格式：用户名@租户名。

• $password：提供账户密码。

更多连接串的信息，请参见 通过 OBClient 连接 OceanBase 租户。

示例如下：

obclient -hxxx.xxx.xxx.xxx -P2881 -utest_user001@mysql001 -p****** -Dtest

步骤四：修改 config.py 文件中的数据库连接信息

根据 步骤三：获取 OceanBase 数据库连接信息 中的信息修改文件 python-mysqlclient/config.py 中的数据库连接信息。

1. 进入 python-mysqlclient 项目文件夹。

2. 修改 config.py 文件中的数据库连接信息。

   • 在 Windows 环境下，使用文本编辑器打开 config.py 文件，修改文件中的数据库连接信息，确保与实际情况相符。
   • 在 Linux 环境下，可以使用 vi config.py 或者 vim config.py 命令编辑 config.py 文件，修改文件中的数据库连接信息，确保与实际情况相符。

   config.py 文件中的数据库连接信息示例如下：

   OCEANBASE_CONFIG = {
       'host': '10.10.10.1',
       'port': 2881,
       'user': 'test_user001@mysql001',
       'password': '******',
       'database': 'test',
       'charset': 'utf8mb4'
   }
   

步骤五：运行 main.py 文件

打开命令提示符或 PowerShell 终端，运行 python main.py 命令启动程序。

1. 进入到 python-mysqlclient 项目目录下。

   示例如下：

   cd /home/admin/python-mysqlclient
   

2. 运行以下命令启动 main.py 程序。

   python main.py
   

   返回结果如下：

   Table created successfully
   Instruction: 1.Insert Data; 2.Query Data; 3.Exit.
   Enter the command [1/2/3]>
   

步骤六：在交互式命令行界面进行相应的操作

• 插入数据成功示例。

  1. 在交互式命令行界面，输入指令 1，按回车键。

     示例如下：

     Enter the command [1/2/3]> 1
     

  2. 在提示 Enter name: 后，输入姓名，按回车键。

     示例如下：

     Enter name：A1
     

  3. 在提示 Enter age: 后，输入年龄，按回车键。

     示例如下：

     Enter age：18
     

  4. 返回插入数据成功，显示 Record inserted successfully。最后，显示指令说明，提示用户可以输入 1、2 或 3，按回车键执行相应操作。

     示例如下：

     Record inserted successfully
     Instruction: 1.Insert Data; 2.Query Data; 3.Exit.
     Enter the command [1/2/3]>
     

• 插入数据失败示例。

  1. 在交互式命令行界面，输入指令 1，按回车键。

     示例如下：

     Enter the command [1/2/3]> 1
     

  2. 在提示 Enter name: 后，输入姓名，按回车键。

     示例如下：

     Enter name：A2
     

  3. 在提示 Enter age: 后，输入年龄，按回车键。

     注意

     字段年龄的数据类型是整型。

     示例如下：

     Enter age：十八
     

  4. 返回插入数据错误信息，显示 (1366, 'Incorrect integer value')。最后，显示指令说明，提示用户可以输入 1、2 或 3，按回车键执行相应操作。

     示例如下：

     (1366, 'Incorrect integer value')
     Instruction: 1.Insert Data; 2.Query Data; 3.Exit.
     Enter the command [1/2/3]>
     

• 查询数据示例。

  1. 在交互式命令行界面，输入指令 2，按回车键。

     示例如下：

     Enter the command [1/2/3]> 2
     

  2. 显示表的数据。最后，显示指令说明，提示用户可以输入 1、2 或 3，按回车键执行相应操作。

     示例如下：

     (1, 'A1', 18)
     Instruction: 1.Insert Data; 2.Query Data; 3.Exit.
     Enter the command [1/2/3]>
     

• 输入错误指令示例。

  1. 在交互式命令行界面，输入一个不是 1/2/3 的，按回车键。

     示例如下：

     Enter the command [1/2/3]> A
     

  2. 返回错误信息，显示 Invalid command, please enter command again [1/2/3]。最后，显示指令说明，提示用户可以输入 1、2 或 3，按回车键执行相应操作。

     示例如下：

     Invalid command, please enter command again [1/2/3]
     Instruction: 1.Insert Data; 2.Query Data; 3.Exit.
     Enter the command [1/2/3]>
     

• 退出程序示例。

  在交互式命令行界面，输入指令 3，按回车键退出程序。

  示例如下：

  Enter the command [1/2/3]> 3
  

项目代码介绍

点击 python-mysqlclient 下载项目代码，是一个名称为 python-mysqlclient.zip 的压缩包。

解压后，得到一个名为 python-mysqlclient 的文件夹。目录结构如下所示：

python-mysqlclient
├── config.py
├── db.py
├── main.py
└── requirements.txt

文件说明：

• config.py：用于管理数据库连接配置信息。

• db.py：用于操作数据库，包括创建表、插入数据、查询数据等。

• main.py：应用程序的入口，包含了简单的用户交互界面，用户可以通过输入命令来执行相应的操作。

• requirements.txt：列出了项目所需的 Python 库。

  说明

  本文获取的代码中只列出了 mysqlclient 库的版本要求，可以通过 pip install -r requirements.txt 命令安装，执行以上命令后，会自动安装所需的库。

config.py 代码介绍

使用 Python 连接数据库时需要指定数据库连接参数，可以将这些参数放在一个单独的配置文件中，比如 config.py 文件。将这些参数封装在一个字典中，可以避免在每个文件中都重复写入这些参数的麻烦，直接在其他 Python 文件中引用该字典来连接数据库即可。

本文获取的 config.py 文件中的代码定义了一个名为 OCEANBASE_CONFIG 的字典变量，用于管理 OceanBase 数据库连接参数。

代码如下：

OCEANBASE_CONFIG = {
    'host': 'localhost',
    'port': 2881,  # 默认端口，可根据实际情况修改
    'user': 'user_name',
    'password': '',
    'database': 'db_name',
    'charset': 'utf8mb4'
}

参数解释：

• host：提供 OceanBase 数据库连接 IP。ODP 连接方式使用的是一个 ODP 地址；直连方式使用的是 OBServer 节点的 IP 地址。
• port：提供 OceanBase 数据库连接端口。默认是 2881；使用 ODP 的时，默认端口是 2883。
• user：连接数据库的用户名。直连格式：{用户名}@{租户名}；ODP 连接格式：{用户名称}@{租户名称}#{集群名称}。更多连接 OceanBase 数据库的信息，请参见 连接方式概述。
• password：连接数据库的密码。
• database：要连接的数据库名。
• charset：连接数据库时使用的字符集。

db.py 代码介绍

db.py 文件是一个 Python 语言编写的封装数据库操作的模块，主要用于实现数据库的增删改查操作。

该文件中主要包括以下几个部分：

1. 导入 MySQLdb 模块和导入数据库连接参数。

   代码如下：

   import MySQLdb
   from config import OCEANBASE_CONFIG
   

2. 定义创建表的函数。

   定义函数 create_table，该函数的作用是在 OceanBase 数据库中创建名为 test_tbl1 的表。使用 with 语句管理数据库连接和游标对象的生命周期，保证了数据库连接和游标对象的安全关闭，避免了内存泄漏等问题。定义 SQL 语句，执行 SQL 语句，打印输出执行结果或异常信息。

   代码如下：

   def create_table():
       with MySQLdb.connect(**OCEANBASE_CONFIG) as conn:
           with conn.cursor() as cursor:
               try:
                   create_table_sql = """
                       CREATE TABLE test_tbl1 (
                           id INT UNSIGNED NOT NULL AUTO_INCREMENT,
                           name VARCHAR(50) NOT NULL,
                           age INT UNSIGNED NOT NULL,
                           PRIMARY KEY (id)
                       ) ENGINE=OCEANBASE AUTO_INCREMENT=1
                   """
                   cursor.execute(create_table_sql)
   
                   print("Table created successfully")
               except MySQLdb.Error as err:
                   print(err)
   

3. 定义插入数据的函数。

   定义函数 insert_record，该函数主要实现了向指定表中插入一条记录，记录包含 name 和 age 两个字段。使用 with 语句管理数据库连接和游标对象的生命周期，保证了数据库连接和游标对象的安全关闭，避免了内存泄漏等问题。定义 SQL 语句，执行插入操作，提交事务，打印输出执行结果或异常信息。

   代码如下：

   def insert_record(table_name, name, age):
       with MySQLdb.connect(**OCEANBASE_CONFIG) as conn:
           with conn.cursor() as cursor:
               try:
                   insert_sql = f"INSERT INTO {table_name} (name, age) VALUES (%s, %s)"
                   cursor.execute(insert_sql, (name, age))
                   conn.commit()
   
                   print("Record inserted successfully")
               except MySQLdb.Error as err:
                   print(err)
   

4. 定义查询表数据的函数。

   定义函数 select_all，该函数主要实现了查询指定表中的所有记录的功能。使用 with 语句管理数据库连接和游标对象的生命周期，保证了数据库连接和游标对象的安全关闭，避免了内存泄漏等问题。定义 SQL 语句，执行查询操作并遍历查询结果，打印输出所有记录。如果发生异常，则捕捉异常并打印输出异常信息。

   代码如下：

   def select_all(table_name):
       with MySQLdb.connect(**OCEANBASE_CONFIG) as conn:
           with conn.cursor() as cursor:
               try:
                   select_sql = f"SELECT * FROM {table_name}"
                   cursor.execute(select_sql)
                   result = cursor.fetchall()
                   for row in result:
                       print(row)
   
               except MySQLdb.Error as err:
                   print(err)
   

main.py 代码介绍

本文中 main.py 的主要作用是演示了如何使用 Python 和 MySQLdb 模块来操作数据库，并通过交互式命令行界面让您进行相应的操作。您可以通过该程序来创建表、插入记录和查询所有记录，从而实现了基本的数据库操作。

该文件中主要包括以下几个部分：

1. 导入 db.py 文件中定义的函数。

   从 db 模块中导入 create_table、insert_record 和 select_all 这三个函数。

   代码如下：

   from db import create_table, insert_record, select_all
   

2. 定义一个函数，用于操作数据库。

   定义函数 main，该函数实现了一个简单的命令行交互式程序，用于操作数据库。它首先调用 create_table 函数创建名为 test_tbl1 的表，然后进入一个 while 循环，等待用户输入命令。根据用户的选择，程序调用不同的函数进行插入或查询操作，直到用户输入 3 命令退出程序。如果用户输入的是无效命令，则程序会提示用户重新输入。

   根据输入的不同命令，程序执行不同的操作，包括插入数据（1）、查询数据（2）和退出程序（3）。

   代码如下：

   def main():
       create_table()
       while True:
           print("Instruction: 1.Insert Data; 2.Query Data; 3.Exit.")
   
           command = input("Enter the command [1/2/3]> ")
           if command == "1":
               name = input("Enter name：")
               age = input("Enter age：")
               insert_record("test_tbl1", name, age)
           elif command == "2":
               select_all("test_tbl1")
           elif command == "3":
               break
           else:
               print("Invalid command, please enter command again [1/2/3]")
   

3. 设置 main 函数的使用场景。

   设置只有当 main.py 被直接运行时，才会调用 main 函数执行程序的主要逻辑。而如果该程序被导入到其他模块中，则不会执行 main 函数。

   代码如下：

   if __name__ == "__main__":
       main()
   

   说明

   这种写法可以避免在导入该模块时自动执行 main 函数，从而保证程序的可重用性和可扩展性。

完整的代码展示

OCEANBASE_CONFIG = {
    'host': 'localhost',
    'port': 2881,  # 默认端口，可根据实际情况修改
    'user': 'user_name',
    'password': '',
    'database': 'db_name',
    'charset': 'utf8mb4'
}

import MySQLdb
from config import OCEANBASE_CONFIG


def create_table():
    with MySQLdb.connect(**OCEANBASE_CONFIG) as conn:
        with conn.cursor() as cursor:
            try:
                create_table_sql = """
                    CREATE TABLE test_tbl1 (
                        id INT UNSIGNED NOT NULL AUTO_INCREMENT,
                        name VARCHAR(50) NOT NULL,
                        age INT UNSIGNED NOT NULL,
                        PRIMARY KEY (id)
                    ) ENGINE=OCEANBASE AUTO_INCREMENT=1
                """
                cursor.execute(create_table_sql)

                print("Table created successfully")
            except MySQLdb.Error as err:
                print(err)


def insert_record(table_name, name, age):
    with MySQLdb.connect(**OCEANBASE_CONFIG) as conn:
        with conn.cursor() as cursor:
            try:
                insert_sql = f"INSERT INTO {table_name} (name, age) VALUES (%s, %s)"
                cursor.execute(insert_sql, (name, age))
                conn.commit()

                print("Record inserted successfully")
            except MySQLdb.Error as err:
                print(err)


def select_all(table_name):
    with MySQLdb.connect(**OCEANBASE_CONFIG) as conn:
        with conn.cursor() as cursor:
            try:
                select_sql = f"SELECT * FROM {table_name}"
                cursor.execute(select_sql)
                result = cursor.fetchall()
                for row in result:
                    print(row)

            except MySQLdb.Error as err:
                print(err)

from db import create_table, insert_record, select_all

def main():
    create_table()
    while True:
        print("Instruction: 1.Insert Data; 2.Query Data; 3.Exit.")

        command = input("Enter the command [1/2/3]> ")
        if command == "1":
            name = input("Enter name：")
            age = input("Enter age：")
            insert_record("test_tbl1", name, age)
        elif command == "2":
            select_all("test_tbl1")
        elif command == "3":
            break
        else:
            print("Invalid command, please enter command again [1/2/3]")

if __name__ == "__main__":
    main()

错误处理

在使用 mysqlclient 连接 OceanBase 数据库时，可能会遇到各种错误。以下是一些常见的错误及其处理方法：

1. 连接错误：如果无法连接到数据库，请检查连接参数是否正确，包括主机名、端口、用户名、密码和数据库名。

2. 权限错误：如果遇到权限相关的错误，请确保用户拥有足够的权限来执行所需的操作。

3. SQL 语法错误：如果 SQL 语句有语法错误，请检查 SQL 语句的语法是否正确。

4. 数据类型错误：如果插入的数据类型与表定义不匹配，请确保插入的数据类型正确。

在代码中，我们使用 try-except 语句来捕获和处理这些错误，确保程序在遇到错误时能够优雅地处理，而不是直接崩溃。

相关文档

• 更多连接 OceanBase 数据库的信息，请参见 连接方式概述。

• 更多创建数据库的信息，请参见 CREATE DATABASE。