Agent skill
brightdata-upgrade-migration
Analyze, plan, and execute Bright Data SDK upgrades with breaking change detection. Use when upgrading Bright Data SDK versions, detecting deprecations, or migrating to new API versions. Trigger with phrases like "upgrade brightdata", "brightdata migration", "brightdata breaking changes", "update brightdata SDK", "analyze brightdata version".
Install this agent skill to your Project
npx add-skill https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/saas-packs/brightdata-pack/skills/brightdata-upgrade-migration
SKILL.md
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
// BEFORE: Raw residential proxy (manual CAPTCHA handling)
const oldProxy = {
host: 'brd.superproxy.io',
port: 22225, // Old residential port
auth: {
username: `brd-customer-${CID}-zone-residential_zone`,
password: OLD_PASSWORD,
},
};
// AFTER: Web Unlocker (automatic CAPTCHA, fingerprinting)
const newProxy = {
host: 'brd.superproxy.io',
port: 33335, // Web Unlocker port
auth: {
username: `brd-customer-${CID}-zone-web_unlocker1`,
password: NEW_PASSWORD,
},
};
// Changes: port 22225 → 33335, zone name, password
// Web Unlocker handles CAPTCHAs automatically — remove manual solving code
Step 3: Migrate to Scraping Browser from Puppeteer
// BEFORE: Self-hosted Puppeteer with proxy
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
args: [`--proxy-server=http://brd.superproxy.io:22225`],
});
// AFTER: Bright Data Scraping Browser (managed browser)
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`,
});
// Changes: launch → connect, local browser → remote WebSocket
// Remove: browser install, proxy args, CAPTCHA solving libraries
Step 4: Migrate Datasets API v2 to v3
// BEFORE: Datasets API v2
const v2Response = await fetch(
`https://api.brightdata.com/dca/trigger?collector=${collectorId}`,
{ method: 'POST', headers: { 'Authorization': `Bearer ${TOKEN}` }, body: JSON.stringify(input) }
);
// AFTER: Datasets API v3 (current)
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) }
);
// Changes: /dca/trigger → /datasets/v3/trigger, collector → dataset_id
// v3 adds: format parameter, webhook delivery, snapshot status polling
Step 5: Migration Checklist
# Create migration branch
git checkout -b migrate/brightdata-zone-upgrade
# Update environment variables
# OLD
BRIGHTDATA_ZONE=residential1
# NEW
BRIGHTDATA_ZONE=web_unlocker1
BRIGHTDATA_ZONE_PASSWORD=new_password
# Test against staging
BRIGHTDATA_ZONE=web_unlocker1_staging npm test
# Verify scraping still works
npm run scrape -- --url https://example.com --dry-run
Rollback Procedure
# Keep old zone active during migration window
# Rollback = switch BRIGHTDATA_ZONE back to old zone name
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.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
dockerfile-generator
Dockerfile Generator - Auto-activating skill for DevOps Basics. Triggers on: dockerfile generator, dockerfile generator Part of the DevOps Basics skill category.
branch-naming-helper
Branch Naming Helper - Auto-activating skill for DevOps Basics. Triggers on: branch naming helper, branch naming helper Part of the DevOps Basics skill category.
readme-generator
Readme Generator - Auto-activating skill for DevOps Basics. Triggers on: readme generator, readme generator Part of the DevOps Basics skill category.
makefile-generator
Makefile Generator - Auto-activating skill for DevOps Basics. Triggers on: makefile generator, makefile generator Part of the DevOps Basics skill category.
gitignore-generator
Gitignore Generator - Auto-activating skill for DevOps Basics. Triggers on: gitignore generator, gitignore generator Part of the DevOps Basics skill category.
pre-commit-hook-setup
Pre Commit Hook Setup - Auto-activating skill for DevOps Basics. Triggers on: pre commit hook setup, pre commit hook setup Part of the DevOps Basics skill category.
Didn't find tool you were looking for?