matlab-write-database

MATLAB Database Export Architect

Use when writing data to relational databases, executing SQL statements, managing transactions, running stored procedures, or using SQL prepared statements. Covers all Database Toolbox operations that modify the database.

When to Use This Skill

Writing/inserting MATLAB data into a database table
Updating existing rows in a database table
Deleting data from a database
Executing arbitrary SQL statements (DDL, DML)
Running stored procedures or custom database functions
Managing transactions (commit/rollback)
Using SQL prepared statements for parameterized queries
Creating or altering database table structures
User mentions keywords: write, export, insert, sqlwrite, sqlupdate, update, delete, execute, stored procedure, runstoredprocedure, transaction, commit, rollback, DDL, CREATE TABLE, ALTER, prepared statement, bulk insert

When NOT to Use

Reading/importing data from a database — use sqlread/fetch with RowFilter and databaseImportOptions
Object-oriented writes with class mapping — use ORM (ormwrite/ormupdate with Mappable classes)
MongoDB, Cassandra, or Neo4j writes — these have their own document/graph-specific write interfaces
Large data that doesn't fit in memory — use DatabaseDatastore + chunked processing for reads, or chunked sqlwrite loops for writes

Critical Rules

Credential Security

NEVER hardcode passwords or credentials in generated code.
ALWAYS use setSecret / getSecret (R2024a+) for credential storage.

Database Connection

ALWAYS establish and verify a connection before any export operation. Check isopen(conn) after connecting.
ALWAYS close connections with close(conn) when done.

Transaction Safety

ALWAYS set AutoCommit to off when using commit / rollback for transaction control.
ALWAYS wrap multi-statement operations in a transaction when atomicity is required.
ALWAYS use rollback in error-handling blocks to undo partial changes on failure.

Destructive Operations

ALWAYS ask the user for explicit confirmation before executing any SQL that could irreversibly destroy or alter data. This includes: DROP, TRUNCATE, DELETE, and ALTER statements that remove columns or modify constraints.
NEVER execute a destructive SQL statement via execute() without first presenting the exact SQL to the user and receiving explicit approval.
The confirmation prompt must include the exact SQL statement or a clear description of what will be affected (e.g., "This will drop table employees. All data will be permanently lost. Proceed?").

Decision Framework

Goal	Function	When to Use
Write MATLAB table to DB table	`sqlwrite`	Bulk insert of tabular data; creates table if needed
Modify existing rows	`sqlupdate`	Update specific rows matching a filter (R2023a+)
Run DDL or raw SQL	`execute`	CREATE TABLE, DROP, ALTER, simple CALL statements
Repeated parameterized inserts	`databasePreparedStatement`	High-frequency inserts with varying values
Stored procedure with typed outputs	`runstoredprocedure`	Need typed output arguments from stored procedure (JDBC/ODBC only)
Simple stored procedure call	`execute` with CALL	No typed output args needed; result sets returned

execute vs runstoredprocedure: Use runstoredprocedure when you need typed output arguments. Use execute with CALL for simple invocation or when you only need result sets.

Function Reference

Function	Purpose	Since
`sqlwrite`	Insert MATLAB table into database table	R2018a
`sqlupdate`	Update rows in database table matching a filter	R2023a
`update`	Replace data in database table (legacy)	R2006a
`execute`	Execute any SQL statement (DDL, DML, stored procs)	R2018b
`runstoredprocedure`	Call stored procedure with input/output arguments (JDBC/ODBC only)	R2006b
`commit`	Make database changes permanent	R2006a
`rollback`	Undo database changes	R2006a
`databasePreparedStatement`	Create SQL prepared statement (JDBC only)	R2019b
`bindParamValues`	Bind values to prepared statement parameters	R2019b

Edge Cases

NULL values: MATLAB missing, NaN, or empty "" map to SQL NULL in sqlwrite
Type mismatches: Ensure MATLAB column types match DB column types (e.g., int32 not double for INTEGER columns)
Auto-increment PKs: Omit the auto-increment column from the MATLAB table before calling sqlwrite

Core Concepts

See knowledge cards for detailed usage and examples:

Insert and update data: reference/cards/sqlwrite-sqlupdate.md
Execute SQL and stored procedures: reference/cards/execute-storedproc.md
Transaction management: reference/cards/transactions.md
Prepared statements (JDBC only): reference/cards/prepared-statements.md

Complete Examples

See knowledge cards for complete examples:

Insert computed results: reference/cards/sqlwrite-sqlupdate.md
Atomic multi-table update with transaction: reference/cards/transactions.md
Parameterized insert with prepared statement: reference/cards/prepared-statements.md

Common Mistakes

% 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);

Best Practices

ALWAYS use sqlwrite for inserting MATLAB tables — it handles type mapping automatically.
ALWAYS prefer sqlupdate (R2023a+) over raw SQL UPDATE — it uses rowfilter for type-safe filtering.
ALWAYS close connections with close(conn) when done.
Prefer transactions (commit/rollback) for multi-statement operations requiring atomicity.
For very large inserts, chunk the MATLAB table manually in a loop to avoid memory issues.
Use prepared statements for repeated parameterized operations — they improve performance and prevent SQL injection.
Prepared statements are JDBC only — not available for ODBC or native connections.
runstoredprocedure is JDBC/ODBC only (database() connections) — not available for native connections (sqlite, postgresql, mysql, duckdb). Use execute with a CALL statement instead.
ALWAYS confirm destructive intent with the user before running DROP, TRUNCATE, DELETE, or column-dropping ALTER — present the SQL and wait for explicit approval, even if the user's request implied the operation.

Common Patterns

Pattern 1: Insert-Verify

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

Pattern 2: Transaction-Protected Update

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';

Pattern 3: DDL-then-Insert

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

Checklist

Before finalizing, verify:

Database connection established and verified (isopen(conn))
No hardcoded credentials — uses getSecret or placeholders
sqlwrite used for table inserts (not raw SQL INSERT for MATLAB data)
Transactions used for multi-statement atomic operations
AutoCommit restored to 'on' after transaction blocks
Prepared statements closed with close(pstmt)
Connection closed with close(conn) at the end
Destructive SQL (DROP, TRUNCATE, DELETE, ALTER) confirmed with user before execution

Troubleshooting

Issue: sqlwrite fails with "table already exists"

Solution: sqlwrite creates the table if it doesn't exist but errors if the table exists with a different schema. Use sqlwrite to append to an existing table — column names and types must match.

Issue: sqlupdate not recognized

Solution: sqlupdate requires R2023a or later. For older releases, use update or execute a raw SQL UPDATE statement with execute.

Issue: sqlupdate errors with "Number of filters must match the height of the table"

Solution: For multi-row updates, pass a cell array of RowFilter objects (one filter per data row). A single RowFilter only works with a 1-row data table (broadcasts to all matching rows). Do not pass a single filter that matches N rows with an N-row data table — this errors.

Issue: Transaction changes not visible after commit

Solution: Verify AutoCommit was set to 'off' before the transaction. If AutoCommit is 'on', each statement auto-commits immediately.

Issue: Prepared statement errors with "parameter index out of range"

Solution: Verify the parameter indices in bindParamValues match the number of ? placeholders in the SQL statement. Indices are 1-based.

Issue: Bulk insert runs out of memory

Solution: sqlwrite has no BatchSize parameter. Chunk the MATLAB table manually in a loop — split data into slices of 5,000–50,000 rows and call sqlwrite on each slice.

Issue: runstoredprocedure fails with "wrong number of arguments"

Solution: Verify the input argument count matches the stored procedure definition. For JDBC connections, output types must use java.sql.Types constants.