Tortoise ORM による OceanBase データベース接続サンプルプログラム|OceanBaseデータベース|ドキュメント|OceanBaseマニュアル

機能の適用範囲

Tortoise ORM は OceanBase データベースの MySQL モードで動作します。

Tortoise ORM は、asyncio をベースとした非同期オブジェクト関係マッピング（ORM）ライブラリであり、現代の Python アプリケーション向けに設計されています。その非同期特性により、特に以下のシナリオに適しています：

大量の同時データベース接続を処理する場合
高パフォーマンスな Web サーバーを構築する場合
複数のネットワークリクエストを同時に処理するアプリケーションの場合

Tortoise ORM では、非同期通信によりデータベース操作がアプリケーション全体をブロックせず、他のタスクを並行して処理できるため、アプリケーション全体のパフォーマンスと応答速度を大幅に向上させることができます。

本記事では、Tortoise ORM を使用して OceanBase データベースに接続し、テーブルの作成、データの挿入、更新、クエリなどの基本的なデータベース操作を実装する方法について説明します。

前提条件

Python 3.7以降のバージョンとpipがインストール済みであること。
OceanBaseデータベースをインストール済みで、MySQLモードのテナントが作成されていること。

手順

OceanBaseデータベースの接続文字列を取得します。
Tortoise ORMとMySQLクライアントライブラリをインストールします。
test_tortoise.py ファイルを作成し、データベース接続情報を入力します。
test_tortoise.py ファイルを実行します。

ステップ１：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、UPDATE、および SELECT 権限が付与されていなければなりません。その他のユーザー権限の詳細については、MySQLモードの権限分類を参照してください。
$user_name：テナントの接続アカウント。ODP接続の一般的な形式：ユーザー名@テナント名#クラスタ名 または クラスタ名:テナント名:ユーザー名。直接接続方式の形式：ユーザー名@テナント名。
$password：アカウントのパスワード。

その他の接続文字列の詳細については、OBClientを使用してOceanBaseテナントに接続するを参照してください。

例：

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

ステップ2：Tortoise ORMとMySQLクライアントライブラリをインストールする

Tortoise ORMは、asyncio専用に設計された非同期Python ORMライブラリで、MySQL、PostgreSQL、SQLiteなどのデータベースをサポートしています。

コマンドプロンプトまたはPowerShellターミナルを開き、以下のコマンドを実行してTortoise ORMとMySQLクライアントライブラリをインストールします。

pip install tortoise-orm aiomysql

インストール完了後、以下のコマンドでインストールが成功したか確認できます：

pip list | grep tortoise

説明

Tortoise ORMは非同期のORMライブラリであり、シンプルで強力なAPIを提供し、データベース操作を簡素化できます。Tortoise ORMは、MySQL、PostgreSQL、SQLiteなど、さまざまなデータベースバックエンドをサポートしています。

ステップ3：test_tortoise.pyファイルを作成し、データベース接続情報を入力する

ステップ1：OceanBaseデータベースの接続文字列を取得する の情報に基づいて、test_tortoise.py ファイルを作成し、データベース接続情報を入力します。

test_tortoise.py という名前のファイルを作成します。

test_tortoise.py ファイルに以下の内容を入力し、実際の状況に応じてデータベース接続情報を修正します。

test_tortoise.py ファイルの内容例は以下のとおりです：

from tortoise import Tortoise, run_async
from tortoise.models import Model
from tortoise import fields
import asyncio

# モデルの定義
from datetime import datetime

class User(Model):
    id = fields.IntField(pk=True)
    username = fields.CharField(max_length=50, null=False)
    email = fields.CharField(max_length=100, unique=True, null=False)
    password_hash = fields.CharField(max_length=255, null=False)
    created_at = fields.DatetimeField(auto_now_add=True, null=False)
    updated_at = fields.DatetimeField(auto_now=True, null=True)

    def __str__(self):
        return f"{self.username} ({self.email})"

    class Meta:
        table = "users"

# データベース設定
DB_CONFIG = {
    'connections': {
        'oceanbase': {
            'engine': 'tortoise.backends.mysql',
            'credentials': {
                'host': 'xxx.xxx.xxx.xxx',
                'port': 2881,
                'user': 'test_user001@mysql001',
                'password': '******',
                'database': 'test',
            }
        },
    },
    'apps': {
        'models': {
            'models': ['__main__'],  # 現在のファイルに含まれるモデル
            'default_connection': 'oceanbase',
        }
    },
    'use_tz': False,
    'timezone': 'Asia/Shanghai',
}

async def init_db():
    # データベース接続の初期化
    await Tortoise.init(config=DB_CONFIG)
    # テーブルの作成
    await Tortoise.generate_schemas()

async def main():
    # データベースの初期化
    await init_db()

    # データの挿入
    from datetime import datetime

    await User.create(
        username='john_doe',
        email='john@example.com',
        password_hash='hashed_password_123',
        created_at=datetime.now(),
        updated_at=datetime.now()
    )

    # データの更新
    user = await User.filter(email='john@example.com').first()
    if user:
        user.username = 'john_updated'
        user.updated_at = datetime.now()
        await user.save()

    # データのクエリ
    users = await User.all()
    for user in users:
        print(user)

    # データベース接続を閉じる
    await Tortoise.close_connections()

if __name__ == '__main__':
    run_async(main())

ステップ4：test_tortoise.pyファイルを実行する

コマンドプロンプトまたはPowerShellターミナルを開き、test_tortoise.py ファイルを実行してデータを照会し、結果を出力します。

test_tortoise.py ファイルがあるディレクトリに移動します。

例：
```
cd ~/orm-demo
```
test_tortoise.py ファイルを実行します。

例：
```
python test_tortoise.py
```
結果は次のとおりです：
```
john_updated (john@example.com)
```