MongoDB データベースを接続する

MongoDB データベースを接続して、Squid のリアルタイムストリーミング、堅牢なクエリ、AI 機能を活用しましょう。

TL;DR

このチュートリアルでは、新しい MongoDB データベースを Squid プロジェクトに接続する方法を学びます。内容は次のとおりです。

• Squid Console で integration を作成する
• 外部データベース向けのセキュリティルールを適用する
• クライアントプロジェクトから Squid を使って MongoDB をクエリする

このチュートリアルでは、React と Squid を使って MongoDB コレクション内のサンプルデータに接続します。データベース用語、React、Squid プラットフォームの基本的な理解があると役立ちますが、このガイドに前提条件はありません。

新しい MongoDB project を作成する

まず、MongoDB アカウントにサインインして新しい project を作成します。MongoDB は project の overview ページへリダイレクトします。そこに移動したら、Create ボタンをクリックして database deployment を作成します。 この deployment では無料の M0 tier を選択してください。クラスターには、sample-data のような任意のカスタム名を付けることもできます。

次に MongoDB は、Security セクションの Quickstart タブへリダイレクトするはずです。これは左側パネルのメニュー内にあります。MongoDB データベースに接続するには、認可されたユーザーを作成する必要があります。

Step 1 では、ユーザー名とパスワードで接続を認証します。ここで選んだパスワードは Squid を MongoDB に接続するときに必要になるため、必ずコピーしておいてください。完了したら Create User をクリックします。

次に Network Access タブへ移動して、Squid の IP アドレスを追加します。Squid がデータベースへアクセスする必要があるため、Squid の IP アドレスからのアクセスを許可します。IP アドレスは、Squid Console のapplication overview page の Cloud provider セクションで確認できます。Add Entry をクリックして、各 IP アドレスを Access List に追加します。 最後にページ下部の Finish and Close をクリックしてセットアップを完了します。

project overview ページで、Database Deployments の下にクラスターが表示されているはずです。クラスターの Overview ページへ移動し、クラスターの Ellipses (...) ボタンをクリックします。次に Load Sample Dataset をクリックして、MongoDB が提供するスターターデータをクラスターに読み込みます。データの追加には数分かかることがあるため、しばらく待ってください。

データがクラスターに入ったら、Browse Collections をクリックして追加されたデータを確認できます。sample_airbnb データベースと、その中の listingsAndReviews コレクションなどが見られるはずです。

MongoDB 側の準備はこれで完了です。次に、React プロジェクトを Squid と一緒に開始して、MongoDB のサンプルデータを使えるようにしましょう。

新しい React project を作成する

まず、任意の場所にルート project ディレクトリを作成します。

mkdir mongo

次に mongo ディレクトリへ cd し、Vite を使って新しい React TypeScript アプリケーションを作成します。

cd mongo
npm create vite@latest mongo-frontend -- --template react-ts

次に、新しく作成されたディレクトリへ cd し、依存関係をすべてインストールします。

cd mongo-frontend
npm install

console で新しい app を作成する

Squid Console に移動し、mongo-tutorial（または同様の名前）で新しい application を作成します。

注意

Squid は development と production の 2 種類の target environment を提供します。このチュートリアルでは dev environment を使用する前提ですが、prod も選択できます。application が動作するためには、プロジェクト全体で同じ target environment を使用していることを確認してください。詳細は Squid の environments を参照してください。

console の手順に従って backend template project を生成します。これらの手順は、application overview ページの Initialize Backend ボタンをクリックすると確認できます。frontend と backend のディレクトリを兄弟関係にするため、backend を初期化する前にルート project ディレクトリへ cd し戻していることを確認してください。

MongoDB Connector（integration）を作成する

注意

このチュートリアルでは、「integration」と「connector」という用語は同じ概念を指し、同義として扱います。

console で application の Connectors ページへ移動し、新しい MongoDB connector を追加します。integration は environment 間で共有されないため、正しい environment を使用していることを確認してください（上の注意を参照）。

次に、4 つの入力フィールドに値を入力します。

• Connector ID: この integration が何を表すか分かる意味のある ID を選びます。例: mongo
• Database Connection String: MongoDB project overview ページで Connect ボタンをクリックすると確認できます。ボタンをクリックすると接続方法の選択を促すモーダルが表示されるので、Shell オプションを選択し、connection string を見つけてください。 Squid が必要とする文字列部分は、通常 "mongodb+srv" で始まり "mongodb.net" で終わります。前後の文字は無視できますが、その間の文字は必要です。さらに、使用するデータベース名として "/sample_airbnb" を末尾に追加します。最終的に、次のような形式になります: mongodb+srv://YOUR_CLUSTER_NAME.SOME_ID_CHARS.mongodb.net/sample_airbnb.
  この値を Squid Console にコピーしてください。MongoDB 側で他に必要な作業はありません。
• Database Username と Database Password: これらは MongoDB Setup で作成しました。ここで console にコピーし、password は新しい secret として作成します。

database connection string、username、password を提供することで、Squid と MongoDB データベースの接続が確立されます。 Test Connection ボタンをクリックして、Squid と MongoDB 間の接続が正しく動作していることを確認してください。

Next ボタンをクリックすると、Squid が sample_airbnb データベース内の現在のデータをもとに database schema を自動検出します。データに変更があった場合は、手動で Rediscover Schema を実行することもできます（このチュートリアルでは不要です）。

これらの手順を完了したら、Add Connector をクリックしてプロジェクトに追加します。

Squid の IP アドレスを allowlist に追加してください

エラーが発生する場合は、Mongo Atlas の Web サイトの Network Access タブに Squid の IP アドレスが追加されているか再確認してください。Squid の IP アドレスは、Squid Console の application overview page の Cloud provider セクションで確認できます。

Security rules

Security rules はすべての database integration で必須です。これにより、特定のコレクションやアクション、またはデータベース全体に対するアクセスを認可するためのカスタムロジックを作成できます。このチュートリアルの範囲外である認証（authentication）と認可（authorization）は扱わないため、mongo integration に対して public access を許可する security rule を作成します。

Tip

データを安全に保護する方法について詳しくは、Squid backend の security rules を参照してください。

Security rules は mongo-backend/src/service/example-service.ts にあります。security rules は、SquidService クラスに decorator を追加することで拡張できます。database integration 向けの security rule を作成するには、database action の type と CONNECTOR_ID をパラメータとして受け取る @secureDatabase decorator を使用します。ExampleService クラスに新しい security rule を作成してください。

Backend code

import { secureDatabase, SquidService } from '@squidcloud/backend';

...

export class ExampleService extends SquidService {

  ...

  @secureDatabase("all", "mongo")
  allowAccessToMongo(): boolean {
    return true; // Allows all access to the mongo integration
  }
}

クライアントコードを編集する

最後のステップは、React プロジェクトで integration を使用することです。React 版の Squid Client SDK を使います。

Setup

まず、mongo-frontend ディレクトリで Squid React SDK をインストールします。

npm install @squidcloud/react

次に src/main.tsx で、App コンポーネントを SquidContextProvider でラップします。以下のプレースホルダーは .env ファイル内の設定値に置き換えてください。 .env ファイルは console で app を作成する 手順中に自動生成され、backend ディレクトリ内にあります。

Client code

import ReactDOM from 'react-dom/client'
import { StrictMode } from 'react';
import App from './App.tsx'
import './index.css'
import { SquidContextProvider } from '@squidcloud/react';

...

ReactDOM.createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <SquidContextProvider
      options={{
        appId: 'YOUR_APP_ID',
        region: 'YOUR_REGION', // example: 'us-east-1.aws'
        environmentId: 'dev | prod', // choose one of 'dev' or 'prod'
        squidDeveloperId: 'YOUR_SQUID_DEVELOPER_ID',
      }}
    >
      <App />
    </SquidContextProvider>
  </StrictMode>
);

プロジェクトを実行する

プロジェクトを実行するには、クライアントの React プロジェクトと backend の Squid プロジェクトの両方を起動する必要があります。

backend を実行するには、backend ディレクトリで次を実行します。

squid start

client を実行するには、frontend ディレクトリで次を実行します。

npm run dev

これで、クライアントプロジェクトが http://localhost:PORT で動作しているのが確認できるはずです（PORT はターミナルに出力されます）。まだページに表示する内容を編集していないため、Vite のスタータープロジェクトが表示されるはずです。

単一ドキュメントをクエリする

Squid のメソッドを使って、コレクションのクエリは複数の方法で実行できます。最初の方法は、document ID を使って listingsAndReviews コレクション内の単一ドキュメントをクエリする方法です。

built-in ではない integration の document ID は、オブジェクト形式である必要があります。Squid における document ID の詳細は、documentation を参照してください。

先ほど console で検出した schema によると、primary key は string 型の _id フィールドを含む必要があります。

MongoDB のデータを見ると、任意のエントリの _id 値を選んで、そのドキュメントをクエリし、クライアントにデータを表示できます。mongo-frontend/src/App.tsx を次のコードに編集してください。

Client code

import './App.css';
import { useCollection, useDoc } from '@squidcloud/react';

function App() {
  const collectionRef = useCollection('listingsAndReviews', 'mongo');

  const { data: listing } = useDoc(collectionRef.doc({ _id: '10057826' }));

  return (
    <>
      <h2>
        Note: this is MongoDB sample data. Any data displayed here may not be
        accurate
      </h2>
      <div>Name: {listing?.name}</div>
      <div>URL: {listing?.listing_url}</div>
      <div>Price: ${listing?.price}</div>
    </>
  );
}

export default App;

上で説明したのと同じ方法でプロジェクトを実行してください。すべて正しくセットアップされていれば、次のような表示が見えるはずです。

おめでとうございます！外部の MongoDB データベースに対して初めてのクエリを完了しました。クエリについて詳しくは、documentation を参照してください。続けて、もう少し複雑なクエリを 1 つ書いてみましょう。

クエリを作成する

「最も安い選択肢は何か？」と尋ねるのは、AirBnB が提供する最高のお宝を求めてデジタルの冒険に出るようなものです！ Squid の高度なクエリオプションを使えば、利用可能な最安の選択肢を簡単に見つけられます。クエリは次のようになります。

Client code

const { data: cheapListings } = useQuery(collectionRef.query().where('price', '<=', 10));

さらに、場所や宿泊可能人数などを指定して、このクエリを拡張することもできます。

すべてをまとめると、最終的な mongo-frontend/src/App.tsx は次のようになります。

Client code

import './App.css';
import { useCollection, useDoc, useQuery } from '@squidcloud/react';

function App() {
  const collectionRef = useCollection('listingsAndReviews', 'mongo');

  const { data: listing } = useDoc(collectionRef.doc({ _id: '10057826' }));

  const { data: cheapListings } = useQuery(
    collectionRef.query().where('price', '<=', 10)
  );

  return (
    <>
      <h2>
        Note: this is MongoDB sample data. Any data displayed here may not be
        accurate
      </h2>
      <div>Name: {listing?.name}</div>
      <div>URL: {listing?.listing_url}</div>
      <div>Price: ${listing?.price}</div>
      <hr />
      <h3>Cheap Listings</h3>
      {cheapListings.map((listing, i) => (
        <div key={i}>
          Name: {listing.data.name} --- URL: {listing.data.listing_url}
        </div>
      ))}
    </>
  );
}

export default App;

このコードにより、先ほどクエリした listing と並んで、$10 以下の AirBnB の一覧が表示されるはずです。

次のステップ

このガイドを完了したら、Squid が提供する他の機能もぜひ試してみてください。MongoDB integration を使えば、データの更新（mutate） も行えます。さらに、authentication をセットアップして、データの特定部分へのアクセスを誰が持つかを制御することもできます。