Imported from jeremylongshore/tons-of-skills-marketplace (plugins/saas-packs/brightdata-pack/skills/brightdata-upgrade-migration/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill brightdata-upgrade-migration. Copyright stays with the author (MIT).

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

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

Examples

Pin the current client/version and reproduce the approved workload against a provider-controlled test target before an upgrade. Compare request policy, response schema, cost/rate behavior, and redacted results behind a feature flag; roll back to the prior artifact on any authorization, compliance, or reconciliation difference.

Error Handling

Resources

• Web Unlocker Migration
• Datasets API v3
• Scraping Browser Setup

Next Steps

For CI integration during upgrades, see brightdata-ci-integration.