SupabaseからInsforgeへの移行：ステップ・バイ・ステップガイド

SupabaseからInsforgeへ数分で移行：本番環境でテスト済みの完全ガイド

SupabaseからInsforgeへのプロジェクト移行を決断された皆様、ようこそ。移行作業は気が重いものかもしれません。パスワードリセットを強制せずに全ユーザーを移行するにはどうすればいいのか？すべてのファイルを転送し、リンクを更新するには？データベーススキーマや貴重なデータはどうなるのか？など、様々な疑問が浮かぶことでしょう。

ご安心ください。私たちがサポートします。

このガイドでは、Supabaseプロジェクト全体を自己ホスト型のInsforgeインスタンスへシームレスに移行するために設計された、本番環境でテスト済みの完全な移行ツールキットを紹介します。これは単なる部分的なデータダンプではありません。以下をすべて保持する完全な移行です。

• ✅ ユーザー認証（パスワードも含む！）
• ✅ 完全なデータベース（スキーマとデータ）
• ✅ すべてのストレージファイル（正確なパスを含む）
• ✅ 外部キー関係（ユーザーIDを保持することで）

このツールキットは、実際の制作環境で徹底的にテストされ、39人のユーザー、985行のデータベースレコード、1,500以上のストレージファイルをデータ損失ゼロで移行することに成功しています。セルフホスティングに関する詳細は、InsforgeのGitHubリポジトリをご覧ください。

さあ、始めましょう。

準備：移行前のチェックリスト

スムーズな移行のために、まずは環境をセットアップしましょう。

1. 前提条件

まず、必要なツールとアクセス権があることを確認してください。

• ソフトウェア：
  • Node.js (v20以上)
  • PostgreSQLクライアント (psql)
• アクセス権：
  • Supabaseプロジェクトの認証情報（APIキー、データベースURL）。
  • 管理者APIキーを持つアクティブなInsforgeインスタンス。

2. 環境設定

次に、移行ツール自体を設定します。

まず、ツールキットのリポジトリをクローン（またはソースをダウンロード）し、依存関係をインストールします。

次に、環境設定ファイルを作成します。サンプルファイルをコピーして、自分用の.envファイルを作成してください。

新しく作成した.envファイルを開き、移行元のSupabaseプロジェクトと新しいInsforgeプロジェクトの両方の認証情報を入力します。

Supabaseの認証情報を見つける

.envファイルに入力するには、Supabaseプロジェクトのダッシュボードから3つの重要な情報が必要です。

1. SUPABASE_URLとSUPABASE_SERVICE_ROLE_KEY：
   • Supabaseプロジェクトに移動します。
   • Project Settings（歯車のアイコン）に移動します。
   • APIをクリックします。
   • ここにプロジェクトURLとservice_roleシークレットキーがあります。
2. SUPABASE_DB_URL（接続文字列）：
   • Supabaseプロジェクトのダッシュボードで、ページ上部のConnectボタンをクリックします。
   • データベースの接続詳細が表示されたパネルが開きます。
   • Direct connectionセクションからURIをコピーします。
   • 重要： 文字列内の[YOUR-PASSWORD]プレースホルダを、実際のデータベースパスワードに置き換える必要があります。忘れた場合は、Project Settings > Databaseでリセットできます。

3. 接続の確認

移行を実行する前に、ツールが両方のデータベースに接続できることを確認しましょう。以下のコマンドを実行して接続をテストします。

両方のコマンドがエラーなく実行されれば、本番の準備は完了です！

---

大移行：ステップバイステップガイド

移行は3つの論理的なフェーズに分かれています。最良の結果を得るために、順番に従ってください。

フェーズ1：ユーザーの移行（パスワードリセットなし！）

これは通常、どんな移行でも最も厄介な部分ですが、このツールキットを使えば簡単です。元のパスワードを保持したまま、すべてのユーザーアカウントを移行します。

ステップ1.1：Supabaseからユーザーをエクスポート

このコマンドはSupabaseプロジェクトに接続し、auth.usersテーブルからすべてのユーザーをローカルのJSONファイルにエクスポートします。

期待される出力：

これにより、ユーザーIDや暗号化されたパスワードを含むユーザー詳細が記載されたauth-export.jsonというファイルが作成されます。

ステップ1.2：Insforgeにユーザーをインポート

次に、auth-export.jsonファイルからInsforgeインスタンスにユーザーをインポートします。このスクリプトは、元のユーザーID（外部キーにとって重要）とbcryptでハッシュ化されたパスワードを保持します。

期待される出力：

プロのヒント： このスクリプトはべき等です。つまり、複数回実行しても重複ユーザーは作成されません。既存のレコードが見つかった場合は、それを更新するだけです。

フェーズ2：データベースの移行

次に、スキーマ、データ、さらには行レベルセキュリティ（RLS）ポリシーを含むPostgreSQLデータベース全体を移行します。

ステップ2.1：データベーススキーマとデータのエクスポート

このコマンドはpg_dumpを使用して、Supabaseのパブリックスキーマの完全なSQLバックアップを作成します。

期待される出力：

これによりdatabase-export.sqlファイルが生成されます。

ステップ2.2：Insforge用にSQLを変換

Supabaseはいくつかの特定の関数や拡張機能を使用しています。このスクリプトは、エクスポートされたSQLファイルをクリーンアップし、Supabase固有のコードを削除し、RLSポリシーを更新し（例：auth.uid()をuid()に）、Insforgeと互換性があるようにします。

期待される出力：

これにより、Insforge対応の新しいファイルdatabase-export.insforge.sqlが作成されます。

ステップ2.3：データベースをInsforgeにインポート

最後に、変換されたSQLファイルをInsforgeプロジェクトにインポートしましょう。

期待される出力：

これでデータベースのスキーマとデータは正常に移行されました！

フェーズ3：ファイルストレージの移行

最終フェーズは、Supabase StorageからInsforge Storageにすべてのファイルを移動することです。このプロセスは正確なファイルパスを保持するため、リンク切れを防ぐ上で非常に重要です。

ステップ3.1：ストレージバケットの再作成

まず、スクリプトはSupabaseプロジェクトからバケットのリストを読み取り、公開・非公開設定を保持したまま、Insforgeに同一のバケットを作成します。

期待される出力：

ステップ3.2：Supabaseからすべてのファイルをダウンロード

このコマンドは、元のディレクトリ構造を保持したまま、Supabaseのすべてのバケットからすべてのファイルをダウンロードします。

期待される出力：

すべてのファイルはローカルのstorage-downloads/ディレクトリに保存されます。

ステップ3.3：すべてのファイルをInsforgeにアップロード

次に、ダウンロードしたすべてのファイルをInsforgeの対応するバケットにアップロードします。

期待される出力：

ステップ3.4：最後の仕上げ - すべてのストレージURLを更新

これが魔法の杖です。あなたのデータベースには、Supabase Storageを指す何千ものURLが含まれている可能性があります。このスクリプトはInsforgeデータベースに接続し、すべてのテーブルに対して一括検索置換を実行します。複雑なJSONBフィールド内であっても、すべてのSupabaseストレージURLを新しいInsforge URLにスマートに更新します。

期待される出力：

これで完了です！プロジェクト全体が移行されました。

---

次のステップは？移行後の手順

データは移行されましたが、まだ終わりではありません。アプリケーションをInsforgeで実行するための最終ステップです。

1. アプリケーションコードの更新： アプリケーションのクライアント設定を、SupabaseではなくInsforgeインスタンスを指すように変更します。MCPを使用したSDKの再設定に関する詳細なガイダンスについては、関連ブログ記事をご覧ください。

   // 変更前 (Supabase) const supabase = createClient('SUPABASE_URL', 'SUPABASE_ANON_KEY'); // 変更後 (Insforge) const insforge = createClient('YOUR_INSFORGE_API_URL', 'YOUR_INSFORGE_API_KEY');

   Copy

2. エンドツーエンドテスト： アプリケーションを徹底的にテストします。

   • ユーザーは古いパスワードでログインできますか？
   • 画像やファイルは正しく読み込まれますか？
   • データ関連のすべての機能は期待どおりに動作しますか？

3. クリーンアップ： すべてが正常に動作することを確認したら、一時的な移行ファイル（storage-downloads/、.sql、.json）を削除できます。

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

• ストレージインポート中のFile too largeエラー： ファイルがInsforgeインスタンスのアップロード制限を超えています。制限を増やすか、ファイルを手動で移行する必要があるかもしれません。
• パスワードでのログイン失敗： import:authスクリプトが正常に実行されたことを再確認してください。bcryptパスワードハッシュはそのまま保持されているはずです。
• 接続タイムアウト： あなたのIPがSupabaseのネットワーク制限でホワイトリストに登録されていること、および.envの接続文字列が正しいことを確認してください。

移行、頑張ってください！🚀