Documentation

Tyro Checkpoint is a simple Laravel package that provides Git-like checkpoint functionality for your SQLite database during local development.

SQLite only: This package is specifically designed for SQLite databases and is perfect for lightning-fast local development flows.

Requirements

  • PHP 8.1 or higher
  • Laravel 10.x, 11.x or 12.x
  • SQLite database configured as your default connection

Installation

Install the package via Composer as a dev dependency:

composer require hasinhayder/tyro-checkpoint --dev

Run the installation command to setup everything:

php artisan tyro-checkpoint:install

This command verifies your database setup and creates the storage/tyro-checkpoints directory.

How It Works

  1. Full Snapshots: Each checkpoint is a complete copy of your SQLite database file.
  2. Metadata Tracking: Metadata is stored in a JSON file outside the database to prevent data loss during restoration.
  3. Instant Swap: Restoring a checkpoint simply replaces your current database file with the saved snapshot.
  4. Encryption: Optional file-level encryption using AES-256-CBC.

What are Checkpoints?

A checkpoint is a point-in-time snapshot of your entire SQLite database. Unlike traditional migrations or SQL dumps, a checkpoint captures the exact state of your data and schema at a specific moment.

Anatomy of a Checkpoint

  • Database Snapshot: A physical copy of your database.sqlite file, optionally encrypted.
  • Metadata: A JSON record containing the checkpoint name, ID, creation timestamp, optional notes, and encryption status.

Storage

By default, all checkpoints are stored in storage/tyro-checkpoints/. This directory contains both the snapshot files (.sqlite) and the metadata registry (checkpoints.json).

Pro Tip: You can version control certain checkpoints or exclude the entire directory from your Git repository depending on your team's workflow.

Creating Checkpoints

Create a checkpoint with an auto-generated name:

php artisan tyro-checkpoint:create

Create a checkpoint with a custom name and an optional note:

php artisan tyro-checkpoint:create initial_state --note="Clean install"

Encrypted Checkpoints

To create an encrypted snapshot, use the --encrypt flag:

php artisan tyro-checkpoint:create secure_state --encrypt

Listing Checkpoints

View all saved checkpoints, their sizes, creation dates, and statuses:

php artisan tyro-checkpoint:list

Restoring Checkpoints

Restore a checkpoint by its ID or Name:

php artisan tyro-checkpoint:restore 1
php artisan tyro-checkpoint:restore initial_state

If you don't provide an identifier, the command will display a selection list.

Note: Typical restoration takes less than 2 seconds, compared to minutes for migrating and seeding.

Notes & Locks

Adding Notes

Change or add a note to an existing checkpoint:

php artisan tyro-checkpoint:add-note 1

Locking Checkpoints

Lock a checkpoint to prevent accidental deletion via delete or flush commands:

php artisan tyro-checkpoint:lock 1

To enable deletion again, unlock it:

php artisan tyro-checkpoint:unlock 1

Delete & Flush

Delete a specific unlocked checkpoint:

php artisan tyro-checkpoint:delete 1

Delete all unlocked checkpoints to save disk space:

php artisan tyro-checkpoint:flush

Why Encryption Matters

When working with local development databases, developers often use production-like data or sensitive PII (Personally Identifiable Information). Tyro Checkpoint's encryption ensures that your data remains safe, even if your snapshots are shared or stored in insecure locations.

Key Benefits

  • Data Privacy: Protects sensitive user data (emails, passwords, personal details) within your SQLite snapshots.
  • Compliance: Helps meet security standards and internal policies regarding data handling during development.
  • Safe Sharing: Encrypted snapshots can be shared with teammates more securely when the encryption key is managed properly.
  • Zero Overhead: AES-256 encryption is blazingly fast on modern hardware, adding negligible time to the snapshot process.

Note: Encryption is handled at the file level. Once a snapshot is encrypted, it cannot be opened by standard SQLite browsers without first being decrypted by Tyro Checkpoint during restoration.

Encryption

Tyro Checkpoint supports AES-256 encryption for your snapshots. First, generate a key:

php artisan tyro-checkpoint:generate-key

⚠ WARNING: Replacing an existing encryption key will make all previously encrypted checkpoints impossible to restore. Always backup your key if you plan to keep your snapshots.

This adds TYRO_CHECKPOINT_ENCRYPTION_KEY to your .env file. Once configured, use --encrypt when creating checkpoints. Restoration will automatically detect and decrypt them.

Configuration

Publish the configuration to customize the storage path:

php artisan tyro-checkpoint:publish-config

Edit config/tyro-checkpoint.php to change where snapshots are stored.