ローカルにReact + FastAPI + PostgreSQLの環境構築をする
はじめに
業務で、Docker を使わずにローカル環境へ React + FastAPI + PostgreSQL を構築する機会がありました。ここでは、その検証を自分の M1 MacBook Air で行った際の手順を備忘録としてまとめています。
本記事では次の内容に触れます。
- PostgreSQL(データベース)の構築
- SQLALchemyを使用した、モデル定義やORM操作
- venvを用いた仮想環境の構築
- FastAPI / React の最小構成の実装
それでは早速始めていきましょう!
その前にこの記事を読む前に次の「注意事項」をお読みください!
1. ローカル環境の汚染
この手順では Python、Node.js、PostgreSQL をローカル環境に直接インストールします。Python の仮想環境はパッケージのみを隔離し、ランタイム本体はシステムに残ります。環境を汚染したくない場合は Docker の使用を検討してください。
2. テーブルの自動生成について
今回は、簡単のために、FastAPIアプリが起動すると、main.pyが読み込まれます。その際Base.metadata.create_all(bind=engine)が実行され、テーブルが自動生成されます。
しかし、テーブル更新が入っても自動反映されないため、現場単位では、Alembicなどのマイグレーションツールを使うことを推奨します。
3. Create React Appの非推奨化について
2025年2月14日に公式からCreate React Appの本番環境での非推奨が発表されています。今回のような検証構成では問題ないと思いますが、公式ページより参照ください。
代替手段
Vite NextJS
バージョン情報
下記のバージョンでの構成になります。
| ツール | バージョン |
|---|---|
| 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をローカルにインストールします。ターミナルを使用して操作していきます。
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ディレクトリに移動して作成していきます。
mkdir project-root
作成したディレクトリに移動します。
cd project-root
ここで、backendを作成します。
mkdir backend
作成したbackendディレクトリに移動します。
cd backend
仮想環境作成
パッケージを管理するための仮想環境を作成し有効化しましょう!今回venvは仮想環境を構築しています。パッケージの管理のみ仮想環境にインストールされ、ローカルを汚染しないようにしています。

下記のコマンドを実行してください。
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