sqlite-sync-core 0.2.0__tar.gz → 0.5.1__tar.gz

sqlite_sync_core-0.5.1/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: sqlite-sync-core
+Version: 0.5.1
+Summary: Universal SQLite Synchronization Core - A dependency-grade, local-first, offline-first SQLite synchronization primitive
+License: AGPL-3.0
+Project-URL: Homepage, https://github.com/shivay00001/sqlite-sync-core
+Project-URL: Documentation, https://github.com/shivay00001/sqlite-sync-core#readme
+Project-URL: Repository, https://github.com/shivay00001/sqlite-sync-core.git
+Project-URL: Issues, https://github.com/shivay00001/sqlite-sync-core/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: msgpack>=1.0.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: server
+Requires-Dist: flask>=3.0.0; extra == "server"
+Provides-Extra: crypto
+Requires-Dist: cryptography>=41.0.0; extra == "crypto"
+Provides-Extra: all
+Requires-Dist: flask>=3.0.0; extra == "all"
+Requires-Dist: cryptography>=41.0.0; extra == "all"
+Dynamic: license-file
+
+# sqlite-sync-core
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![PyPI](https://img.shields.io/pypi/v/sqlite-sync-core.svg)](https://pypi.org/project/sqlite-sync-core/)
+[![Status: Production Grade](https://img.shields.io/badge/status-production--grade-brightgreen.svg)](https://github.com/shivay00001/sqlite-sync-core)
+
+**A production-grade, turn-key synchronization system for SQLite.**
+
+`sqlite-sync-core` provides a powerful, local-first synchronization engine that works seamlessly across multi-peer networks. It handles the "hard parts" of sync (vector clocks, causality, delta bundles, and conflict resolution) while providing a simple, turn-key interface for developers.
+
+---
+
+## 🚀 Turn-Key Synchronization
+
+You can launch a full synchronization node in one command. No infrastructure required.
+
+### 16-Second Setup (CLI)
+
+```bash
+# Install the package
+pip install sqlite-sync-core
+
+# Start a node and sync the 'tasks' table automatically
+sqlite-sync start --db app.db --name Device-A --tables tasks
+```
+
+### Automatic Multi-Peer Sync
+
+Nodes automatically discover each other on the local network (P2P) and synchronize state in the background without any manual peer configuration.
+
+---
+
+## 🏗️ Enterprise Features
+
+- **Multi-Peer Orchestration**: Automatically scales sync across N devices.
+- **P2P Discovery**: Zero-config peer-to-peer discovery on LAN.
+- **Automatic Resolution**: Configurable strategies like Last-Write-Wins and Field-Level Merge.
+- **Schema Evolution**: Built-in migrations that sync across the network.
+- **Transport Agnostic**: Works over HTTP, WebSockets, or file transfer.
+
+---
+
+## Technical Usage (Library)
+
+### Initialize a Node in Code
+
+```python
+from sqlite_sync import SyncNode
+
+node = SyncNode(
+    db_path="app.db",
+    device_name="MobileApp",
+    sync_interval=10  # Sync every 10 seconds
+)
+
+await node.start()
+node.enable_sync_for_table("users")
+```
+
+### Safe Schema Migrations
+
+```bash
+# Safely add a column that will sync to all other peers
+sqlite-sync migrate --db app.db --table tasks --add-column priority --type INTEGER
+```
+
+---
+
+## Core Invariants
+
+| # | Invariant | Description |
+|---|-----------|-------------|
+| 1 | **Causal consistency** | Vector clocks ensure the correct order of operations. |
+| 2 | **Deterministic Replay** | Identical sets of operations always result in identical state. |
+| 3 | **Conflict Tolerance** | Detects and resolves conflicts explicitly and safely. |
+| 4 | **Offline-First** | Entirely local-first design; works without cloud or internet. |
+
+### 2. Generate a Delta Bundle
+
+```python
+# To be sent to Peer B
+bundle_path = engine.generate_bundle(
+    peer_device_id=peer_b_id,
+    output_path="delta.db"
+)
+```
+
+### 3. Import and Detect Conflicts
+
+```python
+# On Peer B
+result = engine.import_bundle("delta.db")
+
+print(f"Ops Applied: {result.applied_count}")
+print(f"Conflicts Detected: {result.conflict_count}")
+```
+
+---
+
+## Core Invariants
+
+| # | Invariant | Description |
+|---|-----------|-------------|
+| 1 | **Append-only** | Operation history is immutable. |
+| 2 | **Causal consistency** | Hybrid Logical Clocks (HLC) ensure correct partial ordering and wall-clock correlation. |
+| 3 | **Deterministic** | Replay results are identical across all replicas. |
+| 4 | **Field-Level Merge** | "Smart" LWW resolution merges concurrent non-conflicting field updates. |
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────┐
+│     Your Sync System / App      │
+└───────────────┬─────────────────┘
+                │ Uses
+┌───────────────▼─────────────────┐
+│       sqlite-sync-core          │
+│  (Logging, Bundling, Clocks)    │
+└───────────────┬─────────────────┘
+                │ Persists to
+┌───────────────▼─────────────────┐
+│         SQLite Database         │
+└─────────────────────────────────┘
+```
+
+---
+
+## License
+
+**AGPL-3.0** for Open Source.
+Contact <shivaysinghrajput@proton.me> for commercial licensing.
+
+---
+
+**Built for developers who need a reliable sync foundation.**

sqlite_sync_core-0.5.1/README.md

@@ -0,0 +1,138 @@
+# sqlite-sync-core
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![PyPI](https://img.shields.io/pypi/v/sqlite-sync-core.svg)](https://pypi.org/project/sqlite-sync-core/)
+[![Status: Production Grade](https://img.shields.io/badge/status-production--grade-brightgreen.svg)](https://github.com/shivay00001/sqlite-sync-core)
+
+**A production-grade, turn-key synchronization system for SQLite.**
+
+`sqlite-sync-core` provides a powerful, local-first synchronization engine that works seamlessly across multi-peer networks. It handles the "hard parts" of sync (vector clocks, causality, delta bundles, and conflict resolution) while providing a simple, turn-key interface for developers.
+
+---
+
+## 🚀 Turn-Key Synchronization
+
+You can launch a full synchronization node in one command. No infrastructure required.
+
+### 16-Second Setup (CLI)
+
+```bash
+# Install the package
+pip install sqlite-sync-core
+
+# Start a node and sync the 'tasks' table automatically
+sqlite-sync start --db app.db --name Device-A --tables tasks
+```
+
+### Automatic Multi-Peer Sync
+
+Nodes automatically discover each other on the local network (P2P) and synchronize state in the background without any manual peer configuration.
+
+---
+
+## 🏗️ Enterprise Features
+
+- **Multi-Peer Orchestration**: Automatically scales sync across N devices.
+- **P2P Discovery**: Zero-config peer-to-peer discovery on LAN.
+- **Automatic Resolution**: Configurable strategies like Last-Write-Wins and Field-Level Merge.
+- **Schema Evolution**: Built-in migrations that sync across the network.
+- **Transport Agnostic**: Works over HTTP, WebSockets, or file transfer.
+
+---
+
+## Technical Usage (Library)
+
+### Initialize a Node in Code
+
+```python
+from sqlite_sync import SyncNode
+
+node = SyncNode(
+    db_path="app.db",
+    device_name="MobileApp",
+    sync_interval=10  # Sync every 10 seconds
+)
+
+await node.start()
+node.enable_sync_for_table("users")
+```
+
+### Safe Schema Migrations
+
+```bash
+# Safely add a column that will sync to all other peers
+sqlite-sync migrate --db app.db --table tasks --add-column priority --type INTEGER
+```
+
+---
+
+## Core Invariants
+
+| # | Invariant | Description |
+|---|-----------|-------------|
+| 1 | **Causal consistency** | Vector clocks ensure the correct order of operations. |
+| 2 | **Deterministic Replay** | Identical sets of operations always result in identical state. |
+| 3 | **Conflict Tolerance** | Detects and resolves conflicts explicitly and safely. |
+| 4 | **Offline-First** | Entirely local-first design; works without cloud or internet. |
+
+### 2. Generate a Delta Bundle
+
+```python
+# To be sent to Peer B
+bundle_path = engine.generate_bundle(
+    peer_device_id=peer_b_id,
+    output_path="delta.db"
+)
+```
+
+### 3. Import and Detect Conflicts
+
+```python
+# On Peer B
+result = engine.import_bundle("delta.db")
+
+print(f"Ops Applied: {result.applied_count}")
+print(f"Conflicts Detected: {result.conflict_count}")
+```
+
+---
+
+## Core Invariants
+
+| # | Invariant | Description |
+|---|-----------|-------------|
+| 1 | **Append-only** | Operation history is immutable. |
+| 2 | **Causal consistency** | Hybrid Logical Clocks (HLC) ensure correct partial ordering and wall-clock correlation. |
+| 3 | **Deterministic** | Replay results are identical across all replicas. |
+| 4 | **Field-Level Merge** | "Smart" LWW resolution merges concurrent non-conflicting field updates. |
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────┐
+│     Your Sync System / App      │
+└───────────────┬─────────────────┘
+                │ Uses
+┌───────────────▼─────────────────┐
+│       sqlite-sync-core          │
+│  (Logging, Bundling, Clocks)    │
+└───────────────┬─────────────────┘
+                │ Persists to
+┌───────────────▼─────────────────┐
+│         SQLite Database         │
+└─────────────────────────────────┘
+```
+
+---
+
+## License
+
+**AGPL-3.0** for Open Source.
+Contact <shivaysinghrajput@proton.me> for commercial licensing.
+
+---
+
+**Built for developers who need a reliable sync foundation.**

{sqlite_sync_core-0.2.0 → sqlite_sync_core-0.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sqlite-sync-core"
-version = "0.2.0"
+version = "0.5.1"
 description = "Universal SQLite Synchronization Core - A dependency-grade, local-first, offline-first SQLite synchronization primitive"
 readme = "README.md"
 license = {text = "AGPL-3.0"}
@@ -50,6 +50,9 @@ all = [
     "cryptography>=41.0.0",
 ]
 
+[project.scripts]
+sqlite-sync = "sqlite_sync.cli.main:main"
+
 [tool.setuptools.packages.find]
 where = ["src"]
 

sqlite_sync_core-0.5.1/src/sqlite_sync/__init__.py

@@ -0,0 +1,117 @@
+"""
+sqlite_sync - Universal SQLite Synchronization Core
+
+A dependency-grade, local-first, offline-first SQLite synchronization primitive.
+Enterprise-ready with authentication, metrics, peer discovery, and enhanced security.
+"""
+
+from sqlite_sync.engine import SyncEngine
+from sqlite_sync.errors import (
+    SyncError,
+    SchemaError,
+    BundleError,
+    ConflictError,
+    InvariantViolationError,
+)
+
+# Core
+__version__ = "0.5.1"
+__all__ = [
+    # Core
+    "SyncEngine",
+    # Errors
+    "SyncError",
+    "SchemaError",
+    "BundleError",
+    "ConflictError",
+    "InvariantViolationError",
+]
+
+# Enterprise: SyncNode (full orchestration)
+try:
+    from sqlite_sync.ext.node import SyncNode
+    __all__.append("SyncNode")
+except ImportError:
+    pass
+
+# Enterprise: P2P Discovery
+try:
+    from sqlite_sync.network.peer_discovery import (
+        UDPDiscovery,
+        PeerManager,
+        Peer,
+        PeerStatus,
+        DiscoveryConfig,
+        create_discovery,
+    )
+    __all__.extend([
+        "UDPDiscovery",
+        "PeerManager", 
+        "Peer",
+        "PeerStatus",
+        "DiscoveryConfig",
+        "create_discovery",
+    ])
+except ImportError:
+    pass
+
+# Enterprise: Conflict Resolution
+try:
+    from sqlite_sync.resolution import (
+        ResolutionStrategy,
+        ConflictResolver,
+        ConflictContext,
+        ResolutionResult,
+        get_resolver,
+        LastWriteWinsResolver,
+        FieldMergeResolver,
+    )
+    __all__.extend([
+        "ResolutionStrategy",
+        "ConflictResolver",
+        "ConflictContext",
+        "ResolutionResult",
+        "get_resolver",
+        "LastWriteWinsResolver",
+        "FieldMergeResolver",
+    ])
+except ImportError:
+    pass
+
+# Enterprise: Schema Evolution
+try:
+    from sqlite_sync.schema_evolution import SchemaManager, SchemaMigration
+    __all__.extend(["SchemaManager", "SchemaMigration"])
+except ImportError:
+    pass
+
+# Optional enterprise imports (fail gracefully if deps missing)
+try:
+    from sqlite_sync.metrics import (
+        get_registry,
+        sync_operations_total,
+        sync_conflicts_total,
+        sync_latency_seconds,
+        configure_logging,
+        SyncLogger,
+        HealthChecker,
+        get_health_checker,
+    )
+    __all__.extend([
+        "get_registry",
+        "sync_operations_total", 
+        "sync_conflicts_total",
+        "sync_latency_seconds",
+        "configure_logging",
+        "SyncLogger",
+        "HealthChecker",
+        "get_health_checker",
+    ])
+except ImportError:
+    pass
+
+try:
+    from sqlite_sync.security import SecurityManager, DeviceIdentity
+    __all__.extend(["SecurityManager", "DeviceIdentity"])
+except ImportError:
+    pass

{sqlite_sync_core-0.2.0 → sqlite_sync_core-0.5.1}/src/sqlite_sync/bundle/generate.py

@@ -5,6 +5,7 @@ Generates a bundle containing operations that a peer hasn't seen.
 Bundles are self-contained SQLite files.
 """
 
+import os
 import sqlite3
 import time
 from typing import Final
@@ -56,6 +57,8 @@ def generate_bundle(
     
     # Create bundle database
     try:
+        if os.path.exists(output_path):
+            os.remove(output_path)
         bundle_conn = sqlite3.connect(output_path)
         
         # Create bundle schema
@@ -66,10 +69,10 @@ def generate_bundle(
         bundle_conn.executemany(
             """
             INSERT INTO bundle_operations (
-                op_id, device_id, parent_op_id, vector_clock,
+                op_id, device_id, parent_op_id, vector_clock, hlc,
                 table_name, op_type, row_pk, old_values, new_values,
                 schema_version, created_at, is_local, applied_at
-            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
             """,
             operations,
         )

sqlite_sync_core-0.5.1/src/sqlite_sync/cli/__init__.py

@@ -0,0 +1,7 @@
+"""
+cli - Command Line Interface for sqlite-sync-core.
+"""
+
+from sqlite_sync.ext.cli.main import main, CLIManager
+
+__all__ = ["main", "CLIManager"]

sqlite_sync_core-0.5.1/src/sqlite_sync/cli/main.py

@@ -0,0 +1,12 @@
+"""
+cli/main.py - Entry point for sqlite-sync CLI.
+
+Re-exports the CLI from ext/cli/main.py for pyproject.toml compatibility.
+"""
+
+from sqlite_sync.ext.cli.main import main, CLIManager
+
+__all__ = ["main", "CLIManager"]
+
+if __name__ == "__main__":
+    main()

{sqlite_sync_core-0.2.0 → sqlite_sync_core-0.5.1}/src/sqlite_sync/db/connection.py

@@ -7,9 +7,14 @@ registration of application-defined SQL functions.
 All connections use WAL mode for concurrent read/write.
 """
 
+import logging
 import sqlite3
-from typing import Callable, Any
+import json
+import time
+
+logger = logging.getLogger("sqlite_sync.db")
 
+from typing import Callable, Any
 from sqlite_sync.config import SQLITE_PRAGMAS
 from sqlite_sync.errors import DatabaseError
 
@@ -85,32 +90,62 @@ def _register_functions(conn: sqlite3.Connection) -> None:
     from sqlite_sync.log.vector_clock import increment_vector_clock, merge_vector_clocks
     from sqlite_sync.utils.msgpack_codec import pack_primary_key, pack_dict
     import json
+    import sys
 
     # sync_uuid_v7() -> BLOB(16)
-    conn.create_function("sync_uuid_v7", 0, generate_uuid_v7)
+    def _uuid_v7() -> bytes:
+        return generate_uuid_v7()
+
+    conn.create_function("sync_uuid_v7", 0, _uuid_v7)
 
     # sync_vector_clock_increment(device_id BLOB, vc_json TEXT) -> TEXT
-    def _vc_increment(device_id: bytes, vc_json: str) -> str:
+    def _vc_increment(device_id: Any, vc_json: Any) -> str:
         return increment_vector_clock(device_id, vc_json)
 
     conn.create_function("sync_vector_clock_increment", 2, _vc_increment)
 
     # sync_vector_clock_merge(vc1_json TEXT, vc2_json TEXT) -> TEXT
-    def _vc_merge(vc1_json: str, vc2_json: str) -> str:
+    def _vc_merge(vc1_json: Any, vc2_json: Any) -> str:
         return merge_vector_clocks(vc1_json, vc2_json)
 
     conn.create_function("sync_vector_clock_merge", 2, _vc_merge)
 
     # sync_pack_pk(value) -> BLOB
-    conn.create_function("sync_pack_pk", 1, pack_primary_key)
+    def _pack_pk(value: Any) -> bytes:
+        return pack_primary_key(value)
+
+    conn.create_function("sync_pack_pk", 1, _pack_pk)
 
     # sync_pack_values(json_str TEXT) -> BLOB
-    def _pack_values(json_str: str) -> bytes:
+    def _pack_values(json_str: Any) -> bytes:
+        if not json_str: return b""
         data = json.loads(json_str)
         return pack_dict(data)
 
     conn.create_function("sync_pack_values", 1, _pack_values)
 
+    # sync_hlc_now(node_id TEXT) -> TEXT
+    def _hlc_now_placeholder(node_id: Any) -> str:
+        return f"{int(time.time() * 1000)}:0:{node_id}"
+
+    conn.create_function("sync_hlc_now", 1, _hlc_now_placeholder)
+
+    if not hasattr(_register_functions, "_disabled_state"):
+        _register_functions._disabled_state = {}
+
+    def _sync_is_disabled() -> int:
+        return _register_functions._disabled_state.get(id(conn), 0)
+
+    conn.create_function("sync_is_disabled", 0, _sync_is_disabled)
+
+
+def set_sync_disabled(conn: sqlite3.Connection, disabled: bool) -> None:
+    """Set the sync-disabled state for a specific connection."""
+    val = 1 if disabled else 0
+    if not hasattr(_register_functions, "_disabled_state"):
+        _register_functions._disabled_state = {}
+    _register_functions._disabled_state[id(conn)] = val
+
 
 def execute_in_transaction(
     conn: sqlite3.Connection, 

{sqlite_sync_core-0.2.0 → sqlite_sync_core-0.5.1}/src/sqlite_sync/db/migrations.py

@@ -49,10 +49,13 @@ def initialize_sync_tables(conn: sqlite3.Connection) -> bytes:
             for sql in statement.strip().split(";"):
                 sql = sql.strip()
                 if sql:
+                    # print(f"DEBUG: Executing SQL: {sql}")
                     conn.execute(sql)
     except sqlite3.Error as e:
+        # Get the failing SQL if possible
+        failed_sql = locals().get('sql', 'unknown')
         raise DatabaseError(
-            f"Failed to create sync tables: {e}",
+            f"Failed to create sync tables: {e} (SQL: {failed_sql})",
             operation="create_tables",
         ) from e