Flask + MySQL ローカル開発環境構築ガイド：初心者が陥りやすいエラーと対処法

お知らせ

はじめに

本記事では、Flask（Pythonの軽量Webフレームワーク）とMySQL（リレーショナルデータベース）を使用したWebアプリケーションのローカル開発環境を構築する手順を解説します。実際の開発で遭遇したエラーとその対処法も含めることで、初学者がスムーズに環境構築を完了できることを目指します。

構築する環境

  • バックエンド: Flask 3.0.0 + Flask-Login（認証機能）
  • データベース: MySQL 8.0
  • 言語: Python 3.9以上
  • デプロイ想定: Google Cloud Run（本記事ではローカル環境のみ扱います）
目次
  1. はじめに
    1. 構築する環境
  2. 1. プロジェクト構成
  3. 2. 環境構築の流れ
    1. 2.1 仮想環境のセットアップ
    2. 2.2 MySQLのセットアップ
    3. 2.3 環境変数の設定
  4. 3. データベース設計
    1. usersテーブル（ユーザー情報）
    2. itemsテーブル（アイテム情報）
  5. 4. 認証機能の実装
  6. 5. 遭遇したエラーと対処法
    1. エラー1: 'cryptography' package is required
    2. エラー2: Table 'testdb.items' doesn't exist
    3. エラー3: Can't connect to local MySQL server through socket '/tmp/mysql.sock'
  7. 6. 動作確認とテスト
  8. 7. トラブルシューティングのベストプラクティス
  9. まとめ
    1. 重要なポイント
    2. 次のステップ
  10. 参考資料

1. プロジェクト構成

以下のような構造でプロジェクトを作成します：

cloudrun-db-test/
├── app.py              # メインアプリケーション
├── database.py         # データベース接続・操作
├── auth.py             # 認証ロジック
├── check_db.py         # データベース接続確認スクリプト
├── create_admin.py     # 管理者ユーザー作成スクリプト
├── requirements.txt    # 依存パッケージ
├── .env                # 環境変数（DB接続情報）
└── templates/          # HTMLテンプレート

2. 環境構築の流れ

2.1 仮想環境のセットアップ

Pythonの仮想環境を作成し、依存関係を分離します：

python3 -m venv venv
source venv/bin/activate  # macOS/Linux
pip install -r requirements.txt

重要な依存パッケージ:

  • Flask==3.0.0: Webフレームワーク
  • PyMySQL==1.1.0: MySQLドライバ
  • cryptography==41.0.7: MySQL認証に必要
  • Flask-Login==0.6.3: ユーザー認証管理
  • python-dotenv==1.0.0: 環境変数管理

2.2 MySQLのセットアップ

macOSの場合、Homebrewを使用してMySQLをインストールします：

brew install mysql
brew services start mysql
mysql_secure_installation  # rootパスワード設定

データベースとユーザーを作成：

CREATE DATABASE testdb;
CREATE USER 'appuser'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON testdb.* TO 'appuser'@'localhost';
FLUSH PRIVILEGES;

2.3 環境変数の設定

.envファイルを作成し、データベース接続情報を記載します：

DB_HOST=localhost
DB_PORT=3306
DB_USER=appuser
DB_PASSWORD=secure_password
DB_NAME=testdb
SECRET_KEY=your-secret-key-here

セキュリティ上の注意: .envファイルは.gitignoreに追加し、リポジトリにコミットしないこと。

3. データベース設計

本アプリケーションでは以下の2つのテーブルを使用します：

usersテーブル（ユーザー情報）

  • id: 主キー
  • username: ユーザー名（一意）
  • password_hash: ハッシュ化されたパスワード
  • role: ユーザーロール（admin/user）
  • created_at: 作成日時

itemsテーブル（アイテム情報）

  • id: 主キー
  • name: アイテム名
  • description: 説明
  • user_id: 作成ユーザーID（外部キー）
  • created_at: 作成日時

テーブル初期化はdatabase.pyのinit_db()関数で実行します。

4. 認証機能の実装

Flask-Loginを使用した基本的な認証フローを実装しました：

  1. パスワードハッシュ化: werkzeug.securityを使用
  2. セッション管理: Flask-Loginのセッション管理機能を活用
  3. ロールベース権限: admin/userの2段階権限設定
# パスワードハッシュ化の例
from werkzeug.security import generate_password_hash, check_password_hash

password_hash = generate_password_hash('user_password')
is_valid = check_password_hash(password_hash, 'user_password')

5. 遭遇したエラーと対処法

開発中に遭遇した代表的なエラーとその解決策を紹介します。

エラー1: 'cryptography' package is required

原因: PyMySQLがMySQL 8.0の認証方式（caching_sha2_password）を使用する際にcryptographyパッケージが必要だが、システムのPythonが参照されている。

対処法:

# 仮想環境のPythonを明示的に使用
./venv/bin/python check_db.py

# または、仮想環境がアクティブな場合はpythonコマンドを使用
python check_db.py  # python3 ではなく python

学び: 仮想環境を使用する場合、python3コマンドはシステムのPythonを参照する可能性があります。仮想環境のパッケージを確実に使用するには、./venv/bin/pythonで直接指定するか、pythonコマンドを使用してください。

エラー2: Table 'testdb.items' doesn't exist

原因: データベースは作成されているが、テーブルが初期化されていない。

対処法:

# テーブル初期化を実行
./venv/bin/python -c "from database import init_db; init_db()"

# または check_db.py を実行（自動的にテーブルを作成）
./venv/bin/python check_db.py

学び: データベース作成とテーブル作成は別工程です。CREATE DATABASEだけでは不十分で、スキーマ定義（CREATE TABLE）が必要です。

エラー3: Can't connect to local MySQL server through socket '/tmp/mysql.sock'

原因: MySQLサーバーが起動していない、または異なるソケットファイルを使用している。

対処法:

# MySQLサービスを再起動
brew services restart mysql

# ステータス確認
brew services list

# 起動確認
ps aux | grep mysql | grep -v grep

学び: macOSでは、MySQLのソケットファイルの場所が環境によって異なる場合があります（/tmp/mysql.sock vs /var/run/mysqld/mysqld.sock）。接続エラーが発生した場合は、まずMySQLサービスの起動状態を確認してください。

6. 動作確認とテスト

環境構築が完了したら、以下の手順で動作確認を行います：

# 1. データベース接続確認
./venv/bin/python check_db.py

# 2. 管理者ユーザー作成
./venv/bin/python create_admin.py

# 3. アプリケーション起動
./venv/bin/python app.py

ブラウザでhttp://localhost:8080にアクセスし、ログイン画面が表示されれば成功です。

7. トラブルシューティングのベストプラクティス

開発中にエラーが発生した際の対処フローを確立しておくことが重要です：

  1. エラーメッセージを正確に読む: スタックトレースから原因を特定
  2. 環境を確認: 仮想環境がアクティブか、正しいPythonを使用しているか
  3. 接続情報を検証: .envファイルの内容が正しいか
  4. サービス状態を確認: MySQLが起動しているか
  5. ドキュメントを活用: プロジェクト内のTROUBLESHOOTING.mdを参照

本プロジェクトでは、TROUBLESHOOTING.mdに詳細なエラー対処法をまとめています。

まとめ

本記事では、Flask + MySQLのローカル開発環境構築手順と、実際に遭遇したエラーの対処法を解説しました。

重要なポイント

  1. 仮想環境の正しい使用: システムのPythonと仮想環境のPythonを区別する
  2. 環境変数管理: .envファイルでDB接続情報を管理し、セキュリティを確保
  3. 段階的な確認: データベース接続 → テーブル作成 → アプリ起動の順で確認
  4. エラーログの活用: MySQLのエラーログやPythonのスタックトレースを読む習慣

次のステップ

  • 本番環境へのデプロイ: Google Cloud Runへのデプロイ設定
  • CI/CDパイプライン: GitHub Actionsを使用した自動デプロイ
  • テストコードの追加: pytestを使用した単体テスト・統合テスト
  • ロギング改善: 本番環境でのエラー追跡機能

参考資料

プロジェクト内のドキュメント:

  • QUICKSTART.md: クイックスタートガイド
  • TROUBLESHOOTING.md: 詳細なトラブルシューティング
  • MYSQL_SETUP.md: MySQL環境構築詳細
  • AUTH_GUIDE.md: 認証機能実装ガイド

公式ドキュメント:

執筆者より: 本記事は実際の開発経験に基づいています。環境構築で困った経験が、同じ課題に直面している方の助けになれば幸いです。