Migration Guide¶

Migrating from v2.x to v3.x¶

CloudSync SDK v3.0 introduced several breaking changes to improve consistency and performance.

Breaking Changes¶

1. Client initialization¶

# v2.x (deprecated)
from cloudsync import SyncClient
client = SyncClient(token="...")

# v3.x
from cloudsync import CloudSyncClient
client = CloudSyncClient(api_key="...")

2. Document API¶

# v2.x
doc.put("field", "value")
doc.remove("field")

# v3.x
doc.update("field", "value")
doc.delete("field")

3. Event names¶

v2.x	v3.x
`on_update`	`change`
`on_sync_complete`	`sync`
`on_conflict`	`conflict`
`on_error`	`error`

4. Configuration file format¶

The configuration file changed from cloudsync.json to cloudsync.yml:

# Auto-convert your config
python -m cloudsync migrate-config cloudsync.json
# Creates cloudsync.yml

5. Storage backend DSN¶

# v2.x
client = SyncClient(db_url="postgres://...")

# v3.x
client = CloudSyncClient(storage_backend="postgres", storage_dsn="postgresql://...")

New Features in v3.x¶

Async client (AsyncCloudSyncClient)
CRDT data types (Counter, Register, Set)
Collection queries
Scoped tokens
gRPC and MQTT transports
Configuration file with env var interpolation

Migration Checklist¶

[ ] Update import: SyncClient → CloudSyncClient
[ ] Update token= → api_key=
[ ] Rename put() → update(), remove() → delete()
[ ] Update event listener names
[ ] Migrate config from JSON to YAML
[ ] Update storage DSN format
[ ] Test with cs_test_ key before deploying

Next: FAQ →