🐘

ローカルにReact + FastAPI + PostgreSQLの環境構築をする

に公開

はじめに

業務で、Docker を使わずにローカル環境へ React + FastAPI + PostgreSQL を構築する機会がありました。ここでは、その検証を自分の M1 MacBook Air で行った際の手順を備忘録としてまとめています。

本記事では次の内容に触れます。

  • PostgreSQL(データベース)の構築
  • SQLALchemyを使用した、モデル定義やORM操作
  • venvを用いた仮想環境の構築
  • FastAPI / React の最小構成の実装

それでは早速始めていきましょう!
その前にこの記事を読む前に次の「注意事項」をお読みください!

1. ローカル環境の汚染

この手順では Python、Node.js、PostgreSQL をローカル環境に直接インストールします。Python の仮想環境はパッケージのみを隔離し、ランタイム本体はシステムに残ります。環境を汚染したくない場合は Docker の使用を検討してください。
https://zenn.dev/agdm/articles/0f82ea448e38b8

2. テーブルの自動生成について

今回は、簡単のために、FastAPIアプリが起動すると、main.pyが読み込まれます。その際Base.metadata.create_all(bind=engine)が実行され、テーブルが自動生成されます。
しかし、テーブル更新が入っても自動反映されないため、現場単位では、Alembicなどのマイグレーションツールを使うことを推奨します。
https://alembic.sqlalchemy.org/en/latest/
https://zenn.dev/usagi1975/articles/2024-08-11_sqlalchemy_alembic

3. Create React Appの非推奨化について

2025年2月14日に公式からCreate React Appの本番環境での非推奨が発表されています。今回のような検証構成では問題ないと思いますが、公式ページより参照ください。
https://ja.react.dev/blog/2025/02/14/sunsetting-create-react-app

代替手段

Vite
https://ja.vite.dev
NextJS
https://nextjs.org

バージョン情報

下記のバージョンでの構成になります。

ツール バージョン
Python v3.12.x
Node.js v20.18.3
React v18.x

1. ディレクトリ構成

まずは、ディレクトリ構成から確認しましょう。

project-root/
├── backend/      # Python / FastAPI + SQLAlchemy
│   ├── venv/     # 仮想環境
│   ├── main.py
│   ├── db.py
│   └── models.py
└── frontend/     # React アプリ
  • frontend/ にはReactアプリを作成します。

2. PostgreSQL の準備

次にPostgreSQLをローカルにインストールします。ターミナルを使用して操作していきます。
https://www.postgresql.org/

PostgreSQLのインストール

まずはローカルにPostgreSQLをインストールします。

brew install postgresql
brew services start postgresql

データベース作成

次に、データベースの作成をします。PostgreSQLに接続していきます。下記コマンドで
ターミナル上で次のように入力します。

psql -U postgres

すると、以下のようにパスワード入力が求められます。

ユーザー postgres のパスワード: 

パスワードを入力すると接続成功し、次のようなプロンプトになります

postgres=#

これで PostgreSQL にログインした状態 です。
下記コマンドを実行してDBを作成します。今回は「testdb」という名前にします。

CREATE DATABASE testdb;

次に、下記コマンドを実行して、DBが作成できているか確認します。

\l

👇こんな感じのデータが見えれば大丈夫です!

   名前    |  所有者  | エンコーディング | ロケールプロバイダー | 照合順序 | Ctype(変換演算子) | ロケール | ICUルール: |     アクセス権限      
-----------+----------+------------------+----------------------+----------+-------------------+----------+------------+-----------------------
 postgres  | postgres | UTF8             | libc                 | C        | C                 |          |            | 
 template0 | postgres | UTF8             | libc                 | C        | C                 |          |            | =c/postgres          +
           |          |                  |                      |          |                   |          |            | postgres=CTc/postgres
 template1 | postgres | UTF8             | libc                 | C        | C                 |          |            | =c/postgres          +
           |          |                  |                      |          |                   |          |            | postgres=CTc/postgres
 testdb    | postgres | UTF8             | libc                 | C        | C                 |          |            | 
(4 行)

対話型シェルを抜ける方法

作業が終わったら以下で終了します

\q

3. Python 環境構築(FastAPI + SQLAlchemy)

次にバックエンドフォルダを作成していきます。その前にそもそもディレクトリがないので作成しましょう。自分が作成したい場所に作ります。私はDocumentsに作ることが多いので、Documentsディレクトリに移動して作成していきます。

https://fastapi.tiangolo.com/ja/

https://www.sqlalchemy.org/

mkdir project-root

作成したディレクトリに移動します。

cd project-root

ここで、backendを作成します。

mkdir backend

作成したbackendディレクトリに移動します。

cd backend

仮想環境作成

パッケージを管理するための仮想環境を作成し有効化しましょう!今回venvは仮想環境を構築しています。パッケージの管理のみ仮想環境にインストールされ、ローカルを汚染しないようにしています。

https://zenn.dev/mabo23/articles/108540be08aff4

下記のコマンドを実行してください。

python3 -m venv venv          # 仮想環境作成
source venv/bin/activate      # macOS / Linux
# Windows: venv\Scripts\activate

必要なパッケージのインストール

今作った仮想環境に今回使うパッケージをインストールします。

pip install fastapi uvicorn sqlalchemy psycopg2-binary

👇各パッケージの簡単な説明を載せときます

パッケージ名 役割 主な用途
fastapi Web フレームワーク Python で高速な API サーバを構築するためのフレームワーク。リクエスト処理、ルーティング、バリデーション、レスポンス生成を担当。
uvicorn ASGI サーバ FastAPI アプリを動作させる実行サーバ。Node.js でいう npm start のような位置づけ。uvicorn main:app --reload で起動。
sqlalchemy ORM(Object Relational Mapper) Python オブジェクトを使ってデータベースを操作するためのライブラリ。SQL を直接書かずにテーブル作成やCRUDが可能。
psycopg2-binary PostgreSQL ドライバ Python から PostgreSQL に接続するためのドライバ。SQLAlchemy がこれを通じて実際のDB通信を行う。

4. SQLAlchemy の設定

データベース接続とセッション管理を行うファイルです。

db.py

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

# 実際の開発現場で使用する場合は.envなどの環境変数に定義すること
DATABASE_URL = "postgresql://postgres:<password>@localhost:5432/testdb"

engine = create_engine(DATABASE_URL, echo=True)
SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)
Base = declarative_base()

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

5. モデル定義

データベースのテーブル構造を Python クラスで定義します。

models.py

from sqlalchemy import Column, Integer, String
from db import Base

class Message(Base):
    __tablename__ = "messages"
    id = Column(Integer, primary_key=True, index=True)
    text = Column(String, nullable=False)

6. FastAPI 本体

API エンドポイントを定義します。テーブル作成と CORS 設定も含まれています。

main.py

from fastapi import FastAPI, Depends
from fastapi.middleware.cors import CORSMiddleware
from sqlalchemy.orm import Session
from db import Base, engine, get_db
from models import Message

# テーブル作成
# 検証用のため、本番ではAlembicなどのマイグレーションツールを使用してください
Base.metadata.create_all(bind=engine)

app = FastAPI()

# React (localhost:3000) からのアクセスを許可
# 本番環境では具体的なドメインを指定するか、より厳格なCORSポリシーを設定する必要があります。
# 将来的に Bearer Token などの認証ヘッダを使う可能性を考慮し、Authorization を許可しています。
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["GET", "POST"],
    allow_headers=["Content-Type", "Authorization"],
)

@app.get("/api/message")
def get_message(db: Session = Depends(get_db)):
    msg = db.query(Message).first()
    if msg:
        return {"message": msg.text}
    else:
        new_msg = Message(text="Hello from PostgreSQL + SQLAlchemy!")
        db.add(new_msg)
        db.commit()
        db.refresh(new_msg)
        return {"message": new_msg.text}

7. FastAPI サーバ起動

ディレクトリ

cd backend

サーバ起動コマンド

uvicorn main:app --reload --port 8000

ブラウザで http://localhost:8000/api/message にアクセスすると確認できます。

8. React フロントエンド

React アプリの作成

プロジェクトルートへ戻り React アプリを作成します

npx create-react-app frontend

src/App.js の実装例

import { useEffect, useState } from "react";

function App() {
  const [msg, setMsg] = useState("");

  useEffect(() => {
    fetch("http://localhost:8000/api/message")
      .then((res) => res.json())
      .then((data) => setMsg(data.message))
      .catch(() => setMsg("API error"));
  }, []);

  return <h1>{msg}</h1>;
}

export default App;

サーバーの起動を行います。

cd frontend
npm start

ブラウザで http://localhost:3000 を開くと、FastAPI から取得したメッセージが表示されます。

9. 開発環境のポイント

  • 仮想環境により依存パッケージが分離される
  • SQLAlchemy により ORM 操作が容易に
  • React → FastAPI → PostgreSQL の流れが確認できる最小構成
  • DB の中身は CLI / GUI ツールで確認可能

まとめ

はい!ということで、React・FastAPI・PostgreSQL を組み合わせ、Dockerを使わずにローカルで動作する最小構成の開発環境を構築できました。

実務で活用するには、少し工夫する箇所もありますが、学習用には最適な構成になっていると思います。ぜひ活用してみて下さい!!

Discussion