Script Versioning¶

Track every change to your scripts and see exactly what code produced specific results.

Overview¶

Scrapazoid automatically creates version snapshots of your scripts. Every execution is linked to a specific version, so you can always see the exact code that was run.

How Versioning Works¶

Automatic Version Creation¶

Versions are created automatically when:

✅ Script is first saved - Creates version 1 ✅ Code changes - Creates a new version (v2, v3, etc.)

Versions are NOT created when:

❌ Name only changes - Updating script name doesn't create a version ❌ Description only changes - Updating description doesn't create a version ❌ Saving without changes - No changes = no new version

What's Stored in Each Version¶

Each version captures a complete snapshot:

Version number - Sequential (1, 2, 3...)
Code - Complete script code
Name - Script name at time of version
Description - Script description
Timestamp - When the version was created

Viewing Version History¶

Access Version History¶

Open a script in the Editor
Click the "Version History" button (next to Save/Run)
View all versions of your script

Version History Page¶

The version history shows:

Version number and creation timestamp
Script name and description at that time
Code preview (first 100 characters)
Actions: View Code, Restore

Version 3                    Jan 24, 2026 3:45 PM
My Scraper
Added error handling for missing elements
Code: import datetime\n\nasync def main(page...
[View Code] [Restore]

Version 2                    Jan 24, 2026 2:30 PM
My Scraper
Fixed selector for title element
Code: async def main(page):\n    await page...
[View Code] [Restore]

Version 1                    Jan 24, 2026 1:15 PM
My Scraper (initial version)
Code: async def main(page):\n    await page...
[View Code] [Restore]

Viewing Version Code¶

Click "View Code" on any version to see the complete script:

Full code in a readable modal
Restore This Version button
Allows comparing versions side-by-side (open in separate tabs)

Best Practices¶

Compare versions: 1. Open version history 2. Right-click "View Code" → Open in New Tab (for version 2) 3. Right-click "View Code" → Open in New Tab (for version 3) 4. Compare side-by-side

Restoring Previous Versions¶

How to Restore¶

Navigate to Version History
Find the version you want to restore
Click "Restore"
Confirm the restoration

What Happens When You Restore¶

When you restore a version:

✅ Script code is updated to the old version
✅ Script name is updated to the old name
✅ Script description is updated to the old description
✅ A new version is created (restoration = code change)

Example:

Current state: Version 5
Restore to:    Version 2
Result:        Version 6 (with code from Version 2)

This means you never lose history - restorations are tracked!

Execution Version Tracking¶

Viewing Execution Version¶

Every execution shows which version was run:

In Execution History: - Each execution displays its version number

In Execution Detail Page: - Version: v3 with "View Code" button - Click to see the exact code that produced those results

For Old Executions: - Executions created before versioning was enabled show: - "Version not tracked (executed before versioning)"

Why Version Tracking Matters¶

Scenario: You run a script and get great results. Later, you modify the script and it breaks.

Without versioning: ❌ You don't know what changed ❌ Can't see the working code ❌ Have to guess what broke

With versioning: ✅ View the execution that worked ✅ Click "View Code" to see exact working script ✅ Compare with current version ✅ Restore to working version

Common Workflows¶

Debugging a Broken Script¶

1. Script was working yesterday, broken today
2. Go to "History" → find successful execution
3. Click execution → see "Version: v2"
4. Click "View Code" → see working script
5. Compare with current version (v5)
6. Identify the breaking change
7. Either fix current version or restore to v2

Experimenting Safely¶

1. Save current working version (creates v3)
2. Experiment with changes
3. Run and test
4. If it works: keep it (v4, v5, v6...)
5. If it breaks: restore to v3

Code Review / Audit¶

1. View version history
2. See all changes over time
3. Review what changed between versions
4. Understand script evolution

Version Metadata¶

Version Numbering¶

Versions are numbered sequentially: 1, 2, 3, 4...
Version numbers are per-script (each script has its own sequence)
Version numbers never reset
Deletions don't reuse numbers

Version Timestamps¶

Each version has a created_at timestamp
Timestamps use UTC
Displayed in your local timezone

Tips & Best Practices¶

1. Save Before Major Changes¶

Before making significant changes:

1. Save current version (creates snapshot)
2. Make your changes
3. Test
4. If it breaks, restore previous version

2. Use Descriptive Names¶

Your script name is captured in each version:

✅ "Scraper - with error handling"
✅ "Product Scraper v2 (pagination fixed)"
❌ "test"
❌ "script1"

3. Document in Description¶

Descriptions are version-tracked too:

# In description field:
"Fixed selector for product titles. Added retry logic for
timeouts. Handles missing images gracefully."

4. Review Before Restoring¶

Before restoring: 1. View the version code 2. Verify it's what you want 3. Remember: restore creates a NEW version (no history loss)

5. Use Execution History¶

When debugging: 1. Find executions that worked 2. Check their version 3. Compare with current version 4. Identify what changed

Limitations¶

Storage¶

Each version stores a full copy of the code
Large scripts × many versions = storage usage
Consider cleaning up old experiments

Ad-Hoc Executions¶

Scripts run without saving have no version
Execution history shows "Ad-hoc script (not saved)"
Save scripts to enable versioning

Concurrent Edits¶

The unique constraint on (script_id, version_number) prevents conflicts
If two versions try to create v5 simultaneously, one will fail
In practice, this is rare (one user per script)

Troubleshooting¶

"Version not tracked"¶

Problem: Execution shows "Version not tracked"

Cause: Execution created before versioning was enabled

Solution: This is normal for old executions. New executions will be tracked.

Version History Empty¶

Problem: No versions shown in version history

Cause: Script has never been saved (or migrations haven't run)

Solution: 1. Save the script (creates v1) 2. If still empty, check that migrations have run

Restore Doesn't Work¶

Problem: Restore button does nothing

Cause: May be a script ownership issue

Solution: You can only restore scripts you own. Check that you're logged in as the script owner.