トラブルシューティング：データベース

一般的なデータベース接続とクエリの問題を修正。

接続拒否

エラー： ECONNREFUSED 127.0.0.1:5432 または connect ECONNREFUSED 127.0.0.1:27017

このエラーは、1DevToolが接続文字列のホストとポートに到達したが、そこでリッスンしているものがなかったことを意味します。データベースサーバーが実行されていないか、異なるポートでリッスンしています。

修正：

  • データベースが実行されているか確認。 PostgreSQLの場合：ターミナルでpg_ctl statusを実行。MySQLの場合：mysqladmin status。Redisの場合：redis-cli ping（PONGが返ってくるはず）。サービスが停止している場合は起動。
  • ポートを確認。 デフォルトポートは5432（PostgreSQL）、3306（MySQL/MariaDB）、27017（MongoDB）、6379（Redis）。DATABASE_URLのポートとデータベースが実際に使用しているポートを比較。
  • Dockerコンテナ。 データベースがDocker内で実行されている場合、docker psでコンテナが実行中か確認。リストにない場合、docker start <container-name>で起動。コンテナのポートがホストに公開されていることも確認（docker ps出力で0.0.0.0:5432->5432/tcpを探す）。

認証失敗

エラー： password authentication failed for user "postgres" または Access denied for user 'root'@'localhost'

接続文字列のユーザー名またはパスワードがデータベースサーバーの期待と一致しません。

修正：

  • DATABASE_URLまたは接続設定のユーザー名とパスワードを再確認。Supabaseアカウントパスワードとデータベースパスワードを混同しやすい — これらは異なります。Supabaseダッシュボードの設定 → データベースに表示されるパスワードを使用。
  • パスワード内の特殊文字。 パスワードに@、#、/、:が含まれている場合、これらの文字は接続文字列でURLエンコードする必要があります。例えば、@は%40、#は%23。p@ss#wordのようなパスワードはURLでp%40ss%23wordと記述。

SSL/TLSが必要

エラー： SSL connection has been closed unexpectedly または server requires SSL but client does not support it

多くのクラウドデータベースプロバイダー（Supabase、Neon、Railway、Render）は暗号化された接続を必要とします。

修正： PostgreSQL接続文字列の末尾に?sslmode=requireを追加：

postgresql://user:pass@host:5432/db?sslmode=require

MongoDB Atlasの場合、接続文字列でmongodb+srv://スキームを使用 — TLSが自動的に有効になり、追加のパラメータは不要。

クエリがタイムアウト

原因： クエリが膨大なデータをスキャンしているか、1DevToolとデータベース間のネットワーク接続がクエリ中に切断。

修正：

  • データを探索中はクエリにLIMIT句を追加。例：SELECT * FROM orders LIMIT 100。
  • 特定のクエリが常に遅い場合、WHERE句のカラムにインデックスがあるか確認。SQLエディタでEXPLAIN ANALYZE <クエリ>を実行するとクエリプランが表示。
  • タイムアウトが断続的に発生する場合、ネットワークを確認。VPN接続は特にデータベース接続を不安定にする可能性がある。

MongoDB：パスワード内の特殊文字

MongoDBパスワードに@、/、:、#が含まれている場合、接続文字列でこれらの文字をURLエンコードする必要があります。これらの文字はURLで特殊な意味を持ち、そのまま使用すると解析が壊れます。

一般的なエンコーディング：@ → %40、# → %23、/ → %2F、: → %3A。

例：my@secret#passというパスワードは接続文字列でmy%40secret%23passになる。

Dockerコンテナに接続できない

データベースがDockerコンテナ内で実行されており、1DevTool（ホストマシンで実行）から接続しようとしている場合、接続文字列でlocalhostを使用しないでください。ホストからlocalhostはコンテナではなくホストマシン自身を参照します。

代わりにhost.docker.internalを使用：

postgresql://user:[email protected]:5432/db

この特別なホスト名は、Docker内から常にホストマシンに解決し、ホスト側から正しいループバックインターフェースに解決します。