11.2 共通の連携概念
ドライバーや言語に関係なく適用される、接続、バインディング、トランザクション、大量入力、エラー処理の 原則を説明します。SDK別の関数名と完全なコードは、本章のSDK別ページを参照してください。
接続文字列と認証
接続にはホスト、ネイティブポート、ユーザー、認証情報を使用します。デフォルトポートは5656ですが、
デプロイ環境のmachbase.conf設定を確認してください。
| 項目 | 確認事項 |
|---|---|
| ホスト・ポート | アプリケーションの実行場所からTCP接続できるか |
| ユーザー | 対象データベースとテーブルに必要な最小限の権限 |
| パスワード | 環境変数またはシークレット管理システムで注入 |
| データベース | SDKが初期データベースの選択をサポートするか |
| タイムアウト | 接続・コマンド・読み取り制限をワークロードに合わせて設定 |
| タイムゾーン | SDKとサーバーがサポートするオプション名と適用範囲 |
例のSYS/MANAGERはローカル検証用です。本番アプリケーションには専用アカウントを作成し、
ソース、コマンド履歴、ログにパスワードを記録しません。
AUTH KEYは、パスワードの代わりに秘密鍵でチャレンジに署名する方式です。鍵形式、ファイル権限、 SDK別オプションはAUTH KEY認証と 該当ドライバーのドキュメントを合わせて確認します。
接続プールを使用する場合は、返却した接続の現在のデータベース、セッション設定、開いた文が 次のリクエストに影響しないよう、初期化動作を検証します。
タイムゾーンと時間値
MachbaseのDATETIMEはナノ秒精度をサポートします。アプリケーションでは時間値の意味と表現を
分けて管理します。
- 収集時刻の基準タイムゾーン（UTCまたは業務地域）を明示します。
- 文字列をバインドする際は、形式とタイムゾーンをともに固定します。
- エポック値を渡す際は、SDKが要求する単位が秒、ミリ秒、マイクロ秒、ナノ秒のどれかを確認します。
- 検索文字列のタイムゾーンは、接続オプションや
TO_CHAR()など実際の使用経路で往復テストします。 - 業務規則で
NOWとSYSDATEを混用せず、必要な意味をSQLリファレンスで確認します。
文字列の往復検証では、同じ接続で入力値、検索値、タイムゾーン変更後の検索値を比較します。 関数の詳細はSQL関数を参照してください。
プリペアドステートメント
プリペアドステートメント（prepared statement）はSQLの構造と値を分離し、同じSQLを繰り返し 実行する際に使用します。
INSERT INTO sensor_data VALUES (?, ?, ?)
SELECT value FROM sensor_data WHERE name = ? AND time >= ?文を準備した接続と現在のデータベースが変わっていないか確認し、使用後に閉じます。 文キャッシュを提供するSDKでは、キャッシュ範囲、項目の削除ポリシー、データベース切り替え時の 初期化動作を確認します。
CTE、LIMITなど構文の位置によってはパラメータープレースホルダーが許可されない場合があります。 構文エラーが発生したら、値を文字列として連結する前に Named Bind Parameterと 該当SDKのプレースホルダーのサポート範囲を確認します。
パラメーターバインディング
| 値の種類 | 推奨方式 |
|---|---|
| 整数・実数 | 言語の固定幅型とSQL型の範囲を合わせる |
| 文字列 | エンコーディングと最大長を確認 |
| DATETIME | SDKの時間オブジェクトまたは明示されたエポック単位を使用 |
| NULL | 言語別のNULL表現とSQL型をともに指定 |
| DECIMAL | 文字列変換よりSDKの正確な固定小数点型を優先 |
| バイナリ・IP | SDKが要求するバイト配列または専用型を使用 |
位置指定のプレースホルダー?は出現順に値をバインドします。名前付きプレースホルダー:nameは
対応するサーバーとSDKでのみ使用し、同名の繰り返し処理規則を確認します。識別子やSQLキーワードは
値パラメーターとしてバインドできないため、許可リストで検証してからSQLを組み立てます。
DMLの影響行数
INSERT、UPDATE、DELETEの後はSDKが返す影響行数を確認します。成功応答だけで業務対象が
実際に変更されたと考えないでください。
- 単一行の変更では期待値が1か確認します。
- 0件の場合、条件に一致する行がないか、すでに同じ変更が反映されているか確認します。
- 権限不足や非サポートのDMLでは、影響行数とは別にエラーコードと例外を確認します。
- 一括変更では、実行前に同じ条件の
COUNT(*)で範囲を確認します。 - AppendではSQLの影響行数の代わりに、close・サーバー処理応答の成功件数と失敗件数を確認します。
トランザクション
明示的なBEGIN、COMMIT、ROLLBACKはTRANSACTIONテーブルのリレーショナルDMLで使用します。
LOG・TAGのAppendを同じロールバック単位とは考えないでください。
- 使用するSDKがトランザクションAPIを提供するか確認します。
- 提供しない場合は、サポートされるSQL制御文を同じ接続で実行します。
- エラー時にロールバックして接続を再利用できるか確認します。
- 接続プールへの返却前に未完了のトランザクションが残らないようにします。
- 複数のテーブルタイプを混在させる作業では、各文のコミット範囲を事前に検証します。
完全なSQL例は TRANSACTIONテーブルのトランザクションを参照してください。
Append APIとバッチ
入力方式の選択と結果確認項目はデータの入力とエクスポート、 クライアント・テーブルタイプ別のAppendの利用条件は SDK Appendサポート表で扱います。 Append接続は通常のクエリ接続と分け、フラッシュ・クローズと失敗行を確認します。
エラー処理と再試行
エラーは、接続、認証・権限、SQL・スキーマ、データ、リソース不足に分類します。
- 接続切断と一時的なタイムアウトだけを、回数を制限し待機時間を設けて再試行します。
- 認証失敗、権限不足、構文エラー、型エラーは、修正前に自動再試行しません。
- 再試行前に文・カーソル・Appendハンドルと接続を解放します。
- INSERTの再試行では業務キーや重複処理ポリシーで冪等性を確保します。
- サーバーのエラーコードとメッセージは記録し、認証情報と機密の生データは除去します。
- 接続プール内でエラーになった接続は、有効性検査後に返却するか破棄します。
運用エラーの分類と診断手順はトラブルシューティングを参照してください。