v1.14.2

NeoSQLite v1.14.2 Release Notes

TL;DR

NeoSQLite v1.14.2 is a bug fix and performance optimization release that resolves compound index sort order issues in the NX-27017 wire protocol and improves write performance through consolidated UPDATE statements.

Critical Fix: This release resolves a functional issue where compound indexes with mixed ASCENDING/DESCENDING fields lost their sort order when created via the NX-27017 wire protocol, potentially causing suboptimal query plans.

• Upgrade if you use: NX-27017 wire protocol with compound indexes, or need faster bulk update performance.
• Result Correctness: Achieved 100% compatibility in API comparison reports (378 tests, 0 failures).

---

Overview

This release focuses on wire protocol correctness and update performance optimization:

• Compound Index Sort Order Fix — NX-27017 now preserves ASCENDING/DESCENDING sort directions when creating compound indexes via createIndexes and createIndex wire protocol commands.
• Consolidated UPDATE Statements — Multiple UPDATE operations are now combined into single nested JSON function calls, reducing database round-trips.
• Faster Writes with WAL — Set PRAGMA synchronous=NORMAL by default when using WAL journal mode for improved write throughput.
• Optimized DateTime Detection — Early-exit optimizations in is_datetime_value() with quick rejection for common non-datetime types.

---

High Severity Fixes

Fixed Compound Index Sort Order in NX-27017

Problem: When creating compound indexes via the MongoDB wire protocol (e.g., {"city": 1, "age": -1}), NX-27017 extracted only field names ["city", "age"], discarding sort direction information. This caused indexes to be created with default ASCENDING order instead of the specified ASCENDING/DESCENDING mix.

Solution: Convert key dictionary to tuple list [("city", 1), ("age", -1)] before passing to create_index(). Fixed in both createIndexes (batch) and createIndex (legacy) command handlers.

---

Medium Severity Enhancements

Consolidated UPDATE Operations

Optimization: Multiple UPDATE statements for single-document modifications are now consolidated into a single nested JSON function call. This reduces SQLite transaction overhead and improves write performance by 20-40% for documents with multiple field updates.

Optimized DateTime Detection

Performance: Added early-exit optimizations to is_datetime_value() with quick rejection for common non-datetime types (strings, integers, booleans, None). This reduces unnecessary type checking overhead in query processing.

WAL Mode Write Performance

Configuration: When using WAL journal mode (the default), PRAGMA synchronous=NORMAL is now set automatically. This provides a good balance between crash safety and write performance, matching SQLite's recommended settings for WAL mode.

---

Low Severity Improvements

Benchmark Module Reorganization

All 59 benchmark categories have been renamed with meaningful, self-documenting names:

• crud.py → crud_operations.py
• expr_operators.py → expr_core_operators.py
• aggregation_stages.py → aggregation_basic_stages.py
• And 27 more...

Category names now follow the pattern Category (Subcategory), making it immediately clear what each test measures.

Options Classes Compatibility-Only

The "Options Classes" category (WriteConcern, ReadPreference, etc.) is now excluded from benchmark timing since these are configuration objects with no actual database I/O. They remain in compatibility tests but no longer skew benchmark results.

---

Test Statistics

Unit Tests

Metric	Result
Total Tests	2,542
Passed	2,542
XFailed	0
Failed	0
Code Coverage	80%

API Comparison Tests

NeoSQLite vs MongoDB

Metric	v1.14.2
Total Tests	378
Passed	363
Skipped	15
Failed	0
Compatibility	100.0%

---

Installation

pip install neosqlite
# or
poetry install

---

Migration Guide

Upgrading from v1.14.1

This is a non-breaking patch release. Users of NX-27017 with compound indexes should upgrade immediately to fix sort order preservation.

For NX-27017 Users

If you created compound indexes with mixed ASCENDING/DESCENDING fields via the wire protocol before this release, you may want to rebuild those indexes:

# Drop and recreate compound indexes with correct sort order
collection.drop_indexes()
collection.create_index([("city", 1), ("age", -1)])

---

Credits

Compound index fixes and performance optimizations developed as part of the NeoSQLite project.

---

NeoSQLite v1.14.2 — Compound Index Sort Order Fix, Consolidated Updates, and Faster WAL Writes.