HarborDB トラブルシューティングガイドへようこそ。この包括的なリソースは、HarborDB と PostgreSQL を扱う際に遭遇する最も一般的な問題を迅速に特定し解決するのに役立ちます。接続の問題、パフォーマンスの低下、インターフェイスの問題など、段階的な解決策がここにあります。

このガイドの使い方

以下のカテゴリから問題を特定する
トラブルシューティングの手順を順番に実行する
問題が解決するまで解決策を試す
まだ解決しない場合、「サポートへのお問い合わせ」セクションを利用する

クイックリファレンス：よくある問題

| 問題 | 考えられる原因 | 簡単な解決策 | | --------------------------- | ------------------------------------- | ----------------------------------------- | | PostgreSQL に接続できない | サーバーが起動していない、ファイアウォールによるブロック | PostgreSQL を起動、ファイアウォール設定を確認 | | クエリのパフォーマンスが遅い | インデックス不足、大規模なデータセット | インデックスを追加、LIMIT を使用、クエリを最適化 | | メモリ使用量が高い | 開きすぎたタブ、大規模な結果セット | 未使用のタブを閉じる、ストリーミングモードを有効化 | | エクスポートが失敗する | 権限の問題、ディスク容量不足 | ファイル権限を確認、ディスク容量を空ける | | UI が遅い | システムリソースの制約 | 他のアプリを閉じる、HarborDB を再起動 |

接続の問題

"PostgreSQL サーバーに接続できない"

症状:

接続タイムアウトエラー
"Connection refused" メッセージ
接続テスト時に無限に読み込みが続く

ステップバイステップのトラブルシューティング:

PostgreSQL サーバーの状態を確認:
```
# ターミナルで PostgreSQL が起動しているか確認
pg_isready -h localhost -p 5432
```
- 起動していない場合: brew services start postgresql (Homebrew) またはシステム環境設定から起動
接続詳細を確認:
- ホスト名: ローカルは localhost、リモートは正しい IP/ホスト名
- ポート: デフォルトは 5432、PostgreSQL のポートを確認
- データベース名: 接続前に存在している必要がある
- ユーザー名/パスワード: 大文字小文字を区別、認証情報を確認
ファイアウォール設定を確認:
- システム環境設定 → セキュリティとプライバシー → ファイアウォール
- PostgreSQL ポート (5432) が許可されていることを確認
- テストのために一時的にファイアウォールを無効化してみる

ネットワーク接続をテスト:

# リモートサーバーの場合
ping your-server-address
telnet your-server-address 5432

一般的な解決策:

✅ PostgreSQL サービスを起動
✅ 正しいホスト名/IP アドレスを使用
✅ ファイアウォールポート 5432 を開放
✅ 正しい認証情報を使用

"パスワード認証に失敗しました"

原因:

誤ったユーザー名またはパスワード
PostgreSQL 認証方式の不一致
ユーザーにデータベース権限がない

解決策:

PostgreSQL パスワードをリセット:

-- スーパーユーザーとして接続 (コマンドライン経由)
ALTER USER username WITH PASSWORD 'new_password';

認証方式を確認:
- pg_hba.conf ファイルを確認
- 一般的な方式: md5, scram-sha-256, trust
- 必要に応じて方式を更新し、PostgreSQL を再起動

ユーザー権限を確認:

-- ユーザーと権限を一覧表示
\du

-- データベースとアクセス権を一覧表示
\l

SSL/TLS 接続エラー

リモートサーバーに接続する場合:

SSL 要件を確認:
- サーバーが特定の SSL モードを要求している可能性がある
- 証明書のインポートが必要な場合がある
HarborDB で異なる SSL モードを試す:
- prefer から始める
- 次に require を試す
- 最後に verify-full (証明書が必要) を試す
verify-full を使用する場合は証明書をインポート:
- サーバー管理者から証明書を取得
- macOS キーチェーンアクセスにインポート
- HarborDB に証明書へのアクセスを許可

パフォーマンスの問題

クエリの実行が遅い

診断手順:

EXPLAIN を使用して分析:
- HarborDB で「説明」(⚡) ボタンをクリック
- 「Seq Scan」（フルテーブルスキャン）を探す - 多くの場合遅い
- 「Index Scan」を探す - 通常はより速い

不足しているインデックスを確認:

-- インデックスのない頻繁にフィルタリングされる列を探す
SELECT schemaname, tablename, attname
FROM pg_stats
WHERE schemaname NOT LIKE 'pg_%'
  AND n_distinct > 100
  AND attname NOT IN (
    SELECT column_name
    FROM information_schema.columns
    WHERE table_schema = schemaname
      AND table_name = tablename
  );

適切なインデックスを追加:

-- 単一列インデックス
CREATE INDEX idx_table_column ON table_name(column_name);

-- 一般的なクエリパターンのための複数列インデックス
CREATE INDEX idx_table_col1_col2 ON table_name(col1, col2);

クイックパフォーマンス修正:

探索的なクエリに LIMIT 句を追加
必要な列のみを選択（SELECT * ではない）
インデックス付きの列で WHERE 句を使用
インデックス使用を妨げる WHERE 句内の関数を避ける

メモリ使用量が高い

症状:

HarborDB が過剰な RAM を使用（アクティビティモニターで確認）
システムが遅くなる
"メモリ不足" エラー

解決策:

クエリキャッシュサイズを削減:
- 環境設定 → パフォーマンス → クエリキャッシュ
- メモリに制約がある場合はデフォルトの 256MB から 128MB に削減
ストリーミングモードを有効化:
- 環境設定 → パフォーマンス → ストリーミング結果
- 10,000 行以上の結果で有効化
- 大規模なデータセットのメモリ使用量を削減
開いているタブを管理:
- 未使用のクエリタブを閉じる
- HarborDB はタブごとに結果セットをメモリに保持
- 通常の作業: 最大 5-10 タブ
HarborDB を再起動:
- 大量使用時に毎日終了して再起動
- 蓄積されたメモリ使用量をクリア

アプリケーションが遅い

クイック修正:

他のアプリケーションを閉じる:
- 特にリソース集約型のアプリ（多くのタブを開いた Chrome、Docker など）
- アクティビティモニターでメモリ圧力を確認
UI アニメーションを削減:
- 環境設定 → 外観 → アニメーションを無効化
- 古いハードウェアでよりスムーズな体験
インターフェイスを簡素化:
- 使用していないサイドバーセクションを折りたたむ
- シンプルなカラーテーマを使用
- 非常に大きなクエリのシンタックスハイライトを無効化

エクスポートとファイルの問題

エクスポートが失敗するか空のファイルが作成される

一般的な原因と解決策:

権限の問題:

# フォルダの権限を確認
ls -la ~/Desktop/

# 別の保存場所を試す
# デスクトップの代わりに書類フォルダを使用

ディスク容量の問題:

# 利用可能なディスク容量を確認
df -h

# エクスポートサイズの少なくとも2倍の空き容量が必要

ファイル形式の問題:
- CSV: 異なる区切り文字を試す（カンマ、セミコロン、タブ）
- CSV: テキスト修飾子を追加（フィールドを引用符で囲む）
- JSON: 「整形」と「コンパクト」の両方の形式を試す
大規模なエクスポートの最適化:
- 小さなチャンクでエクスポート
- 大規模なデータセットには JSON ではなく CSV を使用
- エクスポート設定で圧縮を有効化

「ファイルが見つかりません」またはエクスポートが見つからない

デフォルトの保存場所を確認:
- 環境設定 → エクスポート → デフォルトの保存場所
- 頻繁にアクセスするフォルダに変更

ファイルを検索:

# 最近の CSV/JSON ファイルを検索
find ~ -name "*.csv" -mtime -1
find ~ -name "*.json" -mtime -1

ゴミ箱を確認:
- エクスポートが誤って削除された可能性がある
- 見つかった場合はゴミ箱から復元

インターフェイスと表示の問題

テーマが正しく適用されない

macOS ダーク/ライトモードの問題:

システム設定を確認:
- システム設定 → 外観
- 「自動」または希望のテーマが選択されていることを確認
HarborDB を再起動:
- 完全に終了 (⌘ + Q)
- システムテーマを適用するために再起動
HarborDB でテーマを強制:
- 環境設定 → 外観 → テーマ
- 「ライト」、「ダーク」、または「システム」を選択

機能やメニューが見つからない

HarborDB を更新:
- アップデートを確認 (HarborDB → アップデートを確認)
- App Store → アップデートタブ
インターフェイスレイアウトをリセット:
- ウィンドウ → レイアウトをリセット
- デフォルトのパネル配置を復元
機能の可用性を確認:
- 一部の機能には特定の PostgreSQL バージョンが必要
- 機能ドキュメントで互換性を確認

テキスト表示の問題

フォントサイズ/読みやすさの問題:

エディタのフォントサイズを調整:
- 環境設定 → エディタ → フォントサイズ
- 読みやすさのために大きくする
macOS ズームを使用:
- システム設定 → アクセシビリティ → ズーム
- 一時的な拡大のために有効化
高コントラストモード:
- システム設定 → アクセシビリティ → ディスプレイ
- 視認性を高めるためにコントラストを増加

macOS 固有の問題

「アプリが壊れています」エラー

HarborDB を開くとき:

# 検疫属性を削除
sudo xattr -cr /Applications/HarborDB.app

# HarborDB を再度開く
open /Applications/HarborDB.app

Gatekeeper 警告

直接ダウンロードの場合（App Store 以外）:

システム設定 → プライバシーとセキュリティ
「セキュリティ」セクションまでスクロール
HarborDB 警告の横の「開く」をクリック
開くことを確認

Touch ID/キーチェーンアクセスの問題

「HarborDB がパスワードを使用したい」エラー:

キーチェーン権限をリセット:
- キーチェーンアクセスアプリを開く
- 「HarborDB」を検索
- 既存のエントリを削除
- HarborDB で接続を再追加
キーチェーンを修復:
- キーチェーンアクセス → ファイル → キーチェーン修復
- 「ログイン」キーチェーンで修復を実行

macOS バージョンとの互換性

最小: macOS 12.0 (Monterey) 推奨: macOS 13.0 (Ventura) 以降

互換性を確認:

# macOS バージョンを確認
sw_vers

# アーキテクチャを確認（Apple Silicon vs Intel）
uname -m

データベース固有の問題

"リレーションが存在しません"

テーブルをクエリするとき:

スキーマを確認:

-- 現在のスキーマのすべてのテーブルを一覧表示
\dt

-- すべてのスキーマのテーブルを一覧表示
SELECT schemaname, tablename
FROM pg_tables
WHERE tablename LIKE '%your_table%';

修飾名を使用:

-- 代わりに: SELECT * FROM users;
-- スキーマ修飾を使用:
SELECT * FROM public.users;
SELECT * FROM auth.users;

デフォルトスキーマを設定:
- HarborDB で接続を編集
- 「デフォルトスキーマ」をよく使用するスキーマに設定

データベースオブジェクトの権限エラー

リレーションへのアクセス許可がありません

権限を確認:

-- スーパーユーザーまたはテーブル所有者として接続
SELECT grantee, privilege_type
FROM information_schema.role_table_grants
WHERE table_name = 'your_table';

権限をリクエスト:

-- 例: SELECT 権限を付与
GRANT SELECT ON table_name TO your_username;

大規模なデータセットの処理

"メモリ不足" または極端に遅い:

サーバーサイドページネーションを使用:

-- 代わりに: SELECT * FROM huge_table;
-- 使用:
SELECT * FROM huge_table LIMIT 1000 OFFSET 0;
-- 次ページのために OFFSET を増加

HarborDB でストリーミングを有効化:
- 環境設定 → パフォーマンス → ストリーミングモード
- しきい値を設定（例: 10,000 行）
頻繁な複雑なクエリにマテリアライズドビューを使用

ネットワークとリモート接続の問題

リモート接続が遅い

最適化のヒント:

圧縮を有効化:
- 接続設定 → 詳細 → 圧縮
- データ転送サイズを削減
SSH トンネリングを使用:
- 直接接続よりも安全
- 制限されたネットワークでパフォーマンスを向上できる
重いクエリをスケジュール:
- ピーク時間外に実行
- HarborDB のクエリスケジューラ機能を使用

断続的な接続切断

タイムアウト設定を増加:
- 接続設定 → タイムアウト
- 30秒から60秒に増加
Keep-Alive を有効化:
- 接続設定 → Keep-Alive
- アイドル接続を維持

ネットワークの安定性を確認:

# ネットワークの安定性をテスト
ping -c 100 your-server-address
# パケットロスを確認

サポートに連絡する前に

収集する情報

トラブルシューティング後も問題が続く場合は、次の情報を収集:

システム情報:
- macOS バージョン（Apple メニュー → この Mac について）
- HarborDB バージョン（HarborDB → HarborDB について）
- PostgreSQL バージョン（SELECT version();）
エラーの詳細:
- 正確なエラーメッセージ（可能であればスクリーンショット）
- 問題を再現する手順
- 問題が発生した時期
設定の詳細:
- 接続設定（パスワードなし）
- 問題を引き起こすクエリ（該当する場合）
- エクスポート設定（エクスポート関連の場合）

HarborDB の診断ツール

診断レポートを生成:
- ヘルプ → 診断レポートを作成
- ログ、設定、システム情報を含む
アプリケーションログを表示:
- ヘルプ → ログを表示
- エラーと警告メッセージでフィルタ
システムログ用の Console.app:
- Console.app を開く
- 「HarborDB」を検索
- クラッシュレポートを探す

クイックセルフチェック

サポートに連絡する前に確認:

[ ] macOS が最新である
[ ] HarborDB が最新バージョンである
[ ] PostgreSQL サーバーが実行中である
[ ] ネットワーク接続が安定している
[ ] 十分なディスク容量がある
[ ] ユーザーに必要な権限がある

サポートへの連絡

すべてのトラブルシューティング手順を試しても問題が続く場合:

メールサポート: support@harbordb.com
メールに含める内容:
- 診断レポート（ヘルプメニューから）
- エラーメッセージのスクリーンショット
- 問題を再現する手順
- 試したトラブルシューティング手順
期待される応答時間:
- 最初の応答: 24-48時間以内
- 営業時間: 月曜日～金曜日、9AM-5PM EST
- 緊急の問題: メールに「URGENT」と記入

予防措置

定期的なメンテナンス

毎週:

メモリをクリアするために HarborDB を再起動
一時的なエクスポートファイルをクリア
重要な接続設定をバックアップ

毎月:

HarborDB と PostgreSQL を更新
遅いクエリを確認して最適化
未使用の接続をクリーンアップ

問題を避けるためのベストプラクティス

接続管理:
- 意味のある接続名を使用
- 定期的に接続をテスト
- 未使用の接続を削除
クエリ開発:
- 探索中は常に LIMIT を使用
- 大きなクエリを実行する前に EXPLAIN でテスト
- 複雑なクエリを再利用のために保存
システムメンテナンス:
- macOS を最新の状態に保つ
- 定期的な Time Machine バックアップ
- ディスク容量を監視

追加リソース

HarborDB FAQ - よくある質問と回答
はじめにガイド - インストールとセットアップ
パフォーマンス最適化 - 高度なチューニング
macOS セキュリティガイド - セキュリティのベストプラクティス

よくある問題とトラブルシューティング