v1.3-to-v1.4.md

Migration Guide: v1.3.x to v1.4.x

Overview

ThemisDB v1.4.x introduces API versioning infrastructure, extended context window support, LLM/LoRA framework enhancements, and improved pagination. This is a non-breaking upgrade with full backward compatibility.

Upgrade Difficulty: Easy
Estimated Time: 30-60 minutes
Downtime Required: No (rolling upgrade supported)

What's New in v1.4.x

Major Features

1. API Versioning (NEW in v1.4.1)

   • Accept-Version header support
   • Deprecation tracking
   • 24-month deprecation policy

2. Extended Context Window (32K+)

   • RoPE/YARN scaling
   • Memory profiling
   • Production-ready status

3. LLM/LoRA Framework

   • Multi-adapter support
   • Dynamic adapter switching
   • Prometheus metrics integration

4. Enhanced Pagination

   • Cursor-based pagination
   • Keyset pagination
   • Improved performance

Breaking Changes

None - All changes are backward compatible.

New API Features

API Version Negotiation

You can now specify API version in requests:

GET /api/entities/urn:themis:entity:123
Accept-Version: v1.4.0
Authorization: Bearer <token>

Before (v1.3.x):

curl https://api.themisdb.com/api/entities/123

After (v1.4.x):

curl -H "Accept-Version: v1.4.0" \
     https://api.themisdb.com/api/entities/123

Response includes version:

HTTP/1.1 200 OK
API-Version: v1.4.0
Content-Type: application/json

gRPC Version Negotiation

// Before (v1.3.x) - no version metadata
grpc::ClientContext context;
stub->Create(&context, request, &response);

// After (v1.4.x) - with version metadata
grpc::ClientContext context;
context.AddMetadata("api-version", "v1.4.0");
stub->Create(&context, request, &response);

Deprecated Features

None - No features are deprecated in v1.4.x.

The deprecation tracking infrastructure is now in place for future deprecations.

Step-by-Step Migration

1. Pre-Migration Checklist

• Review CHANGELOG v1.4.x
• Backup database and configuration
• Test in staging/development environment
• Review API Versioning docs
• Check Deprecation Registry

2. Backup Procedures

# Backup database
themisdb-backup create --output /backups/themis-v1.3-$(date +%Y%m%d).tar.gz

# Backup configuration
cp -r /etc/themisdb /etc/themisdb.backup.v1.3

# Verify backup
themisdb-backup verify /backups/themis-v1.3-*.tar.gz

3. Upgrade Steps

Option A: Package Manager (Recommended)

# Debian/Ubuntu
sudo apt update
sudo apt install themisdb=1.4.1

# RHEL/CentOS
sudo yum update themisdb-1.4.1

# Restart service
sudo systemctl restart themisdb

Option B: Docker

# Pull new image
docker pull themisdb/themisdb:v1.4.1

# Update docker-compose.yml
# services:
#   themisdb:
#     image: themisdb/themisdb:v1.4.1

# Restart container
docker-compose up -d

Option C: Manual Binary

# Download binary
wget https://github.com/makr-code/ThemisDB/releases/download/v1.4.1/themisdb-v1.4.1-linux-amd64.tar.gz

# Extract
tar xzf themisdb-v1.4.1-linux-amd64.tar.gz

# Replace binary
sudo systemctl stop themisdb
sudo cp themisdb /usr/local/bin/
sudo systemctl start themisdb

4. Post-Migration Validation

# Check version
curl http://localhost:8080/api/status | jq '.version'
# Expected: "1.4.1-dev" or "1.4.1"

# Check API version support
curl http://localhost:8080/api/status | jq '.api_version'
# Expected: {"major": 1, "minor": 4, "patch": 1}

# Test versioned request
curl -H "Accept-Version: v1.4.0" \
     http://localhost:8080/api/health
# Should return 200 OK with API-Version header

# Run integration tests
themisdb-test run --suite integration

# Check logs for errors
sudo journalctl -u themisdb --since "10 minutes ago" | grep -i error

5. Configuration Updates (Optional)

Enable new features in configuration:

# /etc/themisdb/config.yaml

# Enable API versioning (enabled by default)
api:
  versioning:
    enabled: true
    enforce_version_check: false  # Set to true to require version header

# Extended context window (if using LLM features)
llm:
  extended_context:
    enabled: true
    max_context_length: 32768
    rope_scaling_type: "yarn"

# Enhanced pagination
query:
  pagination:
    default_page_size: 100
    max_page_size: 10000
    cursor_ttl_seconds: 3600

Restart after configuration changes:

sudo systemctl restart themisdb

Code Changes Required

None Required for Basic Usage

Existing code continues to work without modifications. API versioning is optional.

Optional: Add Version Headers

REST API Clients

# Python
import requests

# Before (still works)
response = requests.get('http://localhost:8080/api/entities/123')

# After (recommended)
response = requests.get(
    'http://localhost:8080/api/entities/123',
    headers={'Accept-Version': 'v1.4.0'}
)

// JavaScript
// Before (still works)
const response = await fetch('http://localhost:8080/api/entities/123');

// After (recommended)
const response = await fetch('http://localhost:8080/api/entities/123', {
  headers: {
    'Accept-Version': 'v1.4.0'
  }
});

gRPC Clients

// C++
#include <grpcpp/grpcpp.h>

// Add version metadata
grpc::ClientContext context;
context.AddMetadata("api-version", "v1.4.0");

CreateRequest request;
CreateResponse response;
Status status = stub->Create(&context, request, &response);

// Go
import (
    "context"
    "google.golang.org/grpc/metadata"
)

// Add version metadata
md := metadata.Pairs("api-version", "v1.4.0")
ctx := metadata.NewOutgoingContext(context.Background(), md)

response, err := client.Create(ctx, &request)

Testing

Smoke Tests

# Health check
curl http://localhost:8080/api/health
# Expected: 200 OK

# Version check
curl http://localhost:8080/api/status | jq '.version'
# Expected: "1.4.1"

# Versioned request
curl -H "Accept-Version: v1.4.0" http://localhost:8080/api/health
# Expected: 200 OK with API-Version: v1.4.0 header

# Legacy request (no version header)
curl http://localhost:8080/api/health
# Expected: 200 OK with API-Version: v1.4.1 header (current version)

Integration Tests

# Run full test suite
themisdb-test run --suite all

# Run specific API tests
themisdb-test run --suite api

# Run version negotiation tests
themisdb-test run --test "test_api_version*"

Rollback Procedure

If issues occur:

# 1. Stop service
sudo systemctl stop themisdb

# 2. Restore v1.3.x binary
sudo cp /usr/local/bin/themisdb.backup /usr/local/bin/themisdb

# 3. Restore configuration (if changed)
sudo cp -r /etc/themisdb.backup.v1.3/* /etc/themisdb/

# 4. Restore database (if needed)
themisdb-backup restore /backups/themis-v1.3-*.tar.gz

# 5. Start service
sudo systemctl start themisdb

# 6. Verify
curl http://localhost:8080/api/status | jq '.version'
# Expected: "1.3.x"

Common Issues

Issue: "Unsupported API version" Warning

Symptom: Logs show warnings about unsupported API versions

Solution: This is informational only. The request still succeeds using the current version.

Issue: Performance Degradation

Symptom: Slower response times after upgrade

Solution:

1. Check extended context settings if using LLM features
2. Review pagination configuration
3. Monitor metrics dashboard

Issue: Deprecation Headers Appearing

Symptom: Responses include Deprecation headers

Solution: No immediate action required. Review Deprecation Registry and plan migration within 24 months.

Support

Documentation

• API Versioning
• Deprecation Registry
• CHANGELOG v1.4.x

Community

• GitHub Issues: https://github.com/makr-code/ThemisDB/issues
• Discussions: https://github.com/makr-code/ThemisDB/discussions
• Discord: https://discord.gg/themisdb

Professional Support

For enterprise customers: enterprise@themisdb.com

Next Steps

After successful migration:

1. Monitor - Watch metrics for 48 hours
2. Update Clients - Add version headers to client code
3. Review Deprecations - Check registry periodically
4. Plan v1.5 - Review roadmap for next version

Feedback

Found an issue? Please report:

• GitHub Issues: https://github.com/makr-code/ThemisDB/issues
• Email: support@themisdb.com