Migration Guide: v0.4.2 to v0.5.0
v0.5.0 opens a v0.4.2 database without any manual step. The storage format moves forward on its own as the database runs, and there is no way back to v0.4.2 afterwards.
Most of the work an upgrade asks for is in SQL. v0.4.2 answered many statements it should have refused, often with a NULL, a missing row or the wrong column, and v0.5.0 refuses them with an error that names the problem. A smaller set of queries returns a different, correct answer. This guide lists what to look for, grouped so you can search your application’s queries for each pattern.
Before You Upgrade
- Back up the database directory (or run
PRAGMA SNAPSHOT). Once v0.5.0 has written a manifest, v0.4.2 refuses to open the database. - Run your test suite against v0.5.0 before switching production. Most changes surface as errors at prepare or run time, so a test run finds them.
- Check for a column named
_rowid_. It is now a reserved name (see Storage and Files). - Check for TIMESTAMP values before 1677-09-21 or after 2262-04-11 and for TIME values written by v0.4.2 (see Dates, Times and Intervals).
- Rust embedders that install their own global allocator need
default-features = false(see Build and Dependencies). - Builds with the
semanticfeature need Rust 1.94 or newer; the rest of the crate still builds on 1.88.
Storage and Files
Format
| File | v0.4.2 | v0.5.0 |
|---|---|---|
Volume files (vol_*.vol) |
V4 | V5, with a CRC-32C on every section and block |
Manifest (manifest.bin) |
version 6 | version 8, recording each volume file’s identity and ending in a CRC-32C |
Secondary index side files (vol_*.sidx) |
version 4 | version 6, which also hold FLOAT keys and TEXT B-tree and Hash keys |
| WAL | version 2 | version 2 (unchanged) |
- v0.5.0 reads V4 volumes and version 6 and 7 manifests. Compaction rewrites V4 volumes as V5, one volume per table each cycle, so an upgraded database converts gradually with no downtime.
- No downgrade. v0.4.2 refuses a database once v0.5.0 has written a manifest, with
unsupported manifest version 8 (expected 6). Restore the backup you took before upgrading if you need to go back. PRAGMA VERIFY(new) checks every volume file’s checksums, structure and identity, and returns one row per volume withok,damaged,unreadableorfailed.
Open and Recovery
- A table whose listed volume is missing or unreadable is unavailable. v0.4.2 answered from the remaining volumes, silently missing rows. Now every statement on that table fails with an error naming the segments, other tables keep working,
DROP TABLEstill works, and putting the file back then reopening restores the table. While a table is unavailable,PRAGMA SNAPSHOTfails, and seal, compaction and WAL truncation wait. - Recovery stops at a committed WAL record it cannot apply, naming the operation, table and LSN. v0.4.2 skipped such records and opened with the data missing.
- The open runs a checkpoint after replaying the WAL, and fails if that checkpoint fails.
PRAGMA CHECKPOINTreturns an error when a manifest write fails instead of reporting success. - A damaged block in a V5 volume fails only the statements that read it, and the error names the file, column and row group.
- A
CREATE TABLEinside a transaction is written to the WAL, so the table and its committed rows survive a crash. - AUTO_INCREMENT ids of deleted rows are not handed out again after a reopen. Insert 1, 2, 3, delete 3, reopen: the next insert gets 4.
- Several crash windows around checkpoints that lost committed rows or brought dropped tables back are closed.
Reserved _rowid_
_rowid_ is a pseudo-column giving a row’s identity: its INTEGER primary key, or the id the engine assigned in a table without one. See Row Identity.
A database with a table that has a column named _rowid_ still opens, with a warning. That table refuses every statement except ALTER TABLE, DROP TABLE, DROP INDEX, SHOW CREATE TABLE, SHOW INDEXES and DESCRIBE until the column is renamed:
ALTER TABLE t RENAME COLUMN _rowid_ TO row_ref;
rowid without underscores stays an ordinary name.
Two Index Names That Differ Only in Case
Index names are now matched without regard to case. A v0.4.2 database holding both idxk and IdxK on one table still opens and keeps both, but DROP INDEX then needs the exact spelling; any other spelling is refused as ambiguous.
SQL That Now Returns an Error
Each item below was accepted by v0.4.2, usually with a silently wrong answer. The fix is almost always to write what the query meant.
Names and Scope
| Statement | v0.4.2 | v0.5.0 |
|---|---|---|
SELECT id FROM t JOIN u ON t.k = u.k (both have id) |
read t.id |
column reference 'id' is ambiguous; write t.id |
SELECT MAX(x) FROM (SELECT 1 AS x, 2 AS x) s |
read one of them | ambiguous |
SELECT zz.x FROM u (no FROM entry zz) |
read x |
unknown table or alias 'zz' |
SELECT t.a FROM t AS x |
read a |
table or alias 't' is not visible here: an aliased table is named only by its alias |
SELECT SUM(missing) FROM t |
NULL | column 'missing' not found |
SELECT b, COUNT(*) FROM t GROUP BY a |
b was NULL |
Column 'b' not found: read b through GROUP BY or an aggregate |
SELECT COUNT(*) FROM t GROUP BY nosuchcol |
one group over every row | Column 'nosuchcol' not found |
GROUP BY COUNT(*), or an aggregate by position or alias |
Function not found: COUNT |
an aggregate function cannot be a GROUP BY key |
SELECT a FROM t ORDER BY 2 |
unsorted | ORDER BY position 2 is not in the select list |
SELECT DISTINCT customer FROM orders ORDER BY order_date |
arbitrary order | error: every ORDER BY key must follow from the selected items |
SELECT DISTINCT ON (nosuchcol) a FROM t |
key dropped, one row | column 'nosuchcol' not found |
Names are compared by one rule everywhere, Unicode lowercasing. A table created as "äö" is found as "ÄÖ", and savepoint names are no longer case-sensitive. See Names.
A double-quoted "true" or "false" is a column name; only the unquoted words are boolean literals. With a column named true holding 5, SELECT "true" + 1 gives 6, where v0.4.2 gave NULL.
Statement Shape
- Text after a complete statement that is not
;is a parse error. v0.4.2 ran the statement and ignored the rest:UPDATE t SET v = 1 WHERE id = 1 2wrote the row. - A statement that writes one column more than once is refused:
UPDATE t SET v = 5, v = 6, a repeated column in an INSERT or COPY column list, or in an upsert’s assignments. ON CONFLICT ... DO UPDATEmeeting a row the same statement already inserted or updated fails withON CONFLICT DO UPDATE cannot affect a row a second time in one statementand writes nothing.INSERT INTO t VALUES (1, 'a'), (1, 'b') ON CONFLICT (id) DO UPDATE SET v = EXCLUDED.vleftv = 'b'in v0.4.2. Remove duplicate keys from the input, or useON DUPLICATE KEY UPDATE, which still updates such a row again.- Statements nested too deeply are refused when parsed: more than 32 nested SELECTs (subqueries, derived tables, CTE bodies) or 64 nested expressions in a release build. Deeper statements used to crash the process.
- DISTINCT, an inner ORDER BY and FILTER are allowed only on aggregate calls:
ABS(DISTINCT a)is an error. - A subquery must return as many values as its place takes, with
*counting every column:a IN (SELECT x, y FROM u)is an error. A row compared with a row of another width,(1, 2) = (1, 2, 3), is an error (v0.4.2 answered true), andSELECT (1, 2)is an error (v0.4.2 answered 1). - A grouped query’s subquery that reads an outer column not in GROUP BY fails as an ungrouped column.
- AS OF works only on a table: on a view or a CTE it is an error (v0.4.2 ignored it), and
CREATE VIEWrefuses a query that reads a tableAS OF. - Set operations: in the ORDER BY of a UNION, INTERSECT or EXCEPT, a name two result columns carry is ambiguous and a qualified name is an error. Use a position.
Parameters
- A parameter with no value is an error on every path, before any row is read or written. v0.4.2 mostly read it as NULL.
- Mixing positional (
$1,?) and named (:name) parameters in one statement is a parse error, and so is$0. - Two anonymous
?are two different expressions:SELECT g + ?, COUNT(*) FROM t GROUP BY g + ?fails as an ungrouped column. Repeat a value with$1or:name. CREATE VIEWrefuses parameters.
Evaluation Errors
A runtime error in an expression now fails the statement wherever the expression sits: the SELECT list, WHERE, ORDER BY, GROUP BY, join conditions, window arguments, UPDATE SET, DEFAULT and CHECK. v0.4.2 returned NULL, skipped the row or read the condition as false, so an UPDATE or DELETE could change every row but the failing one.
- INTEGER overflow is an
Integer overflowerror for every operator. Addition already was; newly,ABSand unary minus of the smallest INTEGER (v0.4.2 gave NULL), the smallest INTEGER divided by -1 (v0.4.2 crashed the process), and1 << 64(v0.4.2 gave 1; a shift outside 0 to 63 is an error). Division by zero still gives NULL. - SUM over INTEGER values that leaves the INTEGER range is
Integer overflow in SUM(v0.4.2 turned it into FLOAT or wrapped). - FLOAT to INTEGER outside the INTEGER range, or NaN or infinity, is an error:
CAST(1e30 AS INTEGER)(v0.4.2 gave the largest INTEGER). - LIMIT and OFFSET must be an INTEGER of 0 or more, or a FLOAT without a fraction, on every path:
LIMIT 2.5is an error (v0.4.2 returned 2 rows). - Window arguments: ROWS and LAG/LEAD offsets must be INTEGER >= 0, NTILE and NTH_VALUE counts INTEGER >= 1, RANGE offsets a number >= 0.
- REPEAT, LPAD, RPAD and REPLACE refuse a result over 10 MB.
generate_seriespast 10,000,000 rows is an error instead of a cut-short answer.- A vector distance with mismatched dimensions, or a non-vector argument, is an error in
ORDER BY VEC_DISTANCE_*(...) LIMIT kand with<=>(v0.4.2 gave NULL).
DDL, Constraints and Foreign Keys
- Table-level CHECK constraints are enforced (v0.4.2 parsed and dropped them), a column CHECK may name other columns, and a CHECK now runs on a NULL value: only a NULL result passes, so
CHECK (v IS NOT NULL)refuses a NULL. A CHECK that fails to evaluate fails the statement. - A DEFAULT or CHECK holding a subquery, aggregate or window function is refused.
ALTER TABLE ... ADD COLUMNrefuses CHECK, UNIQUE, PRIMARY KEY, AUTO_INCREMENT and REFERENCES (v0.4.2 accepted them without enforcing them), and refusesNOT NULLwithout a non-NULL DEFAULT while the table holds rows.ALTER TABLE ... DROP COLUMNrefuses the primary key column, a column a foreign key references, and a column another CHECK reads.ALTER TABLE ... MODIFY COLUMNrefuses the primary key column, foreign key columns, and changes whose cast values would turn NOT NULL values into NULL or break UNIQUE. It now rewrites hot rows, indexes and sealed volumes.DROP TABLEis refused while another table’s foreign key references the table.DROP TABLE ... CASCADE(new) drops the table and the referencing keys.- An UPDATE that sets NULL in a NOT NULL column is refused for every row (v0.4.2 stored it for rows still in memory).
- Foreign keys are checked by
ON CONFLICT DO UPDATEandON DUPLICATE KEY UPDATE(v0.4.2 skipped them). - A foreign key check holds the parent key until its transaction ends: a child INSERT racing an uncommitted parent DELETE fails with a write conflict instead of both committing.
- Names: any name, CHECK or DEFAULT text over 65,535 bytes, a table name over 255 bytes, and a table name containing
/or..are refused. - Views:
CREATE VIEWruns its query once and refuses one that cannot run or that gives two columns the same name. Reading a view whose query now returns another number of columns asks for the view to be created again.ALTER TABLE ... RENAME TOa name a view has is refused.
Transactions and Concurrency
- Unique key violations inside an explicit transaction are reported when the statement ends, not at COMMIT. The failing statement is undone and the transaction stays open.
- A statement that overlaps a concurrent ADD, DROP or RENAME COLUMN fails with
SchemaChanged(v0.4.2 could read wrong positions). - A READ COMMITTED write that a TRUNCATE or DROP overtakes fails with
ViewOvertaken; a SELECT retries up to 3 times. - A query timeout stops every kind of work: writes, joins, sorts, windows, aggregation, recursive CTEs, storage scans and ANALYZE, with
QueryCancelled. A stopped write leaves no row changed. v0.4.2 timed only part of a SELECT, so an UPDATE with a 20 ms timeout committed all of its rows. - The rows a timed query returns keep its deadline while you read them, and the time between two reads counts toward it. An application that reads a timed query’s rows slowly can get
QueryCancelledpart way through.
Queries Whose Answers Change
Comparison and Ordering
v0.5.0 compares and orders values by one rule on every plan, in memory or on disk. See Operators and Expressions and NULL Handling.
- Numbers and TEXT: TEXT that reads as a number is compared as that number; any other TEXT makes the comparison UNKNOWN.
1 = 'abc'is NULL. A number and TEXT are never a join key. - BOOLEAN and TIMESTAMP are not numbers:
i = TRUEno longer matchesi = 1, and<,>and BETWEEN between them are UNKNOWN. - JSON and VECTOR are only equal or unequal by value. A JSON column
= 'text'matches nothing; writeCAST(... AS JSON). - FLOAT uses one total order: NaN equals NaN and is greater than every number, and
0.0equals-0.0.MAXis NaN when a NaN is present, and GROUP BY puts every NaN in one group. - Sorting across types (ORDER BY, MIN, MAX, GREATEST, LEAST, windows) uses one order: BOOLEAN, numbers, TEXT, TIMESTAMP. Mixed columns used to sort by arrival order.
- Row comparisons compare every value:
(1, 2) = (1, 3)is false (it was true). - ORDER BY on an indexed column with LIMIT puts NULLs last ascending and first descending, as the full sort does.
- LIKE, ILIKE, GLOB and REGEXP read both sides as their
CAST AS TEXTform;n LIKE '1%'on an INTEGER column matches the same rows in memory and on disk.UPPER(s) LIKE 'john%'is case-sensitive again, and ILIKE folds non-ASCII case.
Aggregates and Grouping
- SUM of INTEGER values is an exact INTEGER; it is FLOAT once any value is FLOAT. Some GROUP BY paths returned FLOAT for integer sums.
- Repeated aggregates keep every column:
SELECT SUM(a), SUM(a) FROM treturns two columns. - Aggregates are matched by their whole expression:
STRING_AGG(v, ',')andSTRING_AGG(v, ';')no longer share one result. - GROUP BY treats 1 and 1.0 as one group.
- HAVING alone (no GROUP BY, no aggregate in the SELECT list) aggregates the statement into one group.
- Window functions over ROLLUP, CUBE or GROUPING SETS see every group, subtotal rows included.
- STRING_AGG: the separator may be any expression, and one that reads the row is read for each row:
STRING_AGG(s, s)over'p','q','r'givespqqrr(v0.4.2 answered NULL). A NULL separator adds nothing (v0.4.2 used,), andSTRING_AGG(s, '-' || '')joins with-(v0.4.2 answered NULL). - A grouped column is read from its GROUP BY item even when an aggregate’s alias has the same name.
- COUNT(DISTINCT) and DISTINCT keep NULLs held by sealed rows and count re-inserted rows correctly.
Result Column Names
An unaliased SELECT item is named as written on every path: ROW_NUMBER() OVER (...), SUM(f) OVER (PARTITION BY g), COUNT(DISTINCT g). v0.4.2 produced names such as expr6, column_2 or SUM(). Code that reads result columns by position is unaffected; code that reads them by these generated names needs an alias.
A derived table, CTE or view over SELECT * from a join names its columns by their plain names (k, not u.k).
Joins
Many join answers are fixed. If your application relied on any of these, check its results:
- USING and NATURAL joins: each name joins on the first column of that name on each side; RIGHT and FULL joins read the merged column from the side that has the row (
COALESCE(left, right)for FULL). - An index join applies its whole ON clause; a CTE side, an AS OF side and a VALUES side keep their conditions.
- A large merge of nearly sorted inputs no longer loses matches (merge join is gone).
- Joins with LIMIT, DISTINCT or DISTINCT ON return the full number of rows.
- Without ORDER BY, the row order of a join may differ, because INNER joins of three or more tables may now be reordered. Add ORDER BY where order matters.
Set Operations, Recursive CTEs and Queries Without FROM
| Statement | v0.4.2 | v0.5.0 |
|---|---|---|
SELECT 2 UNION SELECT 1 EXCEPT SELECT 2 |
2, 1 | 1 |
SELECT 1 UNION SELECT 2 EXCEPT SELECT 2 INTERSECT SELECT 3 |
1 | 1, 2 |
SELECT DISTINCT 1 UNION ALL SELECT 1 |
one row | two rows |
WITH RECURSIVE r(n) AS (SELECT 1 UNION ALL SELECT 100 UNION ALL SELECT n + 1 FROM r WHERE n < 3) SELECT COUNT(*) FROM r |
10003 | 4 |
SELECT COUNT(*) WHERE FALSE |
no row | one row, 0 |
SELECT 1 WHERE 0 |
one row | no row |
- INTERSECT binds tighter than UNION and EXCEPT, which bind equally and apply left to right. Group with derived tables where a chain meant another order.
- A leading
SELECT DISTINCTremoves duplicates from its own SELECT only, before the rows are combined. - In
WITH RECURSIVE, every branch that does not read the CTE is an anchor and runs once. v0.4.2 added a later non-recursive branch again on every pass. - A statement without FROM reads one row with no columns, so an aggregate answers one row, and a WHERE keeps that row only for TRUE or a non-zero integer.
Functions
| Statement | v0.4.2 | v0.5.0 |
|---|---|---|
SELECT MOD(-7.5, 2) |
-1 | -1.5 |
SELECT SPLIT_PART('abc', '', 1) |
'' |
'abc' |
SELECT TO_CHAR(TIMESTAMP '2024-01-02 00:00:00', 'Day') |
Tuestuesday |
Tuesday |
Dates, Times and Intervals
- TIMESTAMP range: a table stores TIMESTAMP values from
1677-09-21to2262-04-11. Storing a value outside it is an error. A row written by v0.4.2 with such a value and still in memory makes the checkpoint report an error naming the table and row; v0.4.2 silently corrupted it when sealing. Computing outside the range (years 0000 to 9999) still works. - TIME values: a time of day alone (
'12:00:00') now reads as1970-01-01 12:00:00. TIME values stored by v0.4.2 carry the date they were written on and no longer equal the same time written now. See Date and Time for moving such a column onto 1970-01-01. - Timestamp text:
'2024/03/04'and'03/04/2024'read as dates (the US form first when both read); a two-digit year such as'24-03-04'no longer reads as a timestamp; aTIMESTAMP 'not a date'literal is a parse error. - Intervals:
n * INTERVAL '1 second'and-INTERVAL '1 hour'evaluate (v0.4.2 gave NULL). Compound literals such asINTERVAL '1 month 1 day'are an error (v0.4.2 kept the first unit). Month and year steps move on the calendar with the day clamped. - Text conversion: every conversion of a value to text follows
CAST AS TEXT, so timestamps are written in RFC 3339.
AS OF
- History lasts from the last open: a point from before it is an error naming the oldest readable point, where v0.4.2 returned missing rows. The same holds for points cut off by VACUUM, TRUNCATE, column changes, a seal, compaction, and the per-row version and 24-hour limits. See Temporal Queries.
- Tables with sealed volumes answer AS OF for any point after their newest seal; v0.4.2 refused every historical read on such tables.
AS OF TIMESTAMP tincludes only transactions whose commit completed byt;AS OF TRANSACTION nmeans right afterncommitted, in commit order.- AS OF inside an explicit transaction is honoured (v0.4.2 read current rows).
Writes
- A DELETE re-checks its WHERE against the version it deletes, so a row a concurrent commit stopped matching is not deleted.
- Subqueries in RETURNING and ON CONFLICT read tables as the statement found them, before its own cascades.
ALTER TABLE ... RENAMEandRENAME COLUMNre-point the foreign keys that reference the table or column.
Changed Defaults
| Setting | v0.4.2 | v0.5.0 |
|---|---|---|
CREATE INDEX on a TEXT column without USING |
Hash | B-tree (JSON columns still get Hash; existing indexes keep their type; write USING HASH for the old behaviour) |
SET isolation_level and set_default_isolation_level |
engine-wide | per session; a session that sets none uses the engine’s level |
| Opening a DSN that is already open | the opener’s handle and its transaction | a new session on the same engine, with its own transaction state |
| Engine close | when the original handle drops | when the last handle drops, clones included; a Transaction keeps its database open until commit or rollback |
Threads sharing one Database handle |
serialised | run statements concurrently outside an explicit transaction |
sync_mode=none |
each schema change synced | schema changes buffered; checkpoint catalog copies still synced |
| Query timeout | parts of SELECT | every statement kind; PRAGMA query_timeout and the query_timeout DSN key set a per-connection default (0, no timeout) |
| EXPLAIN ANALYZE | recorded feedback that changed later plans | no feedback; prints EXPLAIN’s plan lines with the run’s time and rows on the top line |
New Features
_rowid_pseudo-column. See Row Identity.UPDATEmay change an INTEGER primary key;ON UPDATE CASCADEinto a child’s primary key works.- Self-referencing foreign keys,
DROP TABLE ... CASCADE,NATURAL FULL JOIN,NATURAL INNER JOIN. ALTER TABLE t AUTO_INCREMENT = n;ALTER TABLE t DROP CLUSTER BY.PRAGMA query_timeout,PRAGMA VERIFY.- Subqueries in INSERT VALUES, RETURNING, ON CONFLICT, JOIN ON, LIMIT and OFFSET, window arguments, VALUES rows and table-function arguments; a subquery may start with its own WITH.
- Row value comparisons:
(a, b) IN (SELECT x, y ...),(a, b) = (SELECT x, y ...). RETURNINGitems accept aliases.- Interval arithmetic:
n * INTERVAL '...', negated intervals. execute_countsreturnsExecCounts { matched, changed }, so an UPDATE reports the rows it actually changed.- serde deserialization of result rows:
ResultRow::deserialize,Rows::deserialize,Database::query_as_serde. - EXPLAIN shows the planner’s plan tree; see EXPLAIN. Its output format differs from v0.4.2.
Rust API Changes
The engine internals are public modules, so this list names what an embedder is most likely to touch. A crate that only uses Database, Statement, Transaction, Rows and Value needs few or no changes.
Removed or Made Private
- Modules
stoolap::optimizerandstoolap::plannerare crate-private. - Crate-root exports removed:
BufferPool,PoolStats,SemVer,RangeExpr,EmptyResult,EmptyScanner,VecScanner,RangeScanner,SingleRowScanner,DEFAULT_CHECKPOINT_INTERVAL,DEFAULT_KEEP_SNAPSHOTS. Transaction::execute_prepared_namedandquery_prepared_named: useStatement::execute_named_inandquery_named_in.Executor::with_function_registryandfunction_registry: every path uses one global registry.TimeoutGuard,CancellationHandleand theExecutionContextcancellation methods: useExecutionContext::deadline()andset_deadline().- The name-based expression compiler and the subquery caches in
stoolap::executor:compile_expression,CompiledEvaluator,clear_scalar_subquery_cacheand the otherclear_*cache functions. Every statement runs from its prepared plan. MVCCEngine::get_table_for_txnis crate-private: useTransaction::get_table.- AST variants
Expression::Distinct,InHashSetandCteReference;TokenType::Date,TimeandTimestamp; parserKEYWORDSandis_keyword(&str)(use theKeywordenum).
Changed
Error:LockAcquisitionFailedis removed. New variants:TableCheckViolation,TableHasOpenTransactionRows,ViewOvertaken,WalOutcomeUnknown.Error::UniqueConstraintcarriesConflictValues, and itsrow_idisi64::MINwhen no row holds the key (it was -1). Amatchthat lists every variant needs updating.FunctionRegistry::register_scalar,register_aggregate,register_windowandregister_tvfreturnResult<()>and refuse a built-in function’s name, so built-ins can no longer be overridden.FunctionInfocarriesVolatility(Fixed,PerStatement,PerCall) instead of a deterministic flag.- Custom aggregates:
AggregateFunction::resultreturnsResult<Value>, andaccumulateloses itsdistinctparameter. set_default_isolation_leveltakes&self.- The storage
TableandIndextraits changed: several methods take aDeadline;deletetakes the access the caller decides;select_as_ofis replaced byrows_at;insert_with_id,has_visible_rowandfor_each_unique_non_pk_indexmust be implemented; update setters areFnMut(i64, Row), given each row’s id;sum_columnreturns aSumAccumulator;scan_top_ktakes NULL placement and the columns to read;Index::find_with_operatorreturns an error for an operator it cannot answer. Table::commiton a handle from a transaction publishes nothing: the transaction’s own commit publishes the handle’s rows with their WAL records. Code that calledTable::committo make a transaction’s rows visible commits the transaction instead.- Library locks no longer poison after a panic.
Added
ExecCounts, Volatility, Statement::execute_in, query_in, execute_named, query_named, execute_named_in, query_named_in, Database::execute_counts, ResultRow::deserialize, Rows::deserialize, Database::query_as_serde, Database::query_as_serde_named, Value::vector_f32_iter.
C API Changes
New functions in include/stoolap.h:
stoolap_exec_params_counts,stoolap_stmt_exec_counts,stoolap_tx_exec_params_countsstoolap_stmt_exec_named,stoolap_stmt_query_namedstoolap_stmt_query_all,stoolap_query_params_all,stoolap_query_named_all,stoolap_stmt_query_named_all,stoolap_rows_fetch_chunk
Changed behaviour:
- A runtime error part way through a fetch-all is returned as an error, not a partial result.
- A non-UTF-8 text parameter or invalid JSON parameter fails the call (v0.4.2 bound NULL).
stoolap_stmt_exec_batchrefuses a negativeparams_per_rowor NULL params.- A transaction handle passed with a database handle of another database is refused with
transaction belongs to another database. - Functions returning the packed result format return
STOOLAP_ERRORfor a column name longer than 65,535 bytes. stoolap_rows_nextand the batch fetch return an error for a TIMESTAMP outside the stored range.
Build and Dependencies
- jemalloc is the default global allocator (the
jemallocfeature, on by default). An embedder that installs its own#[global_allocator]must depend onstoolapwithdefault-features = false, adding backparallel(andclifor the binary) as needed. Themimallocfeature is removed. - The
heap-profilefeature enablesPRAGMA heap_profile. - The two comparison-benchmark features and
dhat-heapare removed; the comparison benchmarks live in the unpublishedstoolap-comparecrate. - The minimum Rust version stays 1.88, except for the optional
semanticfeature, which needs Rust 1.94 or newer: it moved to candle 0.11 (for zip 9, which fixes zip 7’s advisories), and candle’s x86_64 code needs intrinsics that are stable or safe only from 1.94. ahashmust be 0.8.12 or newer. A--lockedbuild whose lock file holds an older 0.8 release needscargo update -p ahashfirst.- The browser WASM build has its own size-optimized profile:
wasm-pack build --target web --profile wasm -- --no-default-features --features wasm.
Drivers
The Python, Node.js, Go, PHP, Ruby, Java, C#, Swift and MCP drivers are released separately. Upgrade a driver to its release built on Stoolap 0.5 to get this engine; the driver pages name the versions.
Rollback
There is no automatic downgrade. To return to v0.4.2:
- Stop the application.
- Restore the database directory from the backup taken before the upgrade.
- Reinstall v0.4.2.
Writes made under v0.5.0 are not in that backup. To carry them back, export them from v0.5.0 (for example with SELECT or COPY) and load them into the restored database.
Troubleshooting
“column reference ‘x’ is ambiguous”
Two sources of a join (or two columns of a derived table) carry the name. Qualify it: t.x. v0.4.2 silently read one of them.
“unknown table or alias” or “table or alias ‘t’ is not visible here”
The qualifier names no FROM entry in scope, or names a table that has an alias. v0.4.2 read the bare column instead. Use the alias, or the FROM entry that holds the column.
“Column ‘x’ not found”
The name does not exist where it is written. v0.4.2 often answered NULL instead. In a grouped query the same error means the query reads a column outside GROUP BY and outside any aggregate: add it to GROUP BY or wrap it in an aggregate such as MAX(...).
“Integer overflow”
An INTEGER computation left the INTEGER range. For ABS, negation, division and SUM, v0.4.2 returned NULL, a FLOAT or crashed. Cast to FLOAT before the operation if the larger range is intended.
A table refuses every statement after the upgrade
Either a listed volume file is missing or unreadable (the error names the segments; restore the file and reopen), or the table has a column named _rowid_ (rename it).
The database does not open after a crash
The error names the WAL record, table and LSN that recovery could not apply. Restore from a backup snapshot with the CLI:
stoolap -d file:///path/to/db --restore # latest snapshot
stoolap -d file:///path/to/db --reset-volumes --restore # when volumes or manifests are damaged
See Persistence.