matlab-write-database

MATLAB データベースエクスポートアーキテクト

リレーショナルデータベースへのデータ書き込み、SQL ステートメントの実行、トランザクションの管理、ストアドプロシージャの実行、SQL プリペアドステートメントの使用時に利用します。データベースを変更する Database Toolbox のすべての操作を対象としています。

このスキルを使用する場合

• MATLAB データをデータベーステーブルに書き込む／挿入する場合
• データベーステーブルの既存の行を更新する場合
• データベースからデータを削除する場合
• 任意の SQL ステートメント（DDL、DML）を実行する場合
• ストアドプロシージャやカスタムデータベース関数を実行する場合
• トランザクション（コミット／ロールバック）を管理する場合
• パラメーター化クエリに SQL プリペアドステートメントを使用する場合
• データベーステーブルの構造を作成または変更する場合
• ユーザーが次のキーワードに言及した場合：write、export、insert、sqlwrite、sqlupdate、update、delete、execute、stored procedure、runstoredprocedure、transaction、commit、rollback、DDL、CREATE TABLE、ALTER、prepared statement、bulk insert

このスキルを使用しない場合

• データベースからデータを読み取る／インポートする場合 — RowFilter および databaseImportOptions とともに sqlread／fetch を使用します
• クラスマッピングを使用したオブジェクト指向の書き込み — ORM（Mappable クラスとともに ormwrite／ormupdate を使用）を使用します
• MongoDB、Cassandra、Neo4j への書き込み — それぞれに固有のドキュメント／グラフ向け書き込みインターフェイスがあります
• メモリに収まらない大量のデータ — 読み取りには DatabaseDatastore とチャンク単位の処理を、書き込みにはチャンク単位の sqlwrite ループを使用します

重要なルール

認証情報のセキュリティ

• 決して生成コードにパスワードや認証情報をハードコードしないでください。
• 必ず認証情報の保存には setSecret／getSecret（R2024a 以降）を使用してください。

データベース接続

• 必ずエクスポート操作の前に接続を確立し、検証してください。接続後に isopen(conn) を確認します。
• 必ず処理が完了したら close(conn) で接続を閉じてください。

トランザクションの安全性

• 必ずトランザクション制御に commit／rollback を使用する場合は、AutoCommit を off に設定してください。
• 必ず原子性が必要な複数ステートメントの操作は、トランザクションで囲んでください。
• 必ずエラー処理ブロックで rollback を使用し、失敗時に部分的な変更を取り消してください。

破壊的な操作

• 必ずデータを不可逆に破壊または変更する可能性のある SQL を実行する前に、ユーザーから明示的な確認を得てください。これには、DROP、TRUNCATE、DELETE、および列を削除したり制約を変更したりする ALTER ステートメントが含まれます。
• 必ず正確な SQL をユーザーに提示して明示的な承認を得る前に、execute() で破壊的な SQL ステートメントを実行しないでください。
• 確認プロンプトには、正確な SQL ステートメント、または影響を受ける内容の明確な説明を含めてください（例：「テーブル employees を削除します。すべてのデータが完全に失われます。続行しますか？」）。

判断の指針

目的	関数	使用する場合
MATLAB テーブルを DB テーブルに書き込む	sqlwrite	表形式データの一括挿入。必要に応じてテーブルを作成します
既存の行を変更する	sqlupdate	フィルターに一致する特定の行を更新します（R2023a 以降）
DDL または生の SQL を実行する	execute	CREATE TABLE、DROP、ALTER、単純な CALL ステートメント
パラメーター化された挿入を繰り返し実行する	databasePreparedStatement	値を変えながら高頻度で挿入する場合
型付き出力を持つストアドプロシージャ	runstoredprocedure	ストアドプロシージャから型付きの出力引数が必要な場合（JDBC／ODBC のみ）
単純なストアドプロシージャ呼び出し	CALL を指定した execute	型付き出力引数が不要で、結果セットが返される場合

execute と runstoredprocedure の比較： 型付きの出力引数が必要な場合は runstoredprocedure を使用します。単純な呼び出しの場合や、結果セットだけが必要な場合は、CALL を指定した execute を使用します。

関数リファレンス

関数	目的	対応バージョン
sqlwrite	MATLAB のテーブルをデータベースのテーブルに挿入します	R2018a
sqlupdate	フィルターに一致するデータベースのテーブルの行を更新します	R2023a
update	データベースのテーブルのデータを置き換えます（レガシー）	R2006a
execute	任意の SQL 文（DDL、DML、ストアドプロシージャ）を実行します	R2018b
runstoredprocedure	入出力引数を指定してストアドプロシージャを呼び出します（JDBC/ODBC のみ）	R2006b
commit	データベースの変更を確定します	R2006a
rollback	データベースの変更を取り消します	R2006a
databasePreparedStatement	SQL のプリペアドステートメントを作成します（JDBC のみ）	R2019b
bindParamValues	プリペアドステートメントのパラメーターに値をバインドします	R2019b

エッジケース

• NULL 値： MATLAB の missing、NaN、または空の "" は、sqlwrite で SQL の NULL にマッピングされます
• 型の不一致： MATLAB の列の型が DB の列の型と一致するようにしてください（例：INTEGER 列には double ではなく int32 を使用します）
• 自動インクリメントの主キー： sqlwrite を呼び出す前に、MATLAB のテーブルから自動インクリメント列を除外します

中核となる概念

詳しい使い方と例については、ナレッジカードを参照してください：

• データの挿入と更新：reference/cards/sqlwrite-sqlupdate.md
• SQL とストアドプロシージャの実行：reference/cards/execute-storedproc.md
• トランザクション管理：reference/cards/transactions.md
• プリペアドステートメント（JDBC のみ）：reference/cards/prepared-statements.md

完全な例

完全な例については、ナレッジカードを参照してください：

• 計算結果の挿入：reference/cards/sqlwrite-sqlupdate.md
• トランザクションを使用した複数テーブルのアトミックな更新：reference/cards/transactions.md
• プリペアドステートメントを使用したパラメーター化された挿入：reference/cards/prepared-statements.md

よくある間違い

% INCORRECT — inserting rows one at a time in a loop (very slow)
for i = 1:height(data)
    sqlwrite(conn, "orders", data(i,:));
end

% CORRECT — batch insert the entire table at once
sqlwrite(conn, "orders", data);

% INCORRECT — no transaction control for multi-table writes
sqlwrite(conn, "orders", orderData);
sqlwrite(conn, "order_items", itemData);  % if this fails, orders are orphaned

% CORRECT — use transaction control for atomic multi-table writes
conn.AutoCommit = 'off';
try
    sqlwrite(conn, "orders", orderData);
    sqlwrite(conn, "order_items", itemData);
    commit(conn);
catch ME
    rollback(conn);
    conn.AutoCommit = 'on'; %#ok<NASGU> restore before rethrowing
    rethrow(ME);
end
conn.AutoCommit = 'on';

% INCORRECT — including auto-increment column in sqlwrite
data = table(1, "Widget", 9.99, VariableNames=["ID", "Name", "Price"]);
sqlwrite(conn, "products", data);  % Error if ID is auto-increment

% CORRECT — omit auto-increment column
data = table("Widget", 9.99, VariableNames=["Name", "Price"]);
sqlwrite(conn, "products", data);

% INCORRECT — single filter with multi-row data table
rf = rowfilter("Category");
filter = rf.Category == "Widgets";  % matches 2 rows
data = table([8.99; 12.99], VariableNames="Price");  % 2 rows
sqlupdate(conn, "products", data, filter);  % Error: filters must match table height

% CORRECT — cell array of filters for multi-row update
rf = rowfilter("ProductID");
filters = {rf.ProductID == 1; rf.ProductID == 2};
data = table([8.99; 12.99], VariableNames="Price");
sqlupdate(conn, "products", data, filters);

ベストプラクティス

• MATLAB のテーブルを挿入する場合は、必ず sqlwrite を使用してください。型のマッピングが自動的に処理されます。
• 生の SQL UPDATE よりも 必ず sqlupdate（R2023a 以降）を優先してください。型安全なフィルタリングに rowfilter を使用します。
• 作業が終わったら、必ず close(conn) で接続を閉じてください。
• アトミック性が必要な複数文の操作には、トランザクション（commit/rollback）を優先してください。
• 非常に大規模な挿入では、メモリの問題を避けるため、MATLAB のテーブルをループ内で手動で分割してください。
• 繰り返し行うパラメーター化操作には、プリペアドステートメントを使用してください。パフォーマンスが向上し、SQL インジェクションを防止できます。
• プリペアドステートメントは JDBC のみで利用できます。ODBC 接続やネイティブ接続では使用できません。
• runstoredprocedure は JDBC/ODBC のみ（database() 接続）で利用でき、ネイティブ接続（sqlite、postgresql、mysql、duckdb）では使用できません。代わりに CALL 文を指定した execute を使用してください。
• DROP、TRUNCATE、DELETE、または列を削除する ALTER を実行する前に、必ずユーザーに破壊的操作を行う意図があるか確認してください。ユーザーの依頼に操作が示唆されている場合でも、SQL を提示し、明示的な承認を待ってください。

よくあるパターン

パターン 1：挿入して検証

sqlwrite(conn, "myTable", data);
result = sqlread(conn, "myTable");
disp("Rows after insert: " + height(result));

パターン 2：トランザクションで保護した更新

conn.AutoCommit = 'off';
try
    execute(conn, sqlStatement);
    commit(conn);
catch e
    rollback(conn);
    conn.AutoCommit = 'on'; %#ok<NASGU> restore before rethrowing
    rethrow(e);
end
conn.AutoCommit = 'on';

パターン 3：DDL の後に挿入

execute(conn, "CREATE TABLE IF NOT EXISTS results (ID INT, Value DOUBLE)");
sqlwrite(conn, "results", data);

チェックリスト

完了前に、次の項目を確認してください：

• データベース接続が確立され、検証されている（isopen(conn)）
• 認証情報がハードコードされていない（getSecret またはプレースホルダーを使用）
• テーブルへの挿入に sqlwrite を使用している（MATLAB データに生の SQL INSERT を使用していない）
• 複数文のアトミックな操作にトランザクションを使用している
• トランザクションブロックの後に AutoCommit が 'on' に戻されている
• プリペアドステートメントが close(pstmt) で閉じられている
• 最後に接続が close(conn) で閉じられている
• 破壊的な SQL（DROP、TRUNCATE、DELETE、ALTER）の実行前に、ユーザーの承認を得ている

トラブルシューティング

問題：sqlwrite が「table already exists」というエラーで失敗する

• 解決策：sqlwrite はテーブルが存在しない場合は作成しますが、テーブルが異なるスキーマで存在する場合はエラーになります。既存のテーブルに追記するには sqlwrite を使用します。列名と型が一致している必要があります。

問題：sqlupdate が認識されない

• 解決策：sqlupdate を使用するには R2023a 以降が必要です。それより古いリリースでは、update を使用するか、execute で生の SQL UPDATE ステートメントを実行してください。

問題：「Number of filters must match the height of the table」というエラーが sqlupdate で発生する

• 解決策：複数行を更新する場合は、RowFilter オブジェクトのセル配列（データの各行につき 1 つのフィルター）を渡してください。単一の RowFilter は、1 行のデータテーブルでのみ機能します（条件に一致するすべての行に適用されます）。N 行のデータテーブルに、N 行に一致する単一のフィルターを渡さないでください。エラーになります。

問題：commit 後にトランザクションの変更が反映されない

• 解決策：トランザクションの前に AutoCommit が 'off' に設定されていたことを確認してください。AutoCommit が 'on' の場合、各ステートメントはただちに自動コミットされます。

問題：「parameter index out of range」というエラーがプリペアドステートメントで発生する

• 解決策：bindParamValues のパラメーターインデックスが、SQL ステートメント内の ? プレースホルダーの数と一致していることを確認してください。インデックスは 1 から始まります。

問題：一括挿入でメモリ不足になる

• 解決策：sqlwrite には BatchSize パラメーターがありません。ループ内で MATLAB テーブルを手動で分割してください。data を 5,000～50,000 行のスライスに分割し、各スライスに対して sqlwrite を呼び出します。

問題：「wrong number of arguments」というエラーで runstoredprocedure が失敗する

• 解決策：入力引数の数がストアドプロシージャの定義と一致していることを確認してください。JDBC 接続では、出力型に java.sql.Types 定数を使用する必要があります。

---

Copyright 2026 The MathWorks, Inc.

---