---
title: "mysqlclient 连接 OceanBase 数据库示例程序 - OceanBase 数据库 V4.3.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.3.0

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

更新时间：2026-04-10 11:58:35

[编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.3.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://file.oceanbase.com/doc/img/lQLPJyFovGIOcJQWFrAqhLlgRRsPvwU-H7hJ_i0A_22_22.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://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/ocp/422/Play%2002.png) 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 库时，需要编译和链接 MySQL C API 来连接 OceanBase 数据库。因此，需要安装 MySQL Connector C 或者 MySQL C API 的开发文件，以便在编译过程中使用。

    Windows 环境   Linux 环境

**方法一：使用预编译的二进制文件来安装 mysqlclient 库**

在 Windows 上，您可以使用预编译的二进制文件来安装 mysqlclient 库。从 [Download files](https://pypi.org/project/mysqlclient/#files) 下载与您的 Python 版本和操作系统平台兼容的 `whl` 文件，并使用 `pip install` 命令来安装。

示例如下：

打开命令提示符或 PowerShell 终端，运行以下命令，安装必要的 Python 库。

1. 进入到存放 `whl` 文件的目录。

   ```sehll
   cd D:\download

   ```
 2. 运行以下命令，安装 mysqlclient 库。

   ```shell
   PS D:\download> pip install mysqlclient-2.2.0-cp311-cp311-win_amd64.whl
   Processing d:\download\mysqlclient-2.2.0-cp311-cp311-win_amd64.whl
   Installing collected packages: mysqlclient
   Successfully installed mysqlclient-2.2.0

   ```

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

1. 安装 MySQL。

   在使用 mysqlclient 之前，你需要先安装 MySQL 数据库服务器。mysqlclient 库会依赖于 MySQL 的客户端程序和库文件，以便与 MySQL 进行通信。您可以从 [MySQL 官方网站](https://dev.mysql.com/downloads/windows/installer/) 下载安装程序，并按照指示进行安装。
 2. 安装 C 编译器。

   在 Windows 上安装 C 编译器，可以选择安装 Visual Studio 或者 MinGW。
 3. 安装开发工具。

   在 Windows上，你可以使用 MySQL Connector/C 来获取 MySQL 的开发库。您可以按照以下步骤来进行安装 MySQL Connector/C：

      1. 打开 [MySQL 官网下载](https://dev.mysql.com/downloads/connector/c/) 页面。
      2. 在下载页面中，选择适合你的操作系统类型和版本，下载对应的安装包。
      3. 运行下载的安装包，按照安装向导的提示进行安装。
      4. 在安装过程中，选择 **Custom** 安装类型，确保安装了 **Development Components**。
      5. 安装完成后，重新启动计算机。
 4. 安装 mysqlclient 库。

      1. 运行以下命令，进入到代码的 `python-mysqlclient` 目录。

        ```shell
        cd python-mysqlclient

        ```shell
        pip install -r requirements.txt

        ```  

   #### 说明

   您也可以直接运行 `pip install mysqlclient` 命令安装 mysqlclient 库。

在 Linux 环境下，Python 的 C 扩展需要依赖 Python.h 头文件，而这个头文件通常包含在 python3-devel 包中。如果没有安装 python3-devel 包，则编译 MySQL C API 时会出现找不到 Python.h 的错误。

1. 检查是否安装 `python3-devel`。

   运行以下命令来检查是否已安装 `python3-devel` 包：

   ```shell
   rpm -q python3-devel

   ```

      - 如果已安装，则会输出类似于以下内容的信息：

       ```shell
       python3-devel-3.x.x-x.el7.x86_64

       ```

       其中，3.x.x 表示 Python3 的版本号，x86_64 表示系统的 CPU 架构。
      - 如果未安装，则会输出类似于以下内容的信息：

       ```shell
       package python3-devel is not installed

       ```

       此时可以通过以下命令来安装 `python3-devel` 包：

       ```shell
       sudo yum install python3-devel

       ```

       安装完成后，再次运行 `rpm -q python3-devel` 命令来确认安装是否成功。
 2. 安装 mysqlclient 库。

        ```
      2. 运行以下命令，安装项目所需的 Python 库。

        ```shell
        sudo pip install -r requirements.txt

        ```  

   #### 说明

   您也可以直接运行 `sudo pip install mysqlclient` 命令安装 mysqlclient 库。

### 步骤三：获取 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-1000000000642580)。
 - `$user_name`：提供租户的连接账户。ODP 连接的常用格式：`用户名@租户名#集群名` 或者 `集群名:租户名:用户名`；直连方式格式：`用户名@租户名`。
 - `$password`：提供账户密码。

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

**示例如下：**

```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': port,
    '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-1000000000640069)。
 - `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()

```

## 相关文档

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

 上一篇 下一篇 ![有帮助](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) 咨询热线