Skip to content

Latest commit

 

History

History
231 lines (160 loc) · 5.55 KB

v1.2.3.md

File metadata and controls

231 lines (160 loc) · 5.55 KB

MygramDB v1.2.3 Release Notes

Release Date: 2025-11-20 Type: Minor Release (Feature Addition)

Overview

Version 1.2.3 adds two important features: configurable MySQL session timeout to prevent disconnection during long operations, and a C API for parsing web-style search expressions. This release enables better integration with external applications and improves stability for large-scale data synchronization.

What's New

1. Configurable MySQL Session Timeout

Problem: During long-running operations like large table synchronization or slow binlog processing, MySQL connections would timeout and disconnect, causing synchronization failures.

Solution: Added configurable session timeout settings that automatically configure MySQL's wait_timeout and interactive_timeout on connection.

Configuration:

replication:
  session_timeout_sec: 28800  # 8 hours (default)

Benefits:

  • Prevents unexpected disconnections during large table sync operations
  • Configurable timeout value to match your workload requirements
  • Automatically applies to both initial connection and reconnections
  • Default value (8 hours) suitable for most production scenarios

Use Cases:

  • Syncing tables with millions of rows
  • Slow network environments where binlog processing takes time
  • Batch processing scenarios requiring long-lived connections

Example:

# For very large tables requiring 24-hour sync operations
replication:
  session_timeout_sec: 86400  # 24 hours

# For faster environments with frequent reconnections
replication:
  session_timeout_sec: 3600   # 1 hour

2. C API for Parsing Web-Style Search Expressions

Feature: New public C API for parsing MygramDB search query syntax, enabling integration with other C/C++ applications.

API Function:

/**
 * Parse web-style search expression into structured query
 * @param expr Search expression string
 * @param table_name Target table name
 * @param out_query Output query structure (caller must free)
 * @return 0 on success, error code on failure
 */
int mygram_parse_search_expr(
    const char* expr,
    const char* table_name,
    mygram_query_t** out_query
);

Supported Syntax:

  • SEARCH "keywords" - Full-text search
  • FILTER col:value - Column filtering
  • SORT [-]field - Sort by field (- for descending)
  • LIMIT offset,count - Result pagination

Example Usage:

#include "mygram_api.h"

mygram_query_t* query = NULL;
int ret = mygram_parse_search_expr(
    "SEARCH \"hello world\" FILTER status:active SORT -created_at LIMIT 10",
    "articles",
    &query
);

if (ret == 0) {
    // Use parsed query structure
    // ...
    mygram_query_free(query);
}

Use Cases:

  • Integrating MygramDB search into existing C/C++ applications
  • Building custom search interfaces
  • Embedding MygramDB query parser in other systems
  • Query validation and preprocessing

Migration Guide

From v1.2.2

No breaking changes. This is a backward-compatible feature release.

Optional Configuration:

# Add to config.yaml if you need custom session timeout
replication:
  session_timeout_sec: 28800  # Default value, can be omitted

For C API Users:

// New header to include
#include "mygram_api.h"

// Link against libmygram when building
gcc your_app.c -lmygram -o your_app

Upgrade Steps

Docker users:

# Pull the new image
docker pull ghcr.io/libraz/mygram-db:v1.2.3

# Or update docker-compose.yml
services:
  mygramdb:
    image: ghcr.io/libraz/mygram-db:v1.2.3

RPM users:

# Download and install new RPM
sudo rpm -Uvh mygram-db-1.2.3-1.el9.x86_64.rpm

Source build:

git checkout v1.2.3
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

Technical Details

MySQL Session Timeout Implementation

Relevant Code:

  • src/data/mysql_connection.cpp - Connection initialization with timeout settings

Configuration Hierarchy:

  1. User-specified replication.session_timeout_sec
  2. Default: 28800 seconds (8 hours)
  3. Applied via SET SESSION wait_timeout=X, interactive_timeout=X

Behavior:

  • Setting is applied immediately after connection establishment
  • Applies to both initial connection and automatic reconnections
  • MySQL server must support session variable modification
  • Compatible with MySQL 8.0+

C API Architecture

Header File: include/mygram_api.h Implementation: src/api/mygram_api.cpp

Design Principles:

  • Pure C interface for maximum compatibility
  • No C++ exceptions crossing API boundary
  • Caller-owned memory with explicit free functions
  • Error codes for all failure modes

Error Codes:

#define MYGRAM_OK              0
#define MYGRAM_ERR_PARSE       1  // Query syntax error
#define MYGRAM_ERR_INVALID_ARG 2  // NULL pointer or invalid argument
#define MYGRAM_ERR_NOMEM       3  // Memory allocation failure

Performance Impact

Negligible overhead:

  • Session timeout: One-time SET SESSION command per connection
  • C API: Zero overhead (direct calls to existing parser)

No changes to:

  • Query execution performance
  • Binlog processing throughput
  • Memory usage patterns

Known Issues

None.

Contributors

  • @libraz

Links

Questions or Issues? Please open an issue on GitHub Issues