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 for the token):

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:

{
  "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:

Generate new encryption key
Activate the new key
Store previous key for legacy data decryption
Re-encrypt data with new key (async process)
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:

SharedSchema - Shared database + schema, isolated via RLS
DatabasePerTenant - Separate database per tenant
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:

cargo build --release

# No database migration needed - fully compatible

Fresh Installation

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 <JWT>, signed with the HELIOSDB_JWT_SECRET the server was started with; the JWT Auth Quick Reference shows how to sign one. Set TOKEN to that JWT:

# 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

Week 1: Deploy v3.1 (zero downtime)
Week 2: Start using schema inference for new tables
Week 3: Implement tenant management for multi-tenant scenarios
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:

heliosdb-lite repl --memory

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