GitBase LogoGitBase

Version control for your
Live Database.

Version 1.0.2 is live

GitBase synchronizes your Supabase state with local SQL files. A professional workflow for schema tracking, multi-tenant environments, and bulletproof database restores.

Get Started
$npm i -g @coldge/gitbase
~/project/supabase
❯
gitb status
Comparing Live DB (production) to local files...
~ Modified: public.users (Table)
+ Added: public.get_user_stats (Function)
❯
gitb pull
Fetching latest SQL definitions...
Pulled 2 changes successfully.
❯

Core Infrastructure

Engineered for Scale.

GitBase is the industry-standard version control engine for Supabase. It provides a robust, state-aware synchronization layer that transforms your Live Database into a manageable, reproducible asset.

Reverse Git Workflow

Stop struggling with fragile, forward-only local migrations. GitBase treats your Live Database as the absolute Source of Truth. Modify tables natively in the dashboard, and instantly pull perfectly formatted, canonical SQL directly into your version control.

// 1. Edit in Dashboard
$ gitb pull
> Analyzing public schema...
> Wrote 12 tables to local filesystem.
// 2. Save locally
$ gitb commit -m "feat: updated users table"
Building Execution Graph...
1. Create Table: users
2. Create Table: posts
3. Create View: user_posts
4. Create Policy: auth_view
✔ Restoration guaranteed safe.

Dependency-Aware Restoration

Never hit a deadlock during a restore. GitBase automatically parses foreign keys and references to build a complex Directed Acyclic Graph (DAG) for execution. Restores guarantee Tables are created before Views, and Views before Functions.

Multi-Profile Branches

Manage your environments with standard Git patterns. Swap seamlessly between Production, Staging, and Development references using powerful branching commands that redirect your entire project context instantly.

// Current branch: production
$ gitb checkout staging
> Switched to profile 'staging'
$ gitb status
> Comparing Staging DB to local files...
✔ In sync.

Intelligent Semantic Diffing

Leverage a specialized normalization layer that identifies structural modifications while ignoring aesthetic variance. Casing and formatting noise are automatically canonicalized for high-fidelity version tracking.

Remote History Backups

Sync your entire historical `.gitbase` repository directly into a secure Supabase Storage bucket for decentralized backups.

Production Guard

Destructive operations on protected branches like `production` are hard-blocked unless the user possesses Owner or Admin permissions.

The Cycle

How GitBase Works

1. Track Changes

Modify your schema directly in the Supabase Dashboard. Once ready, run a pull to instantly synchronize those remote changes into your local version control history.

# Pull live DB state to local
$ gitb pull
# Snapshot the current schema
$ gitb commit -m "Added policies"

2. Deploy to Live

After reviewing a pull request, or making local SQL adjustments, securely apply those configurations back to your staging or production environments.

# View pending local changes
$ gitb diff
# Deploy local SQL to Live DB
$ gitb push

3. Disaster Recovery

If production breaks due to a bad migration, simply revert. GitBase automatically cascades drop operations and rebuilds the database to that exact historical moment.

# Find the stable commit hash
$ gitb log
# Hard-reset entire live schema
$ gitb revert 8f2a1b

Documentation

Complete technical reference for installing, configuring, and operating the GitBase CLI.

Setup & Initialization

Install the CLI and connect your project to the Supabase Management API.

npm install

Install the GitBase CLI globally using npm to make the gitb command available everywhere.

bash
$npm install -g @coldge.com/gitbase

gitb login

Authenticate your local machine with the Supabase API using a Personal Access Token (PAT).

bash
$gitb login

gitb init

Initialize a GitBase repository within your project. Run this at the root where your supabase/ folder resides.

Flags

-f, --forceOverwrite existing configuration.
bash
$gitb init

Synchronization

Commands to synchronize state between the Live DB and local files.

gitb pull

Fetches schema definitions from the Live Database, canonicalizes them, and writes them to your local supabase/ directory.

Arguments

[files..]Optional. Restrict pull to specific tables (e.g. public.users).
bash
// Pull entire schema
$gitb pull
// Pull specific files
$gitb pull public.users

gitb push

Compiles local .sql files into a dependency-ordered execution graph and applies them sequentially to the Live Database.

Arguments

[files..]Optional. Restrict push to specific schemas or tables.
bash
$gitb push

gitb status

Computes and summarizes the structural differences between the live database and your local files using canonicalization to eliminate noise.

bash
$gitb status

Version Control

Commands to manage your historical snapshots and perform disaster recovery.

gitb commit

Saves a permanent snapshot of the current local schema to the GitBase history log.

Flags

-m, --messageRequired. Description of the snapshot.
bash
$gitb commit -m "added profiles"

gitb revert

Hard-resets the Live Database structure and local files to perfectly match a previous commit hash.

Arguments & Flags

[commit]Optional. The target hash (defaults to HEAD).
--filesOptional. Restrict revert to specific entities.
bash
// Find commit hash
$gitb log
// Revert entire DB
$gitb revert 8f2a1b9

gitb diff

Shows a line-by-line comparison of SQL definitions. Defaults to comparing local HEAD against the Live DB.

bash
$gitb diff

Environments & Profiles

Manage isolated environments by using Git-like branching to swap between Supabase project IDs.

gitb branch

Creates or lists environmental profiles. Use -d to delete a profile.

gitb checkout

Switches the active environment (e.g., from staging to production).

gitb merge

Synchronizes configuration and history from another branch profile into the current one.

bash
// Create and switch to staging
$gitb branch staging
$gitb checkout staging
// Merge staging into production
$gitb checkout production
$gitb merge staging

Security Policies

Token Security

Your Management API token is stored locally in ~/.config/gitbase/token.json. This token grants wide access to your Supabase organizations. Ensure this directory is secure and the file is never accidentally committed to public repositories.

Protected Branches

GitBase employs RBAC for destructive commands. Any branch named production requires the user to have Owner or Admin org permissions to execute a push or revert.