Open Dashboard

Start here

0.11.0 Migration Guide

Upgrade Typesense from 0.23.x to 0.24.x before you start Blnk v0.11.0.

This migration guide covers the breaking changes introduced in Blnk v0.11.0, specifically related to Typesense and search. The main change upgrades the Typesense server from version 0.23.x to 0.24.x, which requires updating your Docker configuration.

Breaking changes summary

  • From: Typesense 0.23.x
  • To: Typesense 0.24.x
  • Impact: Breaking changes in API compatibility and schema handling

Migration steps

Update Docker configuration

Update your Typesense server version in your Docker configuration files.

  1. For production (docker-compose.yaml)
typesense:
  image: typesense/typesense:0.24.0
  1. For development (docker-compose.dev.yaml)
typesense:
  image: typesense/typesense:0.24.0
  1. For Kubernetes (infrastructure/k8s-manifests/typesense-deployment.yaml)
containers:
  - image: typesense/typesense:0.24.0

Replace typesense/typesense:0.23.1 in each file. v0.10.x and earlier used 0.23.1. v0.11.0 uses 0.24.0.

Allow automatic schema migration

The new version includes automatic schema migration. When you start Blnk v0.11.0, it will automatically:

  1. Detect existing collections in your Typesense instance.
  2. Compare schemas between your current collections and the latest schema definitions.
  3. Add new fields to existing collections without data loss.
  4. Create missing collections with the latest schema.

Collections affected:

  • ledgers
  • balances
  • transactions
  • reconciliations
  • identities

Schema improvements

  1. Ledgers collection:
    • Enhanced metadata handling with object type support.
    • Improved nested field support.
  2. Balances collection:
    • All balance fields now use string type for precise decimal handling.
    • Enhanced metadata object support.
    • Improved nested field capabilities.
  3. Transactions collection:
    • precise_amount field uses string type for exact decimal precision.
    • Enhanced metadata object support.
    • Improved nested field capabilities.
  4. Reconciliations collection:
    • No breaking changes to existing fields.
    • Enhanced performance optimizations.
  5. Identities collection:
    • Enhanced metadata object support.
    • Improved nested field capabilities.

Start Blnk v0.11.0

Start your updated Blnk instance. The system handles data migration automatically, including:

  1. Large number conversion: Automatically converts big.Int values to strings for Typesense compatibility.
  2. Metadata normalization: Handles metadata field normalization for object schemas.
  3. Time field normalization: Ensures consistent timestamp formatting.

No manual intervention is required for data migration.

Configuration compatibility

  • Environment variables remain the same.
  • blnk.json configuration structure unchanged.
  • Search API endpoints unchanged.
  • Response formats remain compatible.
POST /search/{collection}

Testing checklist

After migration, verify the following:

  • Typesense server starts successfully.
  • All collections are accessible.
  • Search functionality works correctly.
  • Data integrity is maintained.
  • API endpoints respond correctly.
  • No errors in application logs.

Performance improvements

Blnk v0.11.0 includes several performance improvements:

  1. Enhanced search performance: Optimized query execution.
  2. Improved memory usage: Better resource management.
  3. Faster schema updates: Streamlined collection management.
  4. Better error handling: More robust error recovery.