Snapshot Versioning

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:

Basecut scans all versions of dev-seed
Selects the most recently created version
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:

Basecut resolves dev-seed:brave-lion to an exact snapshot record
Restores that specific version
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:

List available versions:
basecut snapshot list --name dev-seed

Check for typos in tag:

# Tags are exact
dev-seed:brave-lion    # Correct
dev-seed:brave-lions   # Wrong (plural)

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

Getting Started

Core Concepts

Configuration

Workflows

Integrations

CLI Reference

Deployment

Reference

Snapshot Versioning

How Versioning Works

Generated Tags

Storage Structure

Referencing Snapshots

Using `:latest`

Using Specific Tags

Implicit `:latest`

Custom Tags

Version Management

Listing Versions

Deleting Old Versions

Best Practices

1. Use Descriptive Snapshot Names

2. Establish Naming Conventions

3. Automate Snapshot Rotation

4. Document Version Purpose

5. Use Separate Snapshots for Different Use Cases

Troubleshooting

”Version Not Found”

“Multiple Versions Found”

Next Steps

Snapshots Overview

Storage Providers

Common Workflows

CLI Reference

​How Versioning Works

​Generated Tags

​Storage Structure

​Referencing Snapshots

​Using :latest

​Using Specific Tags

​Implicit :latest

​Custom Tags

​Version Management

​Listing Versions

​Deleting Old Versions

​Best Practices

​1. Use Descriptive Snapshot Names

​2. Establish Naming Conventions

​3. Automate Snapshot Rotation

​4. Document Version Purpose

​5. Use Separate Snapshots for Different Use Cases

​Troubleshooting

​”Version Not Found”

​“Multiple Versions Found”

​Next Steps

Snapshots Overview

Storage Providers

Common Workflows

CLI Reference

How Versioning Works

Generated Tags

Storage Structure

Referencing Snapshots

Using `:latest`

Using Specific Tags

Implicit `:latest`

Custom Tags

Version Management

Listing Versions

Deleting Old Versions

Best Practices

1. Use Descriptive Snapshot Names

2. Establish Naming Conventions

3. Automate Snapshot Rotation

4. Document Version Purpose

5. Use Separate Snapshots for Different Use Cases

Troubleshooting

”Version Not Found”

“Multiple Versions Found”

Next Steps