ドキュメントのアクセシビリティについて
Oracleのアクセシビリティについての詳細情報は、Oracle Accessibility ProgramのWebサイト(http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc)を参照してください。
Oracle Supportへのアクセス
サポートをご契約のお客様には、My Oracle Supportを通して電子支援サービスを提供しています。詳細情報は(http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info)か、聴覚に障害のあるお客様は(http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs)を参照してください。
概要
KVLocalは、組込みのOracle NoSQL Databaseであり、大量のデータが必要なアプリケーションに埋め込むことで、そのアプリケーションで複数の大規模なデータセットからのライブ・データを処理および表示できるようになります。KVLocalにより、レプリケートされない、単一ノードのストアが提供されます。
これは、アプリケーションのJVMにおいて独立した子プロセスとして実行され、最小限の管理で済みます。KVLocalは、堅牢なデータベースであり、障害に効率的に対処します。KVLocalの起動と停止にはAPIを使用できます。
KVLocalでは、アプリケーションのクラスパスにkvstore.jarを含め、JVMを起動し、APIをコールしてデータベースを初期化することで、Oracle NoSQL Databaseの単一インスタンスを実行できます。KVLocalには、Javaダイレクト・ドライバAPIを使用してアクセスします。
KVLocalでは、クライアントAPIとKVLocalの間の通信にTCP/IPソケットまたはUnixドメイン・ソケットのどちらかを使用します。KVLocalは、TCP/IPソケットを使用するように構成した場合、デフォルトではセキュア・モードで実行されます。明示的に、非セキュアに実行されるように構成できます。KVLocalは、Unixドメイン・ソケットを使用するように構成した場合は、ネットワーク経由でアクセスできないため本質的にセキュアになります。セキュリティは、通信に使用するソケット・ファイルに対するファイル保護によって異なります。
注意:
Unixドメイン・ソケットを使用する場合は、セキュアなKVLocalと非セキュアなKVLocalが別々にサポートされることはありません。KVLocalストアには、KVLocalストア・コンポーネントの構成、デプロイ、モニターおよび変更に役立つ管理サービスがあります。
注意:
1つのアプリケーション(つまり、1つのJVM)で、1つのKVLocalストアのみを実行できます。
JavaアプリケーションへのKVLocalの埋込み
アプリケーションのCLASSPATHにkvstore.jarファイルがあることを確認してください。kvstore.jarファイルは、Oracle NoSQL Databaseソフトウェアの一部として入手できます。これはOracle Technology Networkからダウンロードできます。
KVLocalConfigオブジェクトの作成
KVLocalConfigクラスのオブジェクトを作成します。このクラスでは、KVLocalで使用される構成パラメータが表されます。KVLocalConfigクラスには、InetBuilderおよびUnixDomainBuilderという2つのビルダーが含まれています。InetBuilderは、TCP/IPソケットを使用してKVLocalConfigインスタンスを構築するビルダーであり、UnixDomainBuilderは、Unixドメイン・ソケットを使用してKVLocalConfigインスタンスを構築するビルダーです。
| パラメータ | 説明 |
|---|---|
| StoreName 設定しない場合は、デフォルトで 例:
|
KVLocalインスタンスの名前。 |
| HostName ( ( 例: |
KVLocalインスタンス用にInetBuilderを使用している場合の、ホストへのアクセスに使用するネットワーク・アドレス。UnixDomainBuilderを使用している場合、このパラメータは設定できません。
|
| Port 設定しない場合は、デフォルトで 例: |
クライアントのAPIとKVLocalインスタンスとの通信に使用するTCP/IPポート。このパラメータは、InetBuilderを使用している場合のみ変更できます。これは、Unixドメイン・ソケットを使用している場合はTCP/IPポートを表しません。ただし、管理CLIに接続する場合は、デフォルト値5000を-portフラグとともに指定する必要があります。
|
| enableSecurity ( ( 例: |
セキュアなKVLocalストアか非セキュアなKVLocalストアかを指定します。UnixDomainBuilderの場合、このパラメータの値は必ずfalseであり、変更はできません。これは、Unixドメイン・ソケットの構成が通信において本質的にセキュアであるためです。
|
| StorageSize 設定しない場合は、デフォルトで 例: 記憶域のサイズを
80 GBに設定するには
|
KVLocalデータベース用に使用可能なディスク領域の最大量(GB)。KVLocalデータベースのディスク使用量がしきい値(5 GBの空き領域を除く)を超えている場合は、十分なデータを削除してしきい値の要件を満たすまで、KVLocalにより、ホスト・システム上のすべての書込み操作が一時停止されます。ストレージ・ディレクトリ・サイズを0に設定した場合、KVLocalでは、5 GBの空きディスク領域を除く使用可能なすべての領域が状況に応じて使用されます。 |
| MemoryMB 設定しない場合は、デフォルトで 例: メモリー・サイズを
85 MBに設定するには
|
埋込みKVLocalデータベースの実行に使用するJavaヒープのメモリー・サイズの量 (MB)。ここでのJavaヒープ・サイズは、アプリケーションを実行しているJVMプロセスではなく、子プロセスのJavaヒープ・サイズを表しています。
注意: ホスト・マシンの使用可能メモリーが、リクエストしたヒープ・サイズでJVMを作成するのに十分な量であることを確認してください。 |
- セキュアなKVLocalの場合
import oracle.kv.KVLocalConfig; /* Create a KVLocalConfig object with TCP sockets */ KVLocalConfig config = new KVLocalConfig.InetBuilder("rootDir") .build(); - 非セキュアなKVLocalの場合
import oracle.kv.KVLocalConfig; /* Create a KVLocalConfig object with port number 6000 and security not enabled */ KVLocalConfig config = new kvlocalConfig.InetBuilder("rootDir") .setPort(6000) .enableSecurity(false) .build();
rootDirとは、kvrootディレクトリがある場所です。これは、Oracle NoSQL Databaseデータが格納されているディレクトリへの絶対パス(/home/kvstore
KVLocalのセキュリティを有効にした場合は、KVLocalを起動すると、kvrootディレクトリの下にセキュリティ・ファイル(user.security)が生成されます。KVストアがすでに存在する場合(つまり、kvrootディレクトリがすでに存在する場合)は、KVLocalにより、既存のkvrootディレクトリにあるセキュリティ・ファイルが使用されてkvstoreが保護されます。
import oracle.kv.KVLocalConfig;
/* Create a KVLocalConfig object with Unix domain sockets */
KVLocalConfig config = new KVLocalConfig.UnixDomainBuilder("rootDir")
.build();rootDirとは、kvrootディレクトリがある場所です。これは、Oracle NoSQL Databaseデータが格納されているディレクトリへの絶対パス(/home/kvstore
Unixドメイン・ソケットを使用している場合は、ソケット・ファイルがkvrootディレクトリの下に作成されます。これらのソケット・ファイルは、サーバー(KVLocal)とクライアント(ユーザー・アプリケーション)との通信に使用されます。たとえば、kvrootディレクトリが/home/kvrootである場合、このようなUnixドメイン・ソケット・ファイルへのフルパスは/home/kvroot/sockets/sock-5000のようになります。
KVLocal起動APIおよび停止APIの呼出し
注意:
1つのアプリケーション(つまり、1つのJVM)で、1つのKVLocalストアのみを管理できます。同じJVMで2つ目のKVLocalをインスタンス化しようとすると、「The KVLocal has already been initialized」という例外がスローされます。| メソッド名 | 説明 |
|---|---|
| start(KVLocalConfig config) | KVLocalインスタンスを起動します。 |
| startExistingStore(String rootDir) | 既存のルート・ディレクトリからKVLocalインスタンスを起動します。 |
| stop() | 実行中のKVLocalインスタンスを停止します。 |
| KVStore getStore() | 実行中のKVLocalインスタンスに対するストア・ハンドルを取得します。
このメソッドの初回コール時に、必要に応じて、新しいストア・ハンドルが作成されます。後続のすべてのコールでは、既存のストア・ハンドルが返されます。既存のストア・ハンドルが 注意: アプリケーションで、ストアへのアクセスが完了したときにKVLocal.closeStore()メソッドを呼び出して、ストア・ハンドルに関連付けられているリソースを解放する必要があります。KVStore.close()メソッドは呼び出さないでください。これを実行すると、ストア・ハンドルに関連付けられているすべてのリソースが解放されず、ストア・ハンドルが機能しなくなります。
|
import oracle.kv.KVLocalConfig;
import oracle.kv.KVLocal;
/* Create a KVLocal object and pass the KVLocal configuration parameters to the object */
KVLocalConfig config = new KVLocalConfig.InetBuilder("rootDir")
.build();
/* Start KVLocal*/
KVLocal local = KVLocal.start(config);
/* Get a handle to kvstore */
KVStore storeHandle = local.getStore();
/* Use existing key/value APIs to write to kvstore */
storeHandle.put(Key,Value);
ValueVersion valueVersion = storeHandle.get(Key.createKey(key));
/* Close kvstore */
KVLocal.closeStore();
/* Stop kvstore */
local.stop();rootDirとは、kvrootディレクトリがある場所です。これは、Oracle NoSQL Databaseデータが格納されているディレクトリへの絶対パス(/home/kvstore
import oracle.kv.KVLocalConfig;
import oracle.kv.KVLocal;
/* Create a KVLocal object and pass the KVLocal configuration parameters to the object */
KVLocalConfig config = new KVLocalConfig.UnixDomainBuilder("rootDir")
.build();
/* Start KVLocal*/
KVLocal local = KVLocal.start(config);
/* Get a handle to kvstore */
KVStore storeHandle = local.getStore();
/* Use existing key/value APIs to write to kvstore */
storeHandle.put(Key,Value);
ValueVersion valueVersion = storeHandle.get(Key.createKey(key));
/* Close kvstore */
KVLocal.closeStore();
/* Stop kvstore */
local.stop();rootDirとは、kvrootディレクトリがある場所です。これは、Oracle NoSQL Databaseデータが格納されているディレクトリへの絶対パス(/home/kvstore
管理CLIの起動
runadminユーティリティでは、管理コマンドライン・インタフェース(CLI)が提供されます。管理クライアントでは、KVLocalインスタンスの実行中に、次のコマンドを使用してKVLocalストアに接続できます。
java -jar <KVHOME>/lib/kvstore.jar runadmin -port 5000 -host localhost
ここでの<KVHOME>は、Oracle NoSQL Databaseパッケージ・ファイルがあるディレクトリを表しています。
注意:
Unixドメイン・ソケットを使用してKVLocalに接続する場合は、unix_domain:KVROOT/sockets/sockという形式でホスト名を指定します。たとえば、KVROOTディレクトリが/disk1/KVROOTである場合は、次のコマンドを実行して管理CLIを起動します。java -jar <KVHOME> /lib/kvstore.jar runadmin -port 5000 -host unix_domain:/disk1/kvroot/sockets/sockKVLocal用のJEパラメータの設定
JEは、KVLocal用のストレージ・エンジンです。KVLocalは、JEのラッパーであり、NoSQLデータベース・クラスタから単一のレプリケーション・ノードをエミュレートします。したがって、KVLocalと、それが単一ノードのNoSQLデータベースであるかのようにやりとりできます。
レプリケーション・ノード(RN)パラメータconfigProperties=<String>を使用してKVLocalインスタンスのJEパラメータを設定できます。これには、基になるBDB JEサブシステムのプロパティ設定が含まれています。形式は、property=value;property=value...です。
show parameters -service nameコマンドを入力します。kv-> show parameters -service rg1-rn1;
...
...
configProperties=je.cleaner.threads 1;
je.rep.insufficientReplicasTimeout 100 ms;
je.env.runEraser true;
je.erase.deletedDatabases true;
je.erase.extinctRecords true;
je.erase.period 6 days;
je.env.runBackup false;
je.backup.schedule 0 8 * * *;
je.backup.copyClass oracle.nosql.objectstorage.backup.BackupObjectStorageCopy;
je.backup.copyConfig /var/lib/andc/config/params/backup.copy.properties;
je.backup.locationClass oracle.nosql.objectstorage.backup.BackupObjectStorageLocation;
je.backup.locationConfig /var/lib/andc/config/params/backup.location.properties;
je.rep.electionsOpenTimeout=2 s;
je.rep.electionsReadTimeout=2 s;
je.rep.feederTimeout=3 s;
je.rep.heartbeatInterval=500;
je.rep.replicaTimeout=3 s;
je.rep.repstreamOpenTimeout=2 s;...
...
JEパラメータを設定または変更するには、管理CLIのplan change-parameters -service <id>コマンドを入力します。
"configProperties=je.cleaner.minUtilization=40;">kv-> plan change-parameters -all-rns -params \
"configProperties=je.cleaner.minUtilization=50;\
je.env.runVerifier=false;">KVLocalのJVMメモリー・パラメータの変更
javaRnParamsOverride=<String>パラメータを使用して、KVLocalのJVMメモリー設定を変更できます。これには、子プロセスの起動時にコマンドラインに追加する文字列を指定します。このパラメータは、他のRNパラメータを使用して指定できないその他のJVMプロパティを指定するために用意されています。その文字列がJVMコマンドライン用の有効な一連のトークンでない場合は、レプリケーション・ノード・プロセスの起動に失敗します。
show parameters -service nameコマンドを入力します。kv-> show parameters -service rg1-rn1;plan change-parametersコマンドを使用します。kv-> plan change-parameters -wait -all-admins -params \
javaRnParamsOverride="-Xms2048m -Xmx2048m-XX:ParallelGCThreads=4"KVLocalを使用したSQLシェルの実行
SQLシェルをKVLocalインスタンスに接続するには、次のコマンドを実行します。
java -jar <KVHOME>/lib/sql.jar -helper-hosts <host:port> -store <storeName>
ここでの<KVHOME>は、Oracle NoSQL Databaseパッケージ・ファイルがあるディレクトリを表しています。
注意:
Unixドメイン・ソケットを使用してKVLocalに接続する場合は、unix_domain:KVROOT/sockets/sockという形式でホスト名を指定します。たとえば、KVROOTディレクトリが/disk1/KVROOTである場合は、次のコマンドを実行して管理CLIを起動します。java -jar <KVHOME>/lib/kvstore.jar -helper-hosts unix_domain:/disk1/kvroot/sockets/sock:5000 -store kvstorejava -jar <KVHOME>/lib/sql.jar <command>を介してアクセスするユーティリティ・コマンドすべてを示すリストについては、シェル・ユーティリティ・コマンドを参照してください。
KVLocalストアのバックアップ
スナップショットを使用すると、KVLocalストアのバックアップを作成してそのデータと構成をコピーできます。後で、スナップショットからKVLocalストアのデータおよび構成をリストアできます。
| メソッド名 | 説明 | パラメータ | 戻り値 |
|---|---|---|---|
| String createSnapshot(String name) | 指定された名前を接尾辞として使用して、新しいスナップショットを作成します。
このメソッドでは、リストア・アクティビティに必要なファイルを含め、KVLocalストアのデータファイルおよび構成ファイルがバックアップされます。スナップショット・データは、kvrootディレクトリ内のディレクトリに格納されます。 注意: スナップショットを作成すると、ホスト・マシンのサブディレクトリにそれが格納されます。ただし、これらのスナップショットは、個別のストレージにコピーされないかぎり、永続バックアップにはなりません。ユーザーは、データの安全性を確保するために、各スナップショットを別の場所(できれば別のマシン上)にコピーする必要があります。 |
name: スナップショット名に使用する接尾辞を指定します。 | 生成されたスナップショット名。生成されたスナップショット名には、日時接頭辞が付いています。date-time接頭辞は、YYMMDD形式の6桁の年、月、日の値と、HHMMSS形式の6桁の時間、分、秒のタイムスタンプで構成されます。その日付と時間の値はダッシュ(-)で区切られており、その後にダッシュ(-)が付けられてから、入力したスナップショット名が示されています。
例: nameパラメータの値として |
| KVLocal restoreFromSnapshot(String rootDir, String name) | スナップショットからストアをリストアします。
このメソッドでは、 |
rootDir: ストアのルート・ディレクトリを指定します。
name: スナップショットの名前を指定します(日付と時間を含む、createSnapshot APIで生成された名前)。 |
KVLocalのインスタンス。 |
| void removeSnapshot(String name) | スナップショットを削除します。
ヒント: 格納場所がなくならないように、古いスナップショットを定期的に削除する必要があります。 |
name: スナップショットの完全名を指定します(日付と時間を含む、createSnapshot APIで生成された名前)。 | |
| String[] listSnapshots() | すべてのスナップショットの名前をリストします。 | スナップショットの名前の配列。 |
import oracle.kv.KVLocalConfig;
import oracle.kv.KVLocal;
/* Start the KVLocal */
KVLocalConfig config = new KVLocalConfig.InetBuilder("/home/kvstore").build();
KVLocal local = KVLocal.start(config);
/* Create a Snapshot */
String snapshotName = local.createSnapshot("sp1");
/* List all Snapshots */
String snapshotName = local.listSnapshots();
/* Stop the KVLocal */
local.stop();
/* Restore from a Snapshot */
local = KVLocal.restoreFromSnapshot(rootDir,snapshotName);import oracle.kv.KVLocalConfig;
import oracle.kv.KVLocal;
/* Start the KVLocal */
KVLocalConfig config = new KVLocalConfig.UnixDomainBuilder("/home/kvstore").build();
KVLocal local = KVLocal.start(config);
/* Create a Snapshot */
String snapshotName = local.createSnapshot("sp1");
/* List all Snapshots */
String snapshotName = local.listSnapshots();
/* Stop the KVLocal */
local.stop();
/* Restore from a Snapshot */
local = KVLocal.restoreFromSnapshot(rootDir,snapshotName);KVLocal診断ユーティリティ
アプリケーションで次のKVLocal APIを呼び出してKVLocal構成エラーを捕捉できます。これらのAPIでは、重要かつ有意義な情報がJSON形式で返されます。この情報を基に、問題を特定または診断できます。
| メソッド名 | 説明 | パラメータ | 戻り値 |
|---|---|---|---|
| String verifyConfiguration(boolean verbose) | コンポーネントを反復処理し、その状態を管理サービスで保持されている情報と照合することで、ストア構成を検証します。
このメソッドでは、埋込みNoSQLデータベース・インスタンスが安定した正常な状態で実行されているかどうかが確認されます。構成エラーがある場合は、違反または警告が出力で示されます。violationsは問題を引き起こす可能性があり、調査が必要です。 |
verbose: 出力に詳細出力を含めるかどうかを指定します。falseの場合、出力には違反と警告のみが含まれます。 | 検証済の構成はJSON形式になります。 |
| String verifyData() | ストアのデータの整合性を検証します。このメソッドでは、ディスク上のログ・レコードの整合性、およびメモリー内のBツリーの整合性が検証されるため、比較的時間がかかります。
KVLocalインスタンスにBツリーまたはログの永続的な破損がある場合、サービスが停止され、JE環境が無効化されます。JEはその後、7fffffff.jdbというファイルを作成し、他の.jdbファイルが存在する環境内のあらゆる場所にそれを配置します。永続的なデータ破損からのリカバリには、手動での管理操作が必要です。詳細は、データ破損からのリカバリを参照してください。 KVLocalインスタンスに一時的な破損がある場合、サービスは自動的に終了されます。メモリーの破損が原因で、一時的な破損が起こる可能性があります。一時的な破損からのリカバリには、埋込みNoSQLデータベース・インスタンスの再起動が必要になります。 |
検証済のデータはJSON形式になります。一時的な破損が見つからない場合は、結果で「No Btree Corruptions」および「No Log File Corruptions」と示されます。 |
診断ユーティリティからのJSON出力の例
verifyConfiguration APIからの詳細なJSON出力の例
{
"topology": {
"storeName": "kvstore",
"sequenceNumber": 5,
"numPartitions": 1,
"numStorageNodes": 1,
"time": 1629830958933,
"version": "21.3.0"
},
"storewideLogName": "localhost:/home/hongyang/projects/kvlocal/kvstore/build/kvsandbox/diagnosticTool/kvstore/log/kvstore_{0..N}.log",
"shardStatus": {
"healthy": 1,
"writable-degraded": 0,
"read-only": 0,
"offline": 0,
"total": 1
},
"adminStatus": "healthy",
"zoneStatus": [
{
"resourceId": "zn1",
"name": "KVLite",
"type": "PRIMARY",
"allowArbiters": false,
"masterAffinity": false,
"rnSummaryStatus": {
"online": 1,
"offline": 0,
"read-only": 0,
"hasReplicas": false
}
}
],
"snStatus": [
{
"resourceId": "sn1",
"hostname": "localhost",
"registryPort": 5000,
"zone": {
"resourceId": "zn1",
"name": "KVLite",
"type": "PRIMARY",
"allowArbiters": false,
"masterAffinity": false
},
"serviceStatus": "RUNNING",
"version": "21.3.0 2021-08-24 18:48:25 UTC Build id: 008f726d548c+ Edition: Enterprise",
"isMasterBalanced": true,
"serviceStartTime": "2021-08-24 18:49:09 UTC",
"adminStatus": {
"resourceId": "admin1",
"status": "RUNNING",
"state": "MASTER",
"authoritativeMaster": true,
"serviceStartTime": "2021-08-24 18:49:11 UTC",
"stateChangeTime": "2021-08-24 18:49:11 UTC",
"availableStorageSize": "2 GB"
},
"rnStatus": [
{
"resourceId": "rg1-rn1",
"status": "RUNNING",
"requestsEnabled": "ALL",
"state": "MASTER",
"authoritativeMaster": true,
"expectedStatus": "RUNNING",
"sequenceNumber": 36,
"haPort": 5003,
"storageType": "HD",
"availableStorageSize": "9 GB",
"serviceStartTime": "2021-08-24 18:49:12 UTC",
"stateChangeTime": "2021-08-24 18:49:12 UTC"
}
],
"anStatus": []
}
],
"violations": [],
"warnings": [],
"operation": "verify configuration -json -silent",
"return_code": 5000,
"description": "Operation ends successfully"
}verifyData APIからのJSON出力の例
{
"Verify Report": {
"rg1-rn1": {
"Btree Verify":"No Btree Corruptions",
"Log File Verify":"No Log File Corruptions"
}
}
}KVLocalに関するFAQ
既存のストアの構成パラメータがKVLocalのstart()パラメータと異なる場合はどうなりますか。
既存のストアの構成パラメータがKVLocalConfigパラメータと異なる場合は、KVLocal.start()によって「parameter not consistent.」という例外がスローされます。ディレクトリに記録されている内容と一致するようにKVLocalConfigパラメータを更新するか、startExistingStore() APIをコールすることができます。
KVLocalのRepNodeサービスは停止後に自動的に再起動されますか。
これは、サービス停止がユーザーによってリクエストされたかどうかで異なります。
RepNodeサービスは、クラッシュすると自動的に再起動されます。ただし、短期間のクラッシュ回数が多い場合は、自動的には再起動されません。その場合は、問題を診断し、サービスを手動で再起動する必要があります。
ユーザーがKVLocal.stop() APIをコールしたかアプリケーションを終了したことでRepNodeサービスが停止された場合は、KVLocal.start() APIをコールすることで手動でRepNodeサービスを再起動する必要があります。
既存のJavaダイレクト・ドライバAPIはサポートされていますか。
KVLocalでは、Javaダイレクト・ドライバAPIはサポートされています。
Oracle NoSQL Database KVLocalクイック・スタート, リリース22.2
F75005-01
2022年8月
Copyright © 2022, Oracle and/or its affiliates.