BranchBase

BranchBase provides a seamless solution for Git-native local database branching, specifically designed for PostgreSQL, MySQL, and SQLite. This innovative tool eliminates the hassle of managing local databases every time a Git branch is switched, allowing developers to focus on what matters most—coding.

The Challenge: Managing Local Databases with Git

Switching between Git branches often results in significant friction due to active migrations. Common issues that arise include:

• Crash occurrences due to schema mismatches when switching branches with pending migrations.
• Time-consuming processes like using the nuclear option of bringing down containers and re-seeding databases.
• Manual rollback efforts that often lead to the loss of test data.
• Handling multiple .env configurations for different branches, leading to errors.
• Reliance on cloud-based branching solutions, which can incur costs and are not suitable for offline development.

The Solution: Instant Database Branching

BranchBase tackles these challenges by introducing instant database branching through its local machine and Docker integration. This is how it works:

1. Quick Branching: Effortlessly create new isolated branch databases quickly using PostgreSQL's CREATE DATABASE ... TEMPLATE or filesystem copy-on-write methods for SQLite.
2. Transparent Proxying: Your application’s connection string remains unchanged, while BranchBase intelligently routes database queries based on the active Git branch.
3. Git Hook Automation: Simplifies branch switching via automated Git hooks, ensuring seamless integration with standard Git workflows.
4. Automatic Cleanup: Provides intelligent database management, automatically removing ephemeral databases when branches are deleted or merged.
5. Local and Offline Capability: Offers a fully local solution, negating the need for subscriptions, cloud connectivity, or telemetry.

Key Features

• Instant Branching: Fast database initialization tailored to the current Git branch.
• Transparent Connection: A proxy that ensures your app's database URL remains stable and never needs modification on branch changes.
• Lifecycle Management: Automatic database cleanup to keep your development environment clean and efficient.

Supported Commands & CLI Reference

BranchBase offers a variety of commands for ease of use:

• branchbase init: Initializes the repository and sets up configuration.
• branchbase proxy: Initiates the local routing proxy.
• branchbase list: Displays all active and ephemeral databases being managed.
• branchbase prune: Cleans up databases associated with merged branches.

How it Works

The system is designed with an efficient workflow:

1. Detection: Upon executing git checkout, BranchBase applies a hook to track branch changes.
2. Snapshot Creation: Database snapshots are created without downtime leveraging PostgreSQL capabilities or SQLite file system techniques.
3. Routing: Internal proxying ensures all database queries are correctly routed to the respective branch.
4. Lifecycle Management: BranchBase can automatically delete databases when branches are no longer needed, ensuring efficient resource usage.

Flexibility to Extend

BranchBase allows for easy extension by integrating new database drivers through a simple interface implementation, enhancing its applicability across various projects.

Community and Contribution

BranchBase encourages contributions, welcoming new developers through a structured onboarding process. For those looking to get involved, detailed guidelines and support resources are available in the repository. Community engagement is fostered with clear documentation and a code of conduct.

By adopting BranchBase, developers can reclaim valuable time typically wasted on database management, streamline their workflow, and enhance the overall productivity of their development processes.