Lunar

A fast database snapshot tool for PostgreSQL and SQLite. Create, restore, and manage database snapshots.

Installation

Using Homebrew:

brew install leonvogt/tap/lunar-db

Other platforms: Download the latest release binaries from the Releases page.

Background

Lunar is a reimplementation of Stellar, designed to make database snapshots and restoration lightning-fast during development.
It's perfect for quickly iterating on schema changes, switching branches, or experimenting locally.

Key Differences from Stellar:

• PostgreSQL and SQLite support (Stellar supports PostgreSQL and partial MySQL)
• Cross-platform binaries with no language runtime setup required

How It Works

PostgreSQL

Lunar leverages PostgreSQL's CREATE DATABASE ... TEMPLATE feature to create efficient database copies. Restoring a snapshot performs a fast rename operation rather than slow SQL dumps and imports.

SQLite

Snapshots are simple file copies of the SQLite database. The tool automatically handles WAL (Write-Ahead Logging) files for databases using WAL mode.

Note

Snapshots are full database copies and can consume significant disk space. Monitor your snapshot count to prevent storage issues.

Important

Lunar is intended for development use only. Do not use it if you cannot afford data loss.

Quick Start

# Initialize Lunar (creates lunar.yml)
lunar init

# Create a snapshot
lunar snapshot production

# List all snapshots
lunar list

# Restore a snapshot
lunar restore production

# Replace an existing snapshot
lunar replace production

# Remove a snapshot
lunar remove production

Configuration

Lunar uses a lunar.yml configuration file. Run lunar init to create one interactively, or create it manually.

PostgreSQL

database_url: postgres://localhost:5432/ # Connection URL without database name
database: my_database                    # Database to snapshot
maintenance_database: postgres           # Optional - database for admin operations

SQLite

provider: sqlite
database_path: ./myapp.db              # Path relative to lunar.yml
snapshot_directory: ./.lunar_snapshots # Optional - where snapshots are stored

Hooks

# Runs before a snapshot is created - if it fails, the snapshot is aborted
before_snapshot_command: "psql -d my_database -c 'TRUNCATE TABLE versions;'"

# Runs after a snapshot has been restored
after_restore_command: "bundle exec rails db:migrate"

Development

Build a local binary:

go build -o lunar .

This creates a lunar executable in the current directory. You can test it in other projects by specifying the path to this binary:

/path/to/lunar/lunar init

Run tests:

go test ./tests

Run only SQLite tests (faster, no Docker required):

go test ./tests -run "SQLite"

Run only PostgreSQL tests:

go test ./tests -run "Postgres"

Run a specific test:

go test -run TestInit ./tests/

---

Lunar is inspired by Stellar and its approach to fast database snapshots. Many thanks to the Stellar project for the ideas that guided Lunar's design.