GitBase LogoGitBase

Version control for your
Supabase Schema.

Chrome Extension + CLI v2.0

GitBase brings Git-like version control to your Supabase database. Commit schema snapshots, diff changes, reset to any checkpoint, and push to GitHub — directly from your dashboard or the command line.

Get Started
$npm i -g @coldge.com/gitbase
supabase.com/dashboard/project/...
GitBase
Setup
Commit
Diff
History
SQL
Schema Commit
Introspecting live database...
+ 3 tables added
~ 2 functions modified
- 1 policy deleted
Commit

Chrome Extension

Injects directly into the Supabase Dashboard. Commit, diff, browse history, and edit SQL without leaving your browser.

CLI

Full-featured command-line interface. Automate commits, push to GitHub, manage backups, and integrate into CI/CD pipelines.

Core Infrastructure

Engineered To Scale.

GitBase is a complete version control system for Supabase. It provides a Git-like commit layer that transforms your live database schema into a versioned, auditable, and recoverable asset.

Dashboard-Native Experience

GitBase embeds directly into the Supabase Dashboard as a Chrome extension. Five injected buttons — Setup, Commit, Diff, History, and SQL — give you full version control without leaving your browser.

// Injected into Supabase header
SetupCommitDiffHistorySQL
// Side panel opens with full UI
> Schema introspection complete
> 24 tables, 8 functions, 12 policies
✔ Ready to commit.
// Commit with component selectors
$ gitb commit -m "add profiles" --only tables
> Introspecting live schema...
> Reusing 18 unchanged objects
> Commit example1 created
// Auto-push to GitHub
✔ Pushed to github.com/team/db-schema

Git-Like Schema Commits

Every schema change becomes a commit with a hash, message, author, and timestamp. Unchanged schema objects are reused instead of being stored again. Optionally auto-push every commit to a GitHub repository.

Execution Plans & Safety

Before any destructive operation, GitBase builds an execution plan with cascade warnings. Preview exactly which SQL statements will run, detect dependency conflicts, and create backup snapshots — all before a single statement executes.

Building Execution Plan...
1. DROP TABLE: old_cache
2. ALTER TABLE: users
3. CREATE TABLE: profiles
4. CREATE POLICY: profiles_rls
⚠ Cascade warning: 2 views depend on users
✔ Backup snapshot created.

Intelligent Semantic Diffing

A specialized canonicalization layer normalizes SQL before comparison. Formatting noise, casing differences, and whitespace changes are ignored — only structural changes surface.

16+ Component Types

Track tables, views, materialized views, functions, triggers, policies, types, sequences, extensions, grants, publications, roles, cron jobs, secrets, and edge functions.

GitHub Integration

Push schema commits directly to a GitHub repository. Enable auto-push to keep your main branch as the single source of truth for your database schema.

Reset to Any Checkpoint

Roll back your live database to any previous commit hash. Preview the execution plan first, then apply. Pre-reset snapshots are created automatically as a safety net.

Dry-Run & Preview

Every push and reset supports --dry-run mode. See exactly what SQL statements would execute, including cascade warnings, before committing to any changes.

Backup Management

Safety snapshots are created automatically before destructive operations. List and clean up backup tables with dedicated commands. Never lose data during schema changes.

The Cycle

How GitBase Works

1. Commit Schema

Modify your schema in the Supabase Dashboard. When ready, click Commit in the injected header — or run the CLI. GitBase introspects the live database and creates a hashed snapshot you can diff, push, or reset to later.

# Commit current live state
$ gitb commit -m "added profiles"
# Or commit only specific components
$ gitb commit -m "add RLS" --only policies

2. Review & Push

Diff any two commits or compare HEAD against the live database. When ready, push changes to apply them — or push schema commits to GitHub for team review.

# Diff HEAD vs live database
$ gitb diff
# Push schema to GitHub
$ gitb github push

3. Disaster Recovery

If production breaks, reset to any previous commit. GitBase previews the execution plan, creates a safety backup, and rebuilds the schema to that exact historical state.

# Find the stable commit hash
$ gitb log
# Preview the reset plan
$ gitb reset example1
# Apply the reset
$ gitb reset example1 --apply

Documentation

Complete reference for the GitBase CLI. The Chrome extension provides the same capabilities through a visual interface.

Setup & Initialization

Install the CLI and initialize a GitBase repository in your project.

npm install

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

bash
$npm install -g @coldge.com/gitbase
// Or run without installing
$npx @coldge.com/gitbase --help

gitb init

Initialize a .gitbase repository with config, refs, and object storage. Connects to your Supabase project and optionally configures GitHub integration.

Flags

--project-refSupabase project reference.
--patSupabase personal access token.
--schemasComma-separated schema list (default: "public").
--db-modepg (direct PostgreSQL) or sql-api (Supabase Management API).
--db-urlPostgreSQL connection string (for pg mode).
--github-repoGitHub repository (owner/name) for schema sync.
--github-auto-pushAuto-push commits to GitHub (default: false).
bash
$gitb init

gitb config set

Update a configuration value after initialization.

Arguments

<key>Config key (e.g. github.autoPush).
<value>New value to set.
bash
$gitb config set github.autoPush true

Schema Sync

Commands to synchronize state between the live database and your local files.

gitb pull

Extracts schema definitions from the live database and writes them as SQL files to a local directory.

Flags

--outputOutput directory (default: current directory).
--schemasComma-separated schema list override.
bash
$gitb pull

gitb push

Pushes a committed schema state to the live database. Builds an execution plan and applies SQL statements in dependency order.

Flags

--hashCommit hash to push (defaults to HEAD).
--dry-runPreview changes without executing.
--recordRe-introspect and create a post-push snapshot commit.
bash
// Preview what will run
$gitb push --dry-run
// Execute push
$gitb push

gitb status

Shows uncommitted changes by comparing the live database against the latest committed HEAD.

Arguments

NoneThis command takes no arguments.
bash
$gitb status

Version Control

Commands to manage schema commits, diffs, and disaster recovery.

gitb commit

Introspects the live database and creates a permanent snapshot in the GitBase history.

Flags

-m, --messageRequired. Commit message.
--authorAuthor name for the commit.
--onlyComponent selectors (e.g. tables, tables:public.users, policies).
bash
// Commit entire schema
$gitb commit -m "added profiles"
// Commit only tables
$gitb commit -m "tables only" --only tables

gitb log

Displays the chronological commit history.

Flags

--limitNumber of commits to display (default: 30).
bash
$gitb log --limit 10

gitb diff

Compares two commits, or HEAD vs the live database. Uses canonicalization to eliminate formatting noise.

Arguments & Flags

[oldHash] [newHash]Compare two commits. Omit both to diff HEAD vs live.
--categoryFilter by category (tables, functions, etc.).
--objectFilter by specific object name.
bash
// Diff HEAD vs live DB
$gitb diff
// Diff two commits
$gitb diff example1 example2

gitb reset

Resets the live database to match a previous commit. Runs in preview mode by default — use --apply to execute.

Arguments & Flags

<hash>Required. Target commit hash.
--applyExecute the reset (preview-only without this flag).
--onlyRestrict reset to specific component selectors.
--snapshotCreate pre-reset snapshot commit (default: true).
bash
// Preview what would change
$gitb reset example1
// Execute the reset
$gitb reset example1 --apply

gitb export

Exports a committed schema to a single SQL file.

Flags

--hashCommit hash to export (defaults to HEAD).
--outputOutput SQL file path.
bash
$gitb export --output schema.sql

GitHub Integration

Push schema commits directly to a GitHub repository. Configure during gitb init or with gitb config set.

gitb github push

Pushes a commit's schema tree to the configured GitHub repository.

Flags

--hashCommit hash to push (defaults to HEAD).

Auto-Push

Enable github.autoPush to automatically push every commit to GitHub:

$ gitb config set github.autoPush true
bash
// Configure GitHub repo
$gitb config set github.repo team/db-schema
$gitb config set github.token ghp_...
// Push HEAD to GitHub
$gitb github push

Backup Management

GitBase creates safety backup tables before destructive operations. Manage them with these commands.

gitb backup list

List all backup tables created by GitBase safety snapshots.

Flags

--schemaFilter by schema name.

gitb backup cleanup

Drop backup tables created by GitBase.

Flags

--dry-runOnly list tables that would be dropped.
--schemaFilter by schema name.
bash
// List backup tables
$gitb backup list
// Preview cleanup
$gitb backup cleanup --dry-run
// Execute cleanup
$gitb backup cleanup

Global Flags & Security

Global Options

Available on every command:

--rootRoot directory containing .gitbase (default: current directory).
--db-modeOverride database mode (pg or sql-api).
--db-urlOverride PostgreSQL connection string.

Token Security

Your Supabase PAT and GitHub token are stored locally in .gitbase/config.json. These tokens grant access to your Supabase project and GitHub repository. Ensure .gitbase/ is listed in your .gitignore and never committed to public repositories.