--- title: "HeliosDB-Lite v3.1 Release Notes" --- # HeliosDB-Lite v3.1 Release Notes **Previous Version**: v3.0.0 (GA) --- ## Overview HeliosDB-Lite v3.1 adds schema inference, encryption key management and multi-tenancy infrastructure. All features are fully backward compatible with v3.0.x. **Statistics:** - 35+ new API endpoints - 0 breaking changes --- ## Major Features ### 1. Schema Inference API Automatically detect database schemas from JSON data samples. **Endpoints:** - `POST /api/v1/schema/infer` - Infer from JSON samples - `POST /api/v1/schema/infer/batch` - Batch inference for multiple tables - `POST /api/v1/schema/infer/file` - Infer from uploaded files (CSV, JSON, Parquet) - `POST /api/v1/schema/optimize` - Optimization recommendations - `POST /api/v1/schema/compare` - Compare schemas and generate migrations - `POST /api/v1/schema/validate` - Validate DDL syntax - `POST /api/v1/schema/generate` - Natural language to DDL (framework) - `GET /api/v1/schema/templates` - Schema templates - `POST /api/v1/schema/templates/instantiate` - Use templates **Type Detection:** - BOOLEAN - Boolean values - INTEGER/BIGINT - Numeric values with size optimization - NUMERIC - Floating point numbers - VARCHAR(n) - Strings with configurable length - TEXT - Long text content - VECTOR(n) - Numeric arrays for vector search - JSONB - JSON objects - JSON - JSON arrays **Features:** - Nullable column detection - Unique column detection - Confidence scoring (0.0-1.0) - DDL generation with constraints - Batch processing - Customizable inference options **Example** (REST API on `--http-port`, default `8080`; see [Testing](#testing) for the token): ```bash curl -X POST http://127.0.0.1:8080/api/v1/schema/infer \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "samples": [ {"id": 1, "name": "Alice", "email": "alice@example.com", "age": 30}, {"id": 2, "name": "Bob", "email": "bob@example.com", "age": 25} ], "table_name": "users", "options": { "detect_nullable": true, "detect_vectors": true, "prefer_narrow_types": true } }' ``` **Response:** ```json { "success": true, "data": { "table_name": "users", "columns": [ { "name": "id", "sql_type": "INTEGER", "nullable": false, "confidence": 0.95 }, { "name": "name", "sql_type": "VARCHAR(100)", "nullable": false, "confidence": 0.95 }, { "name": "email", "sql_type": "VARCHAR(200)", "nullable": false, "confidence": 0.95 } ], "ddl": "CREATE TABLE users (...);", "confidence": 0.85, "warnings": [] } } ``` --- ### 2. Key Rotation Framework Encryption key management with rotation support. **Features:** - Key rotation without data loss - Backup previous key for legacy data decryption - Rotation metadata with timestamps - SHA256 key identification for audit trails - Full backward compatibility during rotation **Rotation Workflow:** 1. Generate new encryption key 2. Activate the new key 3. Store previous key for legacy data decryption 4. Re-encrypt data with new key (async process) 5. Audit rotation via metadata --- ### 3. Multi-Tenancy & RLS Framework Complete infrastructure for tenant isolation and row-level security. **Features:** - Tenant registration and management - Three isolation modes: SharedSchema, DatabasePerTenant, SchemaPerTenant - RLS policy definition - Per-request tenant context - Resource quota framework - Audit trail for tenant operations **Isolation Modes:** 1. **SharedSchema** - Shared database + schema, isolated via RLS 2. **DatabasePerTenant** - Separate database per tenant 3. **SchemaPerTenant** - Separate schema per tenant --- ### 4. Agent Memory API (Fixed & Enabled) 13 endpoints for AI agent session management and memory operations. **New Endpoints:** - `POST /api/v1/agents/memory` - Create session - `GET /api/v1/agents/memory` - List sessions - `GET /api/v1/agents/memory/:id` - Get session details - `PUT /api/v1/agents/memory/:id` - Update session - `DELETE /api/v1/agents/memory/:id` - Delete session - `POST /api/v1/agents/memory/:id/add` - Add message - `POST /api/v1/agents/memory/:id/messages/batch` - Batch add messages - `GET /api/v1/agents/memory/:id/messages` - Get messages - `POST /api/v1/agents/memory/:id/search` - Search memory (FIXED) - `POST /api/v1/agents/memory/:id/summarize` - Summarize memory - `POST /api/v1/agents/memory/:id/context` - Get context - `POST /api/v1/agents/memory/:id/fork` - Fork session - `POST /api/v1/agents/memory/:id/clear` - Clear messages **What's Fixed:** - Tool calls type conversion in memory search - Full support for function_call and tool_calls fields - Proper JSON deserialization --- ### 5. Document Management API (Enabled) 10+ endpoints for document storage and semantic search. **Endpoints:** - `GET /api/v1/documents` - List documents - `POST /api/v1/documents` - Create document - `POST /api/v1/documents/batch` - Batch create - `GET /api/v1/documents/:id` - Get document - `PUT /api/v1/documents/:id` - Update document - `DELETE /api/v1/documents/:id` - Delete document - `POST /api/v1/documents/search` - Full-text search - `GET /api/v1/documents/:id/chunks` - Get chunks - `POST /api/v1/documents/:doc_id/chunk` - Chunk document - `POST /api/v1/documents/:doc_id/similar` - Similar documents --- ## Technical Improvements ### Performance - Schema inference: O(n*m) where n=samples, m=columns - Key rotation: Negligible overhead (metadata only) - Tenant lookups: O(1) - No regressions in existing operations ### Security - Zeroized encryption keys (automatic on drop) - SHA256 hashing for key IDs - RLS framework for tenant isolation - Audit trails for rotation --- ## Installation & Upgrade ### From v3.0.0 Unpack the v3.1 release archive (licensed source distribution) and build in its directory: ```bash cargo build --release # No database migration needed - fully compatible ``` ### Fresh Installation ```bash cargo build --release export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)" # required by heliosdb-lite start ./target/release/heliosdb-lite start --port 5432 ``` --- ## Testing ### Test New Features The REST API listens on `--http-port` (default `8080`), not on the PostgreSQL port `5432`. Every `/api/v1` and `/v1` route requires `Authorization: Bearer `, signed with the `HELIOSDB_JWT_SECRET` the server was started with; the [JWT Auth Quick Reference](/docs/lite/guides/quickstart/jwt_auth_quick_reference/) shows how to sign one. Set `TOKEN` to that JWT: ```bash # Schema inference curl -X POST http://127.0.0.1:8080/api/v1/schema/infer \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"samples": [{"id": 1, "name": "test"}]}' # Agent memory curl -X POST http://127.0.0.1:8080/api/v1/agents/memory \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{}' # Documents curl http://127.0.0.1:8080/api/v1/documents \ -H "Authorization: Bearer $TOKEN" ``` --- ## Migration Guide ### No Breaking Changes All v3.0.x applications work unchanged with v3.1. ### Adoption Path 1. **Week 1**: Deploy v3.1 (zero downtime) 2. **Week 2**: Start using schema inference for new tables 3. **Week 3**: Implement tenant management for multi-tenant scenarios 4. **Week 4**: Plan key rotation schedule ### Example Migration SQL and sessions from v3.0 run unchanged. For example, an in-memory session in the REPL: ```bash heliosdb-lite repl --memory ``` ```sql CREATE TABLE users (id INT, name VARCHAR(100)); INSERT INTO users VALUES (1, 'Alice'); SELECT * FROM users; ``` The same statements run against a server started with `heliosdb-lite start --memory` or `--data-dir `. In-process code written against v3.0 also works unchanged (embedded API, licensed source distribution). --- ## Known Issues None reported for v3.1. --- ## Contributing We welcome contributions! See CONTRIBUTING.md for guidelines. --- ## License HeliosDB-Lite is source-available under the Server Side Public License (SSPL-1.0) and is available to licensed customers. See LICENSE in the source distribution. --- **Thank you for using HeliosDB-Lite v3.1!** For questions or feedback: support@heliosdb.com