---
title: "mysqlclient 连接 OceanBase 数据库示例程序 - OceanBase 数据库 V4.5.0 | OceanBase 文档中心"
description: mysqlclient 连接 OceanBase 数据库示例程序 本文将介绍如何使用 mysqlclient 和 OceanBase 数据库构建一个应用程序，实现创建表、插入数据和查询数据等基本操作。 点击下载 python-mysqlclient 示例工程 mysqlclient 连接 OceanBase 数据库示…
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.5.0

# mysqlclient 连接 OceanBase 数据库示例程序

更新时间：2026-03-17 20:57:43

[编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.5.0/zh-CN/300.develop/100.application-development-of-mysql-mode/200.sample-program-of-mysql-mode/200.python-of-mysql-mode/100.mysqlclient-connection-to-oceanbase-database-sample-program.md)  

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

 [![](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/download.png) 点击下载 python-mysqlclient 示例工程](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/observer-enterprise/V4.2.0/3.develop/demo/python/python-mysqlclient.zip) [![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*DFPmToHK6hgAAAAAAAAAAAAADiGDAQ/original) mysqlclient 连接 OceanBase 数据库示例程序（MySQL 模式）](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/video-center/video/video/02%20python-mysql%20client.mp4)  

## 前提条件

- 您已安装 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 正常安装。

**示例如下：**

```shell
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 数据库。

    Windows 环境   Linux 环境

**方法一：使用预编译的二进制文件安装（推荐）**

1. 从 [Download files](https://pypi.org/project/mysqlclient/#files) 下载与您的 Python 版本和操作系统平台兼容的 `whl` 文件。
 2. 打开命令提示符或 PowerShell 终端，进入到存放 `whl` 文件的目录，运行以下命令安装：

   ```shell
   pip install mysqlclient-2.2.0-cp311-cp311-win_amd64.whl

   ```

**方法二：直接安装**

1. 安装 MySQL 或 MySQL Connector/C，确保安装了开发组件。
 2. 安装 C 编译器（如 Visual Studio 或 MinGW）。
 3. 运行以下命令安装 mysqlclient 库：

   ```shell
   pip install mysqlclient

   ```

1. 安装 Python 开发包：

   ```shell
   sudo yum install python3-devel

   ```
 2. 安装 MySQL 开发库：

   ```shell
   sudo yum install mysql-devel

   ```
 3. 运行以下命令安装 mysqlclient 库：

   ```shell
   sudo pip install mysqlclient

   ```

#### 说明

mysqlclient 是一个高性能的 MySQL 客户端库，适合对性能要求较高的生产环境应用。

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

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

```shell
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 模式下的权限分类](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004479241)。
 - `$user_name`：提供租户的连接账户。ODP 连接的常用格式：`用户名@租户名#集群名` 或者 `集群名:租户名:用户名`；直连方式格式：`用户名@租户名`。
 - `$password`：提供账户密码。

更多连接串的信息，请参见 [通过 OBClient 连接 OceanBase 租户](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004476088)。

**示例如下：**

```shell
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` 文件中的数据库连接信息示例如下：**

   ```python
   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` 项目目录下。

   **示例如下：**

   ```shell
   cd /home/admin/python-mysqlclient

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

   ```shell
   python main.py

   ```

   返回结果如下：

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

   ```

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

- 插入数据成功示例。

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

       **示例如下：**

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

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

       **示例如下：**

       ```shell
       Enter name：A1

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

       **示例如下：**

       ```shell
       Enter age：18

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

       **示例如下：**

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

       ```
 - 插入数据失败示例。

       **示例如下：**

       **示例如下：**

       ```shell
       Enter name：A2

       #### 注意

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

       **示例如下：**

       ```shell
       Enter age：十八

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

       **示例如下：**

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

       ```
 - 查询数据示例。

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

       **示例如下：**

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

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

       **示例如下：**

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

       ```
 - 输入错误指令示例。

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

       **示例如下：**

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

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

       **示例如下：**

       ```shell
       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`，按回车键退出程序。

  **示例如下：**

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

  ```

## 项目代码介绍

点击 [python-mysqlclient](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/observer-enterprise/V4.2.0/3.develop/demo/python/python-mysqlclient.zip) 下载项目代码，是一个名称为 `python-mysqlclient.zip` 的压缩包。

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

```shell
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 数据库连接参数。

**代码如下：**

```python
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 数据库的信息，请参见 [连接方式概述](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004476086)。
 - `password`：连接数据库的密码。
 - `database`：要连接的数据库名。
 - `charset`：连接数据库时使用的字符集。

#### 注意

具体的属性（参数）配置取决于项目需求和数据库的特点，建议您根据实际情况进行调整和配置。

### db.py 代码介绍

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

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

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

   **代码如下：**

   ```python
   import MySQLdb
   from config import OCEANBASE_CONFIG

   ```
 2. 定义创建表的函数。

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

   **代码如下：**

   ```python
   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 语句，执行插入操作，提交事务，打印输出执行结果或异常信息。

   **代码如下：**

   ```python
   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 语句，执行查询操作并遍历查询结果，打印输出所有记录。如果发生异常，则捕捉异常并打印输出异常信息。

   **代码如下：**

   ```python
   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` 这三个函数。

   **代码如下：**

   ```python
   from db import create_table, insert_record, select_all

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

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

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

   **代码如下：**

   ```python
   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` 函数。

   **代码如下：**

   ```python
   if __name__ == "__main__":
       main()

   ```

   #### 说明

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

### 完整的代码展示

    config.py   db.py   main.py

```

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)

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()

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)

```

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

if __name__ == "__main__":
    main()

```

## 错误处理

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

1. **连接错误**：如果无法连接到数据库，请检查连接参数是否正确，包括主机名、端口、用户名、密码和数据库名。
 2. **权限错误**：如果遇到权限相关的错误，请确保用户拥有足够的权限来执行所需的操作。
 3. **SQL 语法错误**：如果 SQL 语句有语法错误，请检查 SQL 语句的语法是否正确。
 4. **数据类型错误**：如果插入的数据类型与表定义不匹配，请确保插入的数据类型正确。

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

## 相关文档

- 更多连接 OceanBase 数据库的信息，请参见 [连接方式概述](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004476086)。
 - 更多创建数据库的信息，请参见 [CREATE DATABASE](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004479570)。

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线