Cache Migration Guide
Overview
This guide explains how to enable caching on an existing Hass-MCP installation, migrate between backends, and update configuration.
Enabling Caching on Existing Installation
Step 1: Verify Current Configuration
Check if caching is already enabled:
Step 2: Enable Caching (if disabled)
Or in configuration file:
Step 3: Choose Backend
Select appropriate backend based on your use case:
Memory Backend (Default):
Redis Backend:
File Backend:
Step 4: Verify Caching is Working
from app.api.system import get_cache_statistics
stats = await get_cache_statistics()
print(f"Cache enabled: {stats['enabled']}")
print(f"Backend: {stats['backend']}")
Backend Migration
Migrating from Memory to Redis
Step 1: Install Redis package:
Step 2: Start Redis server:
# Using Docker
docker run -d -p 6379:6379 redis:latest
# Or install Redis locally
# (See Redis documentation for your OS)
Step 3: Update configuration:
Step 4: Restart Hass-MCP:
Step 5: Verify migration:
from app.core.cache.manager import get_cache_manager
manager = await get_cache_manager()
backend = await manager._get_backend()
print(f"Backend: {backend.__class__.__name__}")
# Should be RedisCacheBackend
Migrating from Memory to File
Step 1: Install aiofiles package:
Step 2: Create cache directory:
Step 3: Update configuration:
Step 4: Restart Hass-MCP:
Step 5: Verify migration:
from app.core.cache.manager import get_cache_manager
manager = await get_cache_manager()
backend = await manager._get_backend()
print(f"Backend: {backend.__class__.__name__}")
# Should be FileCacheBackend
Migrating from File to Redis
Step 1: Install Redis package:
Step 2: Start Redis server:
Step 3: Update configuration:
Step 4: Restart Hass-MCP:
Note: Cache data from file backend is not automatically migrated. Cache will be rebuilt as endpoints are called.
Migrating from Redis to File
Step 1: Install aiofiles package:
Step 2: Create cache directory:
Step 3: Update configuration:
Step 4: Restart Hass-MCP:
Note: Cache data from Redis is not automatically migrated. Cache will be rebuilt as endpoints are called.
Configuration Migration
Migrating from Environment Variables to Configuration File
Step 1: Create configuration file:
{
"enabled": true,
"backend": "memory",
"default_ttl": 300,
"max_size": 1000,
"endpoints": {
"entities": {
"get_state": {
"ttl": 60
}
}
}
}
Step 2: Specify configuration file:
Step 3: Remove environment variables (optional):
# Environment variables still take precedence
# But you can remove them if using config file
unset HASS_MCP_CACHE_BACKEND
unset HASS_MCP_CACHE_DEFAULT_TTL
Migrating from Configuration File to Environment Variables
Step 1: Export environment variables:
export HASS_MCP_CACHE_ENABLED=true
export HASS_MCP_CACHE_BACKEND=memory
export HASS_MCP_CACHE_DEFAULT_TTL=300
export HASS_MCP_CACHE_MAX_SIZE=1000
Step 2: Remove configuration file (optional):
Note: Environment variables take precedence over configuration files.
TTL Configuration Migration
Updating TTL Values
Step 1: Update configuration file:
Step 2: Reload configuration:
Step 3: Verify TTL:
from app.core.cache.config import get_cache_config
config = get_cache_config()
ttl = config.get_endpoint_ttl("entities", "get_state")
print(f"TTL: {ttl} seconds")
Cache Data Migration
Manual Cache Migration
Cache data is not automatically migrated between backends. To migrate:
Step 1: Export cache data (if needed):
from app.core.cache.manager import get_cache_manager
manager = await get_cache_manager()
keys = await manager.keys()
# Export cache data
cache_data = {}
for key in keys:
value = await manager.get(key)
if value is not None:
cache_data[key] = value
# Save to file
import json
with open("cache_export.json", "w") as f:
json.dump(cache_data, f)
Step 2: Import cache data (if needed):
from app.core.cache.manager import get_cache_manager
import json
manager = await get_cache_manager()
# Load from file
with open("cache_export.json", "r") as f:
cache_data = json.load(f)
# Import cache data
for key, value in cache_data.items():
await manager.set(key, value, ttl=300)
Note: Manual migration is usually not necessary. Cache will rebuild automatically as endpoints are called.
Rollback Procedures
Rollback to Previous Backend
Step 1: Update configuration:
Step 2: Restart Hass-MCP:
Step 3: Verify rollback:
from app.core.cache.manager import get_cache_manager
manager = await get_cache_manager()
backend = await manager._get_backend()
print(f"Backend: {backend.__class__.__name__}")
Disable Caching
Step 1: Disable caching:
Step 2: Restart Hass-MCP:
Step 3: Verify caching is disabled:
from app.api.system import get_cache_statistics
stats = await get_cache_statistics()
print(f"Cache enabled: {stats['enabled']}")
# Should be False
Best Practices
- Test migration in development first
- Backup configuration before migration
- Monitor cache performance after migration
- Verify cache is working correctly
- Keep old configuration as backup
Troubleshooting Migration
Migration Issues
If migration fails:
- Check logs for errors
- Verify backend is available (Redis, file system)
- Check permissions (file backend)
- Verify configuration is correct
- Rollback to previous configuration if needed
Cache Not Working After Migration
-
Verify backend is initialized:
-
Check cache statistics:
-
Clear cache and rebuild: