Skip to content

dev-guide-sample-application-python-sqlalchemy.md

Latest commit

 

History

History
339 lines (229 loc) · 17.5 KB

dev-guide-sample-application-python-sqlalchemy.md

File metadata and controls

339 lines (229 loc) · 17.5 KB
Raw
title Connect to TiDB with SQLAlchemy
summary SQLAlchemyを使用してTiDBに接続する方法を学びましょう。このチュートリアルでは、SQLAlchemyを使用してTiDBを操作するPythonのサンプルコードを紹介します。
aliases
/ja/tidb/dev/dev-guide-outdated-for-sqlalchemy
/ja/tidb/stable/dev-guide-sample-application-python-sqlalchemy/
/ja/tidb/dev/dev-guide-sample-application-python-sqlalchemy/
/ja/tidbcloud/dev-guide-sample-application-python-sqlalchemy/

SQLAlchemyを使用してTiDBに接続する {#connect-to-tidb-with-sqlalchemy}

TiDBはMySQL互換のデータベースであり、 SQLAlchemyは人気の高いPythonのSQLツールキットおよびオブジェクトリレーショナルマッパー（ORM）です。

このチュートリアルでは、TiDBとSQLAlchemyを使用して以下のタスクを実行する方法を学ぶことができます。

  • 環境をセットアップしてください。
  • SQLAlchemyを使用してTiDBに接続します。
  • アプリケーションをビルドして実行します。必要に応じて、基本的なCRUD操作のサンプルコードスニペットも利用できます。

Note:

このチュートリアルは、 TiDB Cloud Starter、 TiDB Cloud Essential、 TiDB Cloud Premium、 TiDB Cloud Dedicated、およびTiDB Self-Managedに対応しています。

前提条件 {#prerequisites}

このチュートリアルを完了するには、以下が必要です。

TiDBクラスタをお持ちでない場合は、以下の手順で作成できます。

TiDBに接続するには、サンプルアプリを実行してください。 {#run-the-sample-app-to-connect-to-tidb}

このセクションでは、サンプルアプリケーションコードを実行してTiDBに接続する方法を説明します。

ステップ1：サンプルアプリのリポジトリをクローンする {#step-1-clone-the-sample-app-repository}

サンプルコードリポジトリをクローンするには、ターミナルウィンドウで以下のコマンドを実行してください。

git clone https://github.com/tidb-samples/tidb-python-sqlalchemy-quickstart.git
cd tidb-python-sqlalchemy-quickstart

ステップ2：依存関係をインストールする {#step-2-install-dependencies}

サンプルアプリに必要なパッケージ（SQLAlchemyとPyMySQLを含む）をインストールするには、以下のコマンドを実行してください。

pip install -r requirements.txt

PyMySQLを使う理由とは？ {#why-use-pymysql}

SQLAlchemyは、複数のデータベースを扱うORMライブラリです。データベースの高レベルな抽象化を提供することで、開発者がよりオブジェクト指向的な方法でSQL文を記述できるように支援します。ただし、SQLAlchemyにはデータベースドライバは含まれていません。データベースに接続するには、データベースドライバをインストールする必要があります。このサンプルアプリケーションでは、データベースドライバとしてPyMySQLを使用しています。PyMySQLは、TiDBと互換性があり、すべてのプラットフォームにインストール可能な、純粋なPython製のMySQLクライアントライブラリです。

mysqlclientやmysql-connector-pythonなどの他のデータベース ドライバーを使用することもできます。ただし、これらは純粋な Python ライブラリではなく、コンパイルには対応する C/C++ コンパイラと MySQL クライアントが必要です。詳細については、 SQLAlchemyの公式ドキュメントを参照してください。

ステップ3：接続情報の設定 {#step-3-configure-connection-information}

選択したTiDBのデプロイオプションに応じて、TiDBに接続してください。

Note:

現在、 TiDB Cloud Starterインスタンスには制限があります。5分間アクティブな接続がない場合、インスタンスはシャットダウンし、すべての接続が閉じられます。そのため、 TiDB Cloud Starterインスタンスで SQLAlchemy を使用する場合、プールされた接続でOperationalErrorのようなLost connection to MySQL server during queryやMySQL Connection not availableが発生する可能性があります。このエラーを回避するには、 pool_recycleパラメータを300に設定してください。詳細については、SQLAlchemy ドキュメントの接続切れへの対処を参照してください。

  1. My TiDBページに移動し、対象のTiDB Cloud StarterまたはEssentialインスタンスの名前をクリックして、概要ページに移動します。

  2. 右上隅のConnectをクリックしてください。接続ダイアログが表示されます。

  3. 接続ダイアログの設定がご使用のオペレーティング環境と一致していることを確認してください。

    • Connection TypeはPublicに設定されています。

    • Branchはmainに設定されています。

    • Connect WithはGeneralに設定されています。

    • お使いの環境に合ったOperating Systemを選択してください。

    Tip:

    プログラムがWindows Subsystem for Linux（WSL）上で実行されている場合は、対応するLinuxディストリビューションに切り替えてください。

  4. Generate Passwordをクリックすると、ランダムなパスワードが生成されます。

    Tip:

    以前にパスワードを作成したことがある場合は、元のパスワードを使用するか、 Reset Passwordをクリックして新しいパスワードを生成できます。

  5. .env.exampleをコピーして.envに名前を変更するには、次のコマンドを実行します。

    cp .env.example .env

  6. 対応する接続​​文字列.envファイルにコピー＆ペーストしてください。例は以下のとおりです。

    TIDB_HOST='{host}'  # e.g. gateway01.ap-northeast-1.prod.aws.tidbcloud.com
TIDB_PORT='4000'
TIDB_USER='{user}'  # e.g. xxxxxx.root
TIDB_PASSWORD='{password}'
TIDB_DB_NAME='test'
CA_PATH='{ssl_ca}'  # e.g. /etc/ssl/certs/ca-certificates.crt (Debian / Ubuntu / Arch)

    必ずプレースホルダー{}を、接続ダイアログから取得した接続パラメータに置き換えてください。

  7. .envファイルを保存します。

  1. My TiDBページに移動し、対象のTiDB Cloud Premiumインスタンスの名前をクリックして概要ページに移動します。

  2. 左側のナビゲーションペインで、 Settings > Networkingをクリックします。

  3. Networkingページで、Public EndpointのEnableをクリックし、次にAdd IP Addressをクリックします。

    クライアントのIPアドレスがアクセスリストに追加されていることを確認してください。

  4. 左側のナビゲーションペインでOverviewをクリックすると、インスタンスの概要ページに戻ります。

  5. 右上隅のConnectをクリックしてください。接続ダイアログが表示されます。

  6. 接続ダイアログで、 Connection TypeドロップダウンリストからPublicを選択します。

    • 公開エンドポイントがまだ有効化中であることを示すメッセージが表示された場合は、処理が完了するまでお待ちください。
    • まだパスワードを設定していない場合は、ダイアログのSet Root Passwordをクリックしてください。
    • サーバー証明書を確認する必要がある場合、または接続に失敗して認証局（CA）証明書が必要な場合は、 CA certをクリックしてダウンロードしてください。
    • Public接続タイプに加えて、 TiDB Cloud Premium はPrivate Endpoint接続をサポートします。詳細については、 AWS PrivateLink経由でTiDB Cloud Premiumに接続しますを参照してください。

  7. .env.exampleをコピーして.envに名前を変更するには、次のコマンドを実行します。

    cp .env.example .env

  8. 対応する接続​​文字列.envファイルにコピー＆ペーストしてください。例は以下のとおりです。

    TIDB_HOST='{host}'  # e.g. tidb.xxxx.clusters.tidb-cloud.com
TIDB_PORT='4000'
TIDB_USER='{user}'  # e.g. root
TIDB_PASSWORD='{password}'
TIDB_DB_NAME='test'

    必ずプレースホルダー{}を、接続ダイアログから取得した接続パラメータに置き換えてください。

  9. .envファイルを保存します。

  1. My TiDBページに移動し、対象のTiDB Cloud Dedicatedクラスタの名前をクリックして概要ページに移動します。

  2. 右上隅のConnectをクリックしてください。接続ダイアログが表示されます。

  3. 接続ダイアログで、 Connection TypeドロップダウンリストからPublicを選択し、 CA certをクリックしてCA証明書をダウンロードします。

    IP アクセス リストを設定していない場合は、最初の接続の前に、 Configure IP Access Listをクリックするか、IP アクセス リストを設定するの手順に従って設定します。

    TiDB Cloud Dedicated は、Public接続タイプに加えて、Private EndpointおよびVPC Peering接続タイプもサポートしています。詳細については、 TiDB Cloud Dedicatedクラスタに接続しますを参照してください。

  4. .env.exampleをコピーして.envに名前を変更するには、次のコマンドを実行します。

    cp .env.example .env

  5. 対応する接続​​文字列.envファイルにコピー＆ペーストしてください。例は以下のとおりです。

    TIDB_HOST='{host}'  # e.g. tidb.xxxx.clusters.tidb-cloud.com
TIDB_PORT='4000'
TIDB_USER='{user}'  # e.g. root
TIDB_PASSWORD='{password}'
TIDB_DB_NAME='test'
CA_PATH='{your-downloaded-ca-path}'

    必ず、プレースホルダー{}を接続ダイアログから取得した接続パラメータに置き換え、 CA_PATH前の手順でダウンロードした証明書のパスに設定してください。

  6. .envファイルを保存します。

  1. .env.exampleをコピーして.envに名前を変更するには、次のコマンドを実行します。

    cp .env.example .env

  2. 対応する接続​​文字列.envファイルにコピー＆ペーストしてください。例は以下のとおりです。

    TIDB_HOST='{tidb_server_host}'
TIDB_PORT='4000'
TIDB_USER='root'
TIDB_PASSWORD='{password}'
TIDB_DB_NAME='test'

    プレースホルダー{}を接続パラメータに置き換え、 CA_PATHの行を削除してください。TiDB をローカルで実行している場合、デフォルトのホスト アドレスは127.0.0.1で、パスワードは空欄です。

  3. .envファイルを保存します。

ステップ4：コードを実行して結果を確認する {#step-4-run-the-code-and-check-the-result}

  1. サンプルコードを実行するには、以下のコマンドを実行してください。

    python sqlalchemy_example.py

  2. Expected-Output.txtをチェックして、出力が一致するかどうかを確認してください。

サンプルコードスニペット {#sample-code-snippets}

以下のサンプルコードスニペットを参考に、独自のアプリケーション開発を完成させてください。

完全なサンプルコードと実行方法については、 tidb-samples/tidb-python-sqlalchemy-quickstartリポジトリを参照してください。

TiDBに接続する {#connect-to-tidb}

from sqlalchemy import create_engine, URL
from sqlalchemy.orm import sessionmaker

def get_db_engine():
    connect_args = {}
    if ${ca_path}:
        connect_args = {
            "ssl_verify_cert": True,
            "ssl_verify_identity": True,
            "ssl_ca": ${ca_path},
        }
    return create_engine(
        URL.create(
            drivername="mysql+pymysql",
            username=${tidb_user},
            password=${tidb_password},
            host=${tidb_host},
            port=${tidb_port},
            database=${tidb_db_name},
        ),
        connect_args=connect_args,
    )

engine = get_db_engine()
Session = sessionmaker(bind=engine)

この機能を使用する場合は、 ${tidb_host} 、 ${tidb_port} 、 ${tidb_user} 、 ${tidb_password} 、 ${tidb_db_name} 、 ${ca_path} TiDB の実際の値に置き換える必要があります。

テーブルを定義する {#define-a-table}

from sqlalchemy import Column, Integer, String
from sqlalchemy.orm import declarative_base

Base = declarative_base()

class Player(Base):
    id = Column(Integer, primary_key=True)
    name = Column(String(32), unique=True)
    coins = Column(Integer)
    goods = Column(Integer)

    __tablename__ = "players"

詳細については、 SQLAlchemy ドキュメント: 宣言型によるクラスのマッピング検討を参照してください。

データを挿入する {#insert-data}

with Session() as session:
    player = Player(name="test", coins=100, goods=100)
    session.add(player)
    session.commit()

詳細については、データを挿入するを参照してください。

クエリデータ {#query-data}

with Session() as session:
    player = session.query(Player).filter_by(name == "test").one()
    print(player)

詳細については、 クエリデータを参照してください。

データの更新 {#update-data}

with Session() as session:
    player = session.query(Player).filter_by(name == "test").one()
    player.coins = 200
    session.commit()

詳細については、データの更新を参照してください。

データを削除する {#delete-data}

with Session() as session:
    player = session.query(Player).filter_by(name == "test").one()
    session.delete(player)
    session.commit()

詳細については、データを削除するを参照してください。

次のステップ {#next-steps}

お困りですか？ {#need-help}