AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。

setFeatureCompatibilityVersion(データベースコマンド)

setFeatureCompatibilityVersion

MongoDB の旧バージョンと互換性のないデータを保持する機能を有効または無効にします。setFeatureCompatibilityVersion は adminデータベースに対してのみ発行できます。

機能の互換性バージョンが何であるか、またダウングレードをどのようにサポートするかを学ぶには、MongoDB バージョンとアップグレード パス を参照してください。

警告

下位互換性のないこうした機能を有効にすると、ダウングレード前に保持されていた下位互換性のない機能をすべて削除する必要があるため、ダウングレード プロセスが複雑になる場合があります。

アップグレード後、バーンイン期間中は、下位互換性のない機能を有効にせずに配置を実行します。ダウングレードの可能性が低いと確信できるようになってから、これらの機能を有効にします。

このコマンドは、次の環境でホストされている配置で使用できます。

  • MongoDB Enterprise: サブスクリプションベースの自己管理型 MongoDB バージョン

  • MongoDB Community: ソースが利用可能で、無料で使用できる自己管理型の MongoDB のバージョン

バージョン8.3で変更。

このコマンドの構文は、次のとおりです。

db.adminCommand( { setFeatureCompatibilityVersion: <version>, confirm: true, writeConcern: { wtimeout: <timeout> }, dryRun: <boolean> })

setFeatureCompatibilityVersion コマンドは、次のフィールドがあります。

必須

version に指定できる値は次のとおりです。

バージョン
説明

"8.3"

MongoDB 8.3で利用可能 配置

MongoDB 8.2 と互換性のないデータを永続化する 8.3 の機能を有効にします。

"8.2"

MongoDB 8.2 およびMongoDB 8.3 で利用可能配置

MongoDB 8.3 以降、機能の互換性バージョン を "8.3" から "8.2" へダウングレードできます。

"8.0"

MongoDB 8.0で利用可能 配置

MongoDB 7.0 と互換性のないデータを永続化する 8.0 の機能を有効にします。

"7.0"

MongoDB 7.0 配置で利用可能

MongoDB 6.0 と互換性のないデータを永続化する 7.0 の機能を有効にします。

必須

バージョン7.0の新機能。

機能の互換性の変更を確認し、操作を続行できるようにするには、true に設定します。

confirm パラメーターを省略するか、confirm を true 以外の値に設定すると、コマンドは失敗し、機能の互換性バージョンの変更に関する警告が返されます。

任意

writeConcern は書込み保証 (write concern) の wtimeout の値をミリ秒単位で指定します。

  • プライマリが大多数のレプリカセット ノードからの確認を待機する時間です。時間内に確認応答が受信されない場合、操作は失敗します。

  • デフォルトは 60000 ミリ秒です。レプリカセットのセカンダリ ノードの遅延が wtimeout のデフォルトを超える場合は、時間を長くします。

注意

  • スタンドアロンの場合は、スタンドアロンの mongod インスタンスでコマンドを実行します。

  • レプリカセットの場合は、プライマリでコマンドを実行します。データを保持するノードの過半数が利用可能である必要があります。

  • シャーディングされたクラスターの場合は、mongos インスタンスでコマンドを実行します。

任意

true に設定すると、 MongoDB は機能の互換性バージョンのアップグレードまたはダウングレードをシミュレートします。クラスターに互換性のないデータが含まれている場合、操作はエラーで失敗します。

バージョン8.3の新機能。

機能の互換性バージョンを 8.0 よりもダウングレードする場合は、まず transitionToDedicatedConfigServer コマンドを実行します。ダウングレードの詳細については、「機能の互換性バージョンのダウングレード」を参照してください。

アップグレードされたバージョンに前方互換性の㎏いデータが含まれているクラスターの 機能の互換性バージョン をアップグレードしようとすると、CannotUpgrade エラーを受領します。前方不互換データとは、ターゲットバージョンで削除された機能に依存しているクラスター内のデータのことを指します。

このエラーが発生すると、 によって次のいずれかが実行されます。

  • クラスターデータを変更して前方互換性のない機能を除きます。その後、アップグレードされたバージョンで setFeatureCompatibilityVersion コマンドを再実行して、アップグレードされたバージョンに 機能の互換性バージョン を設定します。

  • 元のダウングレードされたバージョンで setFeatureCompatibilityVersion コマンドを実行し、機能の互換性バージョン を元のバージョンに戻します。

    重要

    機能の互換性バージョン を元のバージョンに設定すると、アップグレード手順が停止し、機能の互換性バージョン がダウングレードされたバージョンに戻ります。クラスターは 機能の互換性バージョン のアップグレードが開始される前の状態にリセットされません。

    `機能の互換性バージョン` のアップグレードで前方互換性のないデータがないことを確認しても、それにもかかわらず停止または失敗した場合、その後の `機能の互換性バージョン` のダウングレードの試行もエラー メッセージを表示して失敗します。機能の互換性バージョンのダウングレードを試す前に、機能の互換性バージョンのアップグレードを完了する必要があります。

ダウングレードされたバージョンに下位互換性のないデータが含まれているクラスターの 機能の互換性バージョン をダウングレードしようとすると、CannotDowngrade エラーを受領します。下位互換性のないデータとは、ターゲット バージョンでは利用できない機能に依存しているクラスター内のデータを指します。

このエラーが発生すると、 によって次のいずれかが実行されます。

  • クラスターデータを変更して下位互換性のない機能を削除し、ダウングレードされたバージョンで setFeatureCompatibilityVersion コマンドを再実行して、fCV をダウングレードされたバージョンに設定します。

  • 元のアップグレード バージョンで setFeatureCompatibilityVersion コマンドを実行し、fCV を元のバージョンに戻します。

    重要

    機能の互換性バージョン を元のバージョンに設定すると、ダウングレード手順が停止し、機能の互換性バージョン がアップグレードされたバージョンに戻ります。クラスターは、機能の互換性バージョン のダウングレードが開始される前の状態に戻りません。

    機能の互換性バージョン ダウングレードで後方互換性のないデータがないことを確認しても、それ以外で停止または失敗すると、その後の 機能の互換性バージョン アップグレードの試行もエラーメッセージと共に失敗します。機能の互換性バージョンをアップグレードする前に、機能の互換性バージョンのダウングレードを完了する必要があります。

8.3 以降、配置の 機能の互換性バージョン を直前のマイナー バージョンにダウングレードできます。

詳しくは、「 8.3から8.2へのダウングレード 」を参照してください。

特定のバックグラウンド操作により、setFeatureCompatibilityVersion の実行が妨げられる可能性があります。実行中の操作を識別するには、currentOp を使用します。

重要

MongoDB 9.0 以降、クラスター内のいずれかのコレクションでインデックス構築が進行中の場合、setFeatureCompatibilityVersion は BackgroundOperationInProgressForNamespace エラーで早期に失敗し、カタログの変更は行われません。The 機能の互換性バージョン は変わりません。チェックの実行後に開始されるインデックス構築は、後でコマンドが失敗する原因となる可能性があります。コマンドを再試行するには、まずインデックス構築が完了するまで待つか、中止してください。

最初の同期中に 機能の互換性バージョンを変更すると、oplog アプリケーション フェーズでエントリを繰り返すと、同期が失敗し、OplogOperationUnsupported エラーが表示される場合があります。操作フェーズで操作が繰り返されなくなるため、次の同期は成功します。

配置
featureCompatibilityVersion

新しい8.3の場合 配置

"8.3"

"8.2" : setFeatureCompatibilityVersion を"8.3" に設定するまで。

新しい8.0の場合 配置

"8.0"

"7.0" : setFeatureCompatibilityVersion を"8.0" に設定するまで。

新しい 7.0 配置の場合

"7.0"

"6.0" : setFeatureCompatibilityVersion を"7.0" に設定するまで。

このコマンドは、内部システム コレクションへの書き込みを実行する必要があります。コマンドが正常に完了しない場合は、安全に再試行できます。操作は冪等です。

MongoDB 6.0 以降では、機能の互換性バージョンをダウングレードする必要がある場合は、クラスター間のレプリケーションとユーザー書込みブロックを無効にしてください。

  1. クラスター間のレプリケーションを有効にしている場合は無効にします。

  2. ユーザーに書込みブロックを有効にしている場合は、無効にします。

    db.runCommand( { setUserWriteBlockMode: 1, global: false } )
  3. 前のコマンドが完了するまで待機します。

  4. setFeatureCompatibilityVersion を使用して機能の互換性バージョンをダウングレードします。

MongoDB Cluster-to-Cluster Sync の詳細については、ドキュメントを参照してください。

アービタは admin.system.version コレクションを複製しません。このため、レプリカセットの fCV 値に関係なく、アービタは常にバイナリのダウングレード バージョンと同じ機能の互換性バージョンを使用します。

例、 MongoDB 5.0 クラスターのアービタの FCV 値は 4.4 です。

mongod インスタンスの featureCompatibilityVersion を表示するには、mongod インスタンスで getParameter コマンドを実行します。

db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )

出力は次のようになります。

{ featureCompatibilityVersion: { version: '5.0' }, ok: 1, '$clusterTime': { clusterTime: Timestamp({ t: 1660318752, i: 5 }), signature: { hash: Binary(Buffer.from("ce0cff3621e9b089fa6d8e9a1e1efc1a1ff15dab", "hex"), 0), keyId: Long("7129893797260951557") } }, operationTime: Timestamp({ t: 1660318752, i: 5 })}

注意

mongos インスタンスでは操作が未定義です。

アクセス制御が有効になっているシャーディングされたクラスターでは、コマンドを実行するためにシャード ローカル ユーザーとしてシャードに接続する必要があります。

MongoDB 7.0 と互換性のないデータを保持する 8.0 機能 を有効にするには、 MongoDB 8.0 配置で機能の互換性を "8.0" に設定します。

注意

admin データベースに対して setFeatureCompatibilityVersion コマンドを実行します。

  • スタンドアロンの場合は、スタンドアロンの mongod インスタンスでコマンドを実行します。

  • レプリカセットの場合は、プライマリでコマンドを実行します。データを保持するノードの過半数が利用可能である必要があります。

  • シャーディングされたクラスターの場合は、mongos インスタンスでコマンドを実行します。

db.adminCommand( { setFeatureCompatibilityVersion: "8.0", confirm: true })

MongoDB 7.0 と互換性のないデータを保持する 8.0 機能 を無効にするには、 MongoDB 8.0 配置で機能の互換性を "7.0" に設定します。

注意

admin データベースに対して setFeatureCompatibilityVersion コマンドを実行します。

  • スタンドアロンの場合は、スタンドアロンの mongod インスタンスでコマンドを実行します。

  • レプリカセットの場合は、プライマリでコマンドを実行します。データを保持するノードの過半数が利用可能である必要があります。

  • シャーディングされたクラスターの場合は、mongos インスタンスでコマンドを実行します。

  • "7.0" featureCompatibilityVersion は、 MongoDB 7.0 およびMongoDB 8.0 の配置でサポートされています。
db.adminCommand( { setFeatureCompatibilityVersion: "7.0", confirm: true })

MongoDB 8.0 からMongoDB 7.0 へのダウングレード プロセスの一部としてこのコマンドを実行する場合は、7.0 と 互換性のない すべての永続機能も削除する必要があります。適切なダウングレード手順を参照してください。

MongoDB 6.0 と互換性のないデータを保持する 7.0 の機能を有効にするには、MongoDB 7.0 配置で機能の互換性を "7.0" に設定します。

注意

admin データベースに対して setFeatureCompatibilityVersion コマンドを実行します。

  • スタンドアロンの場合は、スタンドアロンの mongod インスタンスでコマンドを実行します。

  • レプリカセットの場合は、プライマリでコマンドを実行します。データを保持するノードの過半数が利用可能である必要があります。

  • シャーディングされたクラスターの場合は、mongos インスタンスでコマンドを実行します。

db.adminCommand( { setFeatureCompatibilityVersion: "7.0", confirm: true })

MongoDB 6.0 と互換性のないデータを保持する 7.0 の機能を無効にするには、MongoDB 7.0 配置で機能の互換性を "6.0" に設定します。

注意

admin データベースに対して setFeatureCompatibilityVersion コマンドを実行します。

  • スタンドアロンの場合は、スタンドアロンの mongod インスタンスでコマンドを実行します。

  • レプリカセットの場合は、プライマリでコマンドを実行します。データを保持するノードの過半数が利用可能である必要があります。

  • シャーディングされたクラスターの場合は、mongos インスタンスでコマンドを実行します。

  • "6.0" featureCompatibilityVersion は、MongoDB 6.0 および MongoDB 7.0 の配置でのみサポートされます。
db.adminCommand( { setFeatureCompatibilityVersion: "6.0", confirm: true })

MongoDB 7.0 から MongoDB 6.0 へのダウングレード プロセスの一部として実行する場合には、6.0 と互換性のないすべての永続機能も削除する必要があります。適切なダウングレード手順を参照してください。

次の例では、任意の書込み保証 (write concern) の wtimeout フィールドを 5000(5 秒)に設定しています。

注意

admin データベースに対して setFeatureCompatibilityVersion コマンドを実行します。

  • スタンドアロンの場合は、スタンドアロンの mongod インスタンスでコマンドを実行します。

  • レプリカセットの場合は、プライマリでコマンドを実行します。データを保持するノードの過半数が利用可能である必要があります。

  • シャーディングされたクラスターの場合は、mongos インスタンスでコマンドを実行します。

db.adminCommand( { setFeatureCompatibilityVersion: "5.0", writeConcern: { wtimeout: 5000 }} )

機能の互換性バージョンを設定した後にスタートアップの問題が発生した場合は、MongoDBサポート にお問い合わせください。

このページを評価