Configuration

CloudSync SDK can be configured via constructor arguments, environment variables, or a YAML configuration file.

Precedence Order

1. Constructor arguments (highest priority)
2. Environment variables
3. Configuration file (cloudsync.yml)
4. Built-in defaults (lowest priority)

Constructor Arguments

from cloudsync import CloudSyncClient

client = CloudSyncClient(
    api_key="cs_live_...",
    region="us-east-1",
    transport="websocket",
    storage_backend="sqlite",
    storage_path="./data/cloudsync.db",
    max_retries=5,
    retry_backoff=1.5,
    timeout=30,
    heartbeat_interval=15,
    encryption_key="base64-encoded-aes-key",
    log_level="INFO",
    batch_size=100,
    compression=True,
)

Environment Variables

Variable	Description	Default
CLOUDSYNC_API_KEY	API key for authentication	— (required)
CLOUDSYNC_REGION	Datacenter region	us-east-1
CLOUDSYNC_TRANSPORT	Transport protocol	websocket
CLOUDSYNC_STORAGE_BACKEND	Local storage adapter	sqlite
CLOUDSYNC_STORAGE_PATH	Path for local database	./cloudsync.db
CLOUDSYNC_MAX_RETRIES	Max reconnection attempts	10
CLOUDSYNC_TIMEOUT	Request timeout (seconds)	30
CLOUDSYNC_LOG_LEVEL	Logging verbosity	WARNING
CLOUDSYNC_ENCRYPTION_KEY	E2E encryption key (base64)	— (optional)
CLOUDSYNC_COMPRESSION	Enable payload compression	true

Configuration File

Create cloudsync.yml in your project root:

api_key: ${CLOUDSYNC_API_KEY}  # supports env var interpolation
region: us-east-1

transport:
  protocol: websocket
  heartbeat_interval: 15
  compression: true

storage:
  backend: sqlite
  path: ./data/cloudsync.db
  wal_mode: true

sync:
  batch_size: 100
  max_retries: 10
  retry_backoff: 1.5
  conflict_strategy: last-write-wins  # last-write-wins | manual | custom

encryption:
  enabled: true
  algorithm: aes-256-gcm
  key_rotation_interval: 86400  # seconds

logging:
  level: INFO
  format: json
  output: stderr

Load it explicitly:

client = CloudSyncClient.from_config("./cloudsync.yml")

Storage Backends

SQLite (default)

client = CloudSyncClient(
    api_key="...",
    storage_backend="sqlite",
    storage_path="./data/sync.db"
)

PostgreSQL

client = CloudSyncClient(
    api_key="...",
    storage_backend="postgres",
    storage_dsn="postgresql://user:pass@localhost:5432/cloudsync"
)

Redis

client = CloudSyncClient(
    api_key="...",
    storage_backend="redis",
    storage_dsn="redis://localhost:6379/0"
)

Custom Adapter

from cloudsync.storage import StorageAdapter

class MyCustomStorage(StorageAdapter):
    def get(self, key: str) -> dict | None:
        ...

    def set(self, key: str, value: dict) -> None:
        ...

    def delete(self, key: str) -> None:
        ...

    def list_keys(self, prefix: str = "") -> list[str]:
        ...

client = CloudSyncClient(
    api_key="...",
    storage_backend=MyCustomStorage()
)

Conflict Resolution Strategies

Strategy	Behavior
last-write-wins	Timestamp-based, most recent write wins (default)
first-write-wins	Earliest write is preserved
manual	Emits conflict event for application-level resolution
custom	User-provided merge function

from cloudsync import CloudSyncClient, ConflictStrategy

def custom_merge(field, local_value, remote_value, metadata):
    # Example: prefer longer strings, higher numbers
    if isinstance(local_value, str) and isinstance(remote_value, str):
        return local_value if len(local_value) >= len(remote_value) else remote_value
    return remote_value

client = CloudSyncClient(
    api_key="...",
    conflict_strategy=ConflictStrategy.CUSTOM,
    conflict_resolver=custom_merge
)

---

Next: API Reference →