Bright Data Upgrade & Migration
Overview
Guide for migrating between Bright Data products, API versions, and zone configurations. Since Bright Data uses proxy protocols and REST APIs (not versioned SDKs), migrations typically involve changing zone types, proxy endpoints, or API payload formats.
Prerequisites
- Current Bright Data zone credentials
- Git for version control
- Staging environment for testing
Instructions
Step 1: Identify Migration Type
| Migration | From | To | Effort |
|---|
| Zone upgrade | Web Unlocker v1 | Web Unlocker v2 | Low |
| Product switch | Residential Proxy | Web Unlocker | Medium |
| Browser migration | Puppeteer direct | Scraping Browser | Medium |
| API migration | Datasets v2 | Datasets v3 | Medium |
| Full platform | Competitor | Bright Data | High |
Step 2: Migrate from Direct Proxies to Web Unlocker
const oldProxy = {
host: 'brd.superproxy.io',
port: 22225,
auth: {
username: `brd-customer-${CID}-zone-residential_zone`,
password: OLD_PASSWORD,
},
};
const newProxy = {
host: 'brd.superproxy.io',
port: 33335,
auth: {
username: `brd-customer-${CID}-zone-web_unlocker1`,
password: NEW_PASSWORD,
},
};
Step 3: Migrate to Scraping Browser from Puppeteer
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
args: [`--proxy-server=http://brd.superproxy.io:22225`],
});
import puppeteer from 'puppeteer-core';
const AUTH = `brd-customer-${CID}-zone-scraping_browser1:${PASSWORD}`;
const browser = await puppeteer.connect({
browserWSEndpoint: `wss://${AUTH}@brd.superproxy.io:9222`,
});
Step 4: Migrate Datasets API v2 to v3
const v2Response = await fetch(
`https://api.brightdata.com/dca/trigger?collector=${collectorId}`,
{ method: 'POST', headers: { 'Authorization': `Bearer ${TOKEN}` }, body: JSON.stringify(input) }
);
const v3Response = await fetch(
`https://api.brightdata.com/datasets/v3/trigger?dataset_id=${datasetId}&format=json`,
{ method: 'POST', headers: { 'Authorization': `Bearer ${TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify(input) }
);
Step 5: Migration Checklist
git checkout -b migrate/brightdata-zone-upgrade
BRIGHTDATA_ZONE=residential1
BRIGHTDATA_ZONE=web_unlocker1
BRIGHTDATA_ZONE_PASSWORD=new_password
BRIGHTDATA_ZONE=web_unlocker1_staging npm test
npm run scrape -- --url https://example.com --dry-run
Rollback Procedure
export BRIGHTDATA_ZONE=old_zone_name
export BRIGHTDATA_ZONE_PASSWORD=old_password
Output
- Updated zone configuration
- Migrated proxy code to new endpoints
- Passing test suite against new zone
- Old zone kept active for rollback
Error Handling
| Issue | Cause | Solution |
|---|
| 407 after migration | New zone password not set | Update BRIGHTDATA_ZONE_PASSWORD |
| Different response format | Zone type changed | Update response parsing |
| Higher latency | Web Unlocker overhead | Expected; CAPTCHA solving takes time |
| Missing data fields | API v3 schema change | Update TypeScript interfaces |
Resources
Next Steps
For CI integration during upgrades, see brightdata-ci-integration.
