Flask アプリを Render にデプロイし、PostgreSQL と接続するだけのはずが、
実際には Python バージョンの不一致、psycopg2 の非対応、SQLAlchemy の仕様変更、アプリ構造の問題など、複数の技術的課題が重なった。

この記事では、実際に遭遇したエラーと、それぞれの技術的な原因・解決策をまとめる。

## 1. Render が Python 3.13 を強制してくる問題

runtime.txt に python-3.12.10 を書いても Render が無視し、
ビルドログに以下のように出る：

Using Python version 3.13.x

psycopg2 が Python 3.13 に非対応のため、ImportError が発生。

ImportError: undefined symbol: _PyInterpreterState_Get

Render の Python 自動判定が壊れており、runtime.txt が反映されない。

psycopg2 を捨てて psycopg3（psycopg[binary]）に移行する。

requirements.txt：

psycopg[binary]

psycopg3 は Python 3.13 に対応しているため、
Render のバージョン問題を完全に回避できる。

## 2. SQLAlchemy が psycopg2 を探し続ける問題

psycopg3 を入れても、SQLAlchemy が内部で psycopg2 を探して落ちる。

ModuleNotFoundError: No module named 'psycopg2'

DATABASE_URL が psycopg2 用の形式になっている。

接続 URL を psycopg3 用に変更する。

postgresql://user:pass@host:5432/dbname

postgresql+psycopg://user:pass@host:5432/dbname

SQLAlchemy のドライバ選択は URL で決まるため、
+psycopg を付けることで psycopg3 が使われる。

RuntimeError: The current Flask app is not registered with this 'SQLAlchemy' instance.

app.py と models.py の両方で SQLAlchemy() を生成していた。

# app.py
db = SQLAlchemy(app)

# models.py
db = SQLAlchemy()  # ← これが別インスタンス

db は app.py で1つだけ作り、models.py ではそれを import する。

db = SQLAlchemy(app)
from models import Todo

from app import db

class Todo(db.Model):
    ...

これで Flask アプリとモデルが同じ db インスタンスを共有できる。

Textual SQL expression 'SELECT 1' should be explicitly declared as text('SELECT 1')

SQLAlchemy 2.0 以降、
生 SQL を実行する場合は text() で包む必要がある。

from sqlalchemy import text
db.session.execute(text('SELECT 1'))

すべての修正後 /dbtest を叩いた結果：

PostgreSQL OK

これで Flask アプリが Render 上で PostgreSQL と正常に通信できることが確認できた。