> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Square Cloud の MongoDB: 接続、制限、対応機能

> Square Cloud のマネージド MongoDB: 接続文字列、クライアント証明書を使う TLS、スタンドアロンサーバー (トランザクションと変更ストリームなし)、ユーザーロール、メモリ、プロファイラー、よくあるエラー。

クライアント証明書による TLS 接続と、自分のデータベース、コレクション、インデックスを管理できるユーザーを備えたマネージド MongoDB サーバーです。すべてのエンジンに共通する事項 (制限、snapshot、Insights) は[データベースの概要](https://docs.squarecloud.app/ja/services/databases.md)にまとめています。

## 接続する

ダッシュボードのデータベースのページから接続 URL をコピーします。形式は次のとおりで、`default` ユーザーは `admin` データベースに対して認証します。

```
mongodb://default:PASSWORD@HOST:PORT
```

MongoDB では **TLS とクライアント証明書**が必須です。**接続** → **SSL/TLS 証明書**から `.pem` をダウンロードし、クライアント証明書と CA の両方として渡します: `tls=true`、`tlsCertificateKeyFile`、`tlsCAFile`。

> [!WARNING]
>
> URL にデータベース名を追加すると (`mongodb://...:PORT/mydb`)、ドライバーは `mydb` に対して認証しようとし、ログインは `Authentication failed` で失敗します。その場合は `authSource=admin` を付けてください: `mongodb://default:PASSWORD@HOST:PORT/mydb?authSource=admin`。

> [tab] Node.js
>
> ```javascript theme={"system"}
> import { MongoClient } from "mongodb";
>
> // One client for the whole process, created once and reused.
> export const client = new MongoClient(process.env.MONGO_URL, {
>   tls: true,
>   tlsCAFile: "certificate.pem",
>   tlsCertificateKeyFile: "certificate.pem",
>   maxPoolSize: 10,
> });
>
> await client.connect();
> const users = client.db("app").collection("users");
> ```

> [tab] Mongoose
>
> ```javascript theme={"system"}
> import mongoose from "mongoose";
>
> await mongoose.connect(process.env.MONGO_URL, {
>   dbName: "app",
>   tls: true,
>   tlsCAFile: "certificate.pem",
>   tlsCertificateKeyFile: "certificate.pem",
> });
> ```

> [tab] Python
>
> ```python theme={"system"}
> import os
> from pymongo import MongoClient
>
> client = MongoClient(
>     os.environ["MONGO_URL"],
>     tls=True,
>     tlsCAFile="certificate.pem",
>     tlsCertificateKeyFile="certificate.pem",
> )
> db = client["app"]
> ```

> [tab] mongosh
>
> ```bash theme={"system"}
> mongosh "mongodb://default:PASSWORD@HOST:PORT" \
>   --tls --tlsCAFile certificate.pem --tlsCertificateKeyFile certificate.pem
> ```

## スタンドアロンサーバー

各データベースは単一の**スタンドアロン**サーバーです。レプリカセットも oplog もなく、レプリカセットに変換することもできません。そのため、次のようになります。

| 機能 | 状況 | 発生するエラー |
| :- | :- | :- |
| 複数ドキュメントのトランザクション | 利用不可 | `Transaction numbers are only allowed on a replica set member or mongos` |
| 変更ストリーム (`watch()`) | 利用不可 | `The $changeStream stage is only supported on replica sets` |
| MongoDB での Prisma | 非対応 (Prisma にはレプリカセットが必要) | |
| 公式ドライバーと Mongoose | 対応 (トランザクションなし) | |

単一ドキュメントへの書き込みはアトミックです。`$inc`、`$push`、`$set` などの演算子を使った更新や `findOneAndUpdate` で、本来トランザクションが必要になる多くのケースをカバーできます。トランザクション付きのセッションを開くライブラリ (たとえば Mongoose の `connection.transaction()`) は、上記の最初のエラーで失敗します。

## 接続数

各データベースは最大 256 の同時接続を受け付けます。`MongoClient` はそれぞれ独自のプール (`maxPoolSize`) に**加えて 2 つの監視用接続**を保持するため、**プロセスごとに 1 つのクライアント**を作成して使い回してください。リクエストごとにクライアントを作ると、すぐに接続が足りなくなります。開いている接続を誰が保持しているかは **Insights** タブで確認できます。

## ユーザーと権限

`default` ユーザーには `readWriteAnyDatabase` と `dbAdminAnyDatabase` のロールがあります。データベース、コレクション、インデックスの作成と削除ができ、`db.stats()`、`$collStats`、`explain()`、プロファイラー (`system.profile`) を参照できます。

ユーザーやロールの作成、`db.serverStatus()` の実行、ほかの接続の操作の参照 (`currentOp`)、`top`、`hostInfo`、`setParameter`、`shutdown` の実行はできません。`serverStatus` に依存する監視ツールは動作しないため、代わりに `db.stats()`、`$collStats`、プロファイラーを使ってください。

## メモリ

MongoDB は、データベースの RAM から WiredTiger キャッシュのサイズを決めます: **(RAM − 1 GB) の 50% と 256 MB のうち大きいほう**です。

| データベースの RAM | WiredTiger キャッシュ |
| :- | :- |
| 1 GB | 256 MB |
| 2 GB | 512 MB |
| 4 GB | 1.5 GB |
| 8 GB | 3.5 GB |

* サイズはサーバーの起動時に読み込まれます。RAM を変更したらデータベースを再起動してください。調整はできません。
* キャッシュに入るのは、クエリが触れたデータとインデックスのページだけです。
* キャッシュ外のメモリ: 接続ごとに約 1 MB、インデックスの構築、集計 (100 MB を超えるステージはディスクに書き出されます)。
* メモリアロケーターは解放したメモリを再利用のために保持するため、ダッシュボードに表示される RAM は上昇したあと高いまま推移します。これは正常な動作で、メモリリークではありません。

## 遅いクエリ

プロファイラーは 100 ms 以上かかった操作を各データベースの `system.profile` コレクション (上限 1 MB) に記録し、**Insights** タブに一覧表示されます。

```javascript theme={"system"}
db.system.profile.find().sort({ ts: -1 }).limit(5)
```

遅いクエリに `explain("executionStats")` を使うと、インデックスが使われているかどうかを確認できます。

## ストレージ

MongoDB は最大 200 MB の独自の診断データを保持し、これはデータベースの 10 GB に含まれます。ストレージが完全にいっぱいになると、MongoDB は停止し、自動では復帰しません。ダッシュボードから起動し、すぐに空き容量を確保してください (不要なコレクションやインデックスを削除します)。[ディスクがいっぱい](https://docs.squarecloud.app/ja/platform/troubleshooting/database-performance.md#ディスクがいっぱい)を参照してください。

## Snapshot

MongoDB の snapshot には、ユーザーを含むすべてのデータベースが圧縮されて含まれます。サイズの上限は圧縮後のエクスポートに適用されます。oplog がないため、書き込み中に取得した snapshot は単一の時点を表すものにはなりません。[snapshot と復元](https://docs.squarecloud.app/ja/services/databases.md#snapshot-と復元)を参照してください。

## よくあるエラー

| メッセージ | 意味 | 対処方法 |
| :- | :- | :- |
| TLS ハンドシェイクが失敗する、またはすぐに `MongoServerSelectionError` になる | クライアントが TLS なし、またはクライアント証明書なしで接続しました。 | `tls`、`tlsCAFile`、`tlsCertificateKeyFile` に `.pem` を指定します。 |
| `Authentication failed` | パスワードが誤っているか、URL が `authSource=admin` なしでデータベース名を指定しています。 | パスワードを確認し、`authSource=admin` を追加します。 |
| `Transaction numbers are only allowed on a replica set member or mongos` | トランザクションにはレプリカセットが必要です。 | 単一ドキュメントのアトミックな更新を使います。 |
| `The $changeStream stage is only supported on replica sets` | 変更ストリームにはレプリカセットが必要です。 | 変更の通知は自分のコードで行います (たとえば Redis の pub/sub)。 |
| `not authorized on admin to execute command` | コマンドに、ユーザーが持っていないロールが必要です (`serverStatus`、`createUser` など)。 | `db.stats()`、`$collStats`、プロファイラーを使います。 |

## お問い合わせ

**技術的な問題**が解決しない場合は、**専門のサポートチーム**がお手伝いします。[**お問い合わせ**](https://squarecloud.app/ja/support)いただければ、どのような問題でも喜んで解決をサポートいたします。サポートの質の高さも、開発者が Google と Trustpilot で Square Cloud に[**402 件のレビューで 4.9/5**](https://www.trustpilot.com/review/squarecloud.app)という評価をつけている理由の 1 つです。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.