Skip to main content
Basecut automatically versions every snapshot you create, allowing you to maintain multiple point-in-time captures of your database and reference specific versions when restoring.

​
How Versioning Works

Every time you run basecut snapshot create with the same --name, Basecut creates a new version rather than overwriting the previous one.

​
Generated Tags

Each version is automatically assigned a unique, human-readable tag using an adjective-animal format: 
brave-lion
swift-falcon
gentle-bison
These tags are generated by the Basecut API when you create a snapshot without providing an explicit tag.

​
Storage Structure

Snapshot references are name/tag based (dev-seed:brave-lion), while cloud storage objects are keyed by internal job IDs (for example <prefix>/snapshots/<job-id>/...). Use CLI/API metadata (snapshot list and snapshot inspect) to map a name/tag reference to its storage location.

​
Referencing Snapshots

​
Using :latest

The most common pattern—reference the newest version: 
basecut snapshot restore dev-seed:latest --target "$BASECUT_DATABASE_URL"
What happens:
  1. Basecut scans all versions of dev-seed
  2. Selects the most recently created version
  3. Restores that version
Use case: Development workflows where you always want the freshest data.

​
Using Specific Tags

Reference an exact version by its unique tag: 
basecut snapshot restore dev-seed:brave-lion --target "$BASECUT_DATABASE_URL"
What happens:
  1. Basecut resolves dev-seed:brave-lion to an exact snapshot record
  2. Restores that specific version
  3. Fails if that tag doesn’t exist
Use cases:
  • Reproducing a bug with the exact data state
  • Rolling back to a known-good snapshot
  • Compliance/audit requirements for specific dates

​
Implicit :latest

Omitting the version defaults to :latest: 
# These are equivalent
basecut snapshot restore dev-seed --target "$BASECUT_DATABASE_URL"
basecut snapshot restore dev-seed:latest --target "$BASECUT_DATABASE_URL"

​
Custom Tags

You can override the automatic tag generation by providing your own tag using the --tag or -t flag: 
# Create a snapshot with a custom tag
basecut snapshot create --config basecut.yml --name dev-seed --tag v1-0-0
Referencing by custom tag: 
basecut snapshot restore dev-seed:v1-0-0 --target "$BASECUT_DATABASE_URL"
Custom tags must be lowercase alphanumeric with hyphens, starting and ending with an alphanumeric character. The tag latest is reserved.

​
Version Management

​
Listing Versions

List snapshots from the CLI: 
# List all snapshots (paginated)
basecut snapshot list

# Filter to one snapshot name
basecut snapshot list --name dev-seed
For deeper details on one version: 
basecut snapshot inspect dev-seed:brave-lion

​
Deleting Old Versions

Delete snapshot metadata from the CLI: 
basecut snapshot delete dev-seed:v1 --yes
For object cleanup, use storage lifecycle policies (recommended) or your storage provider CLI (aws s3 rm, gsutil rm).

​
Best Practices

​
1. Use Descriptive Snapshot Names

Names should indicate purpose, not just content: Good: 
--name "dev-seed"           # Clear: for development seeding
--name "debug-user-12345"   # Clear: debugging specific user
--name "pre-migration-test" # Clear: testing before migration
--name "qa-stable"          # Clear: stable data for QA
Avoid: 
--name "backup"             # Vague: backup for what?
--name "test"               # Vague: test what?
--name "data"               # Vague: what data?

​
2. Establish Naming Conventions

Pattern: <environment>-<purpose>[-<context>] Examples:
  • dev-seed - Daily development data
  • staging-smoke - Smoke test data for staging
  • prod-debug-issue-456 - Production debugging snapshot
  • qa-regression-v2.0 - QA regression testing for v2.0

​
3. Automate Snapshot Rotation

Schedule snapshot creation in CI (see CI/CD Integration) and configure storage lifecycle policies to automatically delete old versions.

​
4. Document Version Purpose

Add metadata to your snapshot manifest for traceability: 
# Capture git metadata
basecut snapshot create \
  --config basecut.yml \
  --name "dev-seed" \
  --git
Result in manifest.json: 
{
  "name": "dev-seed",
  "created_at": "2024-01-29T10:30:00Z",
  "git": {
    "commit": "a1b2c3d",
    "branch": "main",
    "repo": "github.com/myorg/myapp"
  }
}

​
5. Use Separate Snapshots for Different Use Cases

Don’t overload a single snapshot name: Antipattern: 
# Same snapshot for everything
--name "snapshot"  # Used for dev, testing, debugging, etc.
Better approach: 
# Separate snapshots by purpose
--name "dev-daily"          # Daily development refresh
--name "ci-test"            # CI/CD test suite
--name "debug-prod-issues"  # Production debugging
--name "qa-regression"      # QA regression suite
Why: Prevents accidental overwrites and makes version management clearer.

​
Troubleshooting

​
”Version Not Found”

Symptom: 
✗ Error: version not found: dev-seed:old-tag
Solutions:
  1. List available versions: 
    basecut snapshot list --name dev-seed
  2. Check for typos in tag: 
    # Tags are exact
dev-seed:brave-lion    # Correct
dev-seed:brave-lions   # Wrong (plural)
  3. Use :latest instead: 
    basecut snapshot restore dev-seed:latest --target "$BASECUT_DATABASE_URL"

​
“Multiple Versions Found”

This shouldn’t happen—Basecut resolves versions using unique snapshot tags and IDs. If you see this error, file a bug report.

​
Next Steps

Snapshots Overview

Understand snapshot anatomy and structure

Storage Providers

Configure S3, GCS, or local storage

Common Workflows

Patterns for versioning in practice

CLI Reference

Complete command documentation