Skip to content

Data Synchronization

This guide explains how to create and manage data synchronization sessions with PinkCloudSync.

Overview

A sync session transfers data between a source and target system1. The process includes:

  1. Creating a session with source and target configuration
  2. Monitoring the synchronization progress
  3. Handling any conflicts that arise
  4. Reviewing the results
graph LR
    A[Create Session] --> B[Data Reading]
    B --> C[Processing]
    C --> D{Conflicts?}
    D -->|Yes| E[Resolve]
    D -->|No| F[Write Data]
    E --> F
    F --> G[Complete]

Setup Checklist

Complete these steps before creating your first sync session:

  • Obtain API credentials and authenticate
  • Identify source and target systems
  • Verify network connectivity between systems
  • Determine conflict resolution strategy
  • Plan data filters and batch size
  • Set up monitoring and alerts

Creating a Sync Session

Basic Example

Create a simple sync session between two databases:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
curl -X POST https://api.pinkcloudsync.example/v1/sync/sessions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "database",
      "connection": {
        "host": "source-db.example.com",
        "port": 5432,
        "database": "production",
        "username": "sync_user",
        "password": "secure_password"
      }
    },
    "target": {
      "type": "database",
      "connection": {
        "host": "target-db.example.com",
        "port": 5432,
        "database": "backup",
        "username": "sync_user",
        "password": "secure_password"
      }
    }
  }'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
import requests

url = "https://api.pinkcloudsync.example/v1/sync/sessions"

headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

payload = {
    "source": {
        "type": "database",
        "connection": {
            "host": "source-db.example.com",
            "port": 5432,
            "database": "production",
            "username": "sync_user",
            "password": "secure_password"
        }
    },
    "target": {
        "type": "database",
        "connection": {
            "host": "target-db.example.com",
            "port": 5432,
            "database": "backup",
            "username": "sync_user",
            "password": "secure_password"
        }
    }
}

response = requests.post(url, headers=headers, json=payload)
session = response.json()

print(f"Session created: {session['id']}")
print(f"Status: {session['status']}")

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "source": {
    "type": "database",
    "connection": {
      "host": "source-db.example.com",
      "database": "production"
    }
  },
  "target": {
    "type": "database",
    "connection": {
      "host": "target-db.example.com",
      "database": "backup"
    }
  },
  "statistics": {
    "total_records": 0,
    "synced_records": 0,
    "failed_records": 0,
    "conflicts": 0
  },
  "created_at": "2025-01-03T10:00:00Z",
  "updated_at": "2025-01-03T10:00:00Z"
}

Session Created

The session is created with status pending and will automatically start processing.

Configuration Options

Conflict Strategy

Specify how to handle conflicts:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
curl -X POST https://api.pinkcloudsync.example/v1/sync/sessions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { /* ... */ },
    "target": { /* ... */ },
    "options": {
      "conflict_strategy": "newest_wins"
    }
  }'

1
2
3
4
5
6
7
payload = {
    "source": { /* ... */ },
    "target": { /* ... */ },
    "options": {
        "conflict_strategy": "newest_wins"
    }
}

Available strategies:

Strategy Description
manual Save conflicts for manual resolution (default)
source_wins Always use source data
target_wins Always use target data
newest_wins Use the most recent version

Batch Size

Control how many records are processed at once:

1
2
3
4
5
{
  "options": {
    "batch_size": 500
  }
}
  • Default: 100 records
  • Range: 1-1000 records
  • Recommendation: Use larger batches (500-1000) for better performance

Filters

Limit which data is synchronized:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
curl -X POST https://api.pinkcloudsync.example/v1/sync/sessions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "database",
      "connection": { /* ... */ },
      "filters": {
        "table": "users",
        "where": "created_at > '\''2025-01-01'\''",
        "columns": ["id", "name", "email"]
      }
    },
    "target": { /* ... */ }
  }'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
payload = {
    "source": {
        "type": "database",
        "connection": { /* ... */ },
        "filters": {
            "table": "users",
            "where": "created_at > '2025-01-01'",
            "columns": ["id", "name", "email"]
        }
    },
    "target": { /* ... */ }
}

Managing Sessions

List All Sessions

Retrieve all sync sessions:

1
2
curl -X GET "https://api.pinkcloudsync.example/v1/sync/sessions?status=in_progress&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import requests

url = "https://api.pinkcloudsync.example/v1/sync/sessions"

headers = {
    "Authorization": f"Bearer {access_token}"
}

params = {
    "status": "in_progress",
    "limit": 20,
    "offset": 0
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

print(f"Total sessions: {data['total']}")
for session in data['sessions']:
    print(f"- {session['id']}: {session['status']}")

Cancel a Session

Stop an active sync session:

1
2
curl -X DELETE https://api.pinkcloudsync.example/v1/sync/sessions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import requests

session_id = "550e8400-e29b-41d4-a716-446655440000"
url = f"https://api.pinkcloudsync.example/v1/sync/sessions/{session_id}"

headers = {
    "Authorization": f"Bearer {access_token}"
}

response = requests.delete(url, headers=headers)

if response.status_code == 204:
    print("Session cancelled successfully")

Cancellation

Cancelling a session stops the synchronization immediately. Already synced data will not be rolled back.

Error Handling

Common Errors

Connection Failed

Cause: Cannot connect to source or target

Solution: * Verify connection parameters * Check network connectivity * Ensure credentials are correct

Error Response: 

1
2
3
4
5
6
7
8
{
  "error": "connection_failed",
  "message": "Failed to connect to source database",
  "details": {
    "host": "source-db.example.com",
    "error": "Connection timeout"
  }
}

Next Steps

  1. A session represents a single synchronization operation with its own configuration, state, and statistics. ↩