Git For database Systems

Safe database version control for AI coding agents and developers.

Works with Claude Code, Cursor, Cline, Windsurf, and any skills / MCP-compatible agent

• Important Notice
• What is GFS?
• Built for AI Agents
• Supported Databases
• Features
• Installation
• Quick Start
• AI Agent Setup
• MCP Server
• Command Reference
• Configuration
• Troubleshooting
• Development
• Contributing
• Community
• Roadmap
• License

This project is under active development. Expect changes, incomplete features, and evolving APIs.

GFS (Git For database Systems) brings Git-like version control to your databases. It enables you to:

• Safe for AI agents — automatic snapshots protect against agent mistakes and data loss
• Rollback instantly — undo any database change in seconds
• Branch to let agents and developers experiment without risking data
• Time travel through your database history
• Commit database states with meaningful messages
• Collaborate — agents and humans working on the same database with confidence

GFS uses Docker to manage isolated database environments, making it easy to work with different versions of your database without conflicts.

AI coding agents are powerful but dangerous around databases. A single bad migration, a dropped table, or corrupted data can be costly to recover from — if recovery is even possible.

GFS makes agent-driven database work safe by default:

• Every change is a commit. If an agent makes a mistake, roll back in one command.
• Branches are free. Let agents experiment on an isolated branch — merge only what works.
• MCP integration. Agents interact with GFS natively through the Model Context Protocol, no shell wrappers needed.
• Less token waste. Import, export, and query operations run through GFS instead of the agent generating boilerplate SQL.

Without GFS: an agent drops a table or runs a bad migration — you're left manually restoring from backups (if they exist).

With GFS: gfs checkout HEAD~1 — done. Your database is back to the previous state in seconds.

• PostgreSQL (versions 13-18)
• MySQL (versions 8.0-8.1)

Run gfs providers to see all available providers and their supported versions.

• Initialize database repositories
• Commit database changes
• View commit history
• Checkout previous commits
• Create and switch branches
• Check database status
• Query database directly from CLI (SQL execution and interactive mode)
• Schema extraction, show, and diff between commits
• Export and import data (SQL, custom, CSV)
• Compute container management (start, stop, logs)
• Repository config (user.name, user.email)

curl -fsSL https://gfs.guepard.run/install | bash

gfs providers

This shows all supported database providers and their versions.

mkdir my_project
cd my_project

gfs init --database-provider postgres --database-version 17

This creates a .gfs directory and starts a PostgreSQL database in a Docker container.

gfs status

This shows the current state of your storage and compute resources.

# Execute a SQL query directly
gfs query "SELECT 1"

# Or open an interactive terminal session
gfs query

gfs query "CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT NOT NULL);"
gfs query "INSERT INTO users (name) VALUES ('Alice'), ('Bob');"
gfs commit -m "Add users table"

gfs log

gfs checkout <commit_hash>

Your database will be restored to that exact state.

gfs checkout -b feature-branch   # Create and switch to a new branch
gfs checkout main                # Switch back to main

Connect your AI agent to GFS in under a minute.

GFS works with Claude Code out of the box via MCP:

claude mcp add gfs -- gfs mcp --path /path/to/your/repo

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "gfs": {
      "command": "gfs",
      "args": ["mcp", "--path", "/path/to/your/repo"]
    }
  }
}

Restart Claude Desktop and GFS operations will be available as tools.

Use the stdio MCP server:

gfs mcp --path /path/to/your/repo

Configure your editor's MCP settings to point to this command. Refer to your editor's MCP documentation for the exact configuration format.

Once connected, your AI agent can:

• Commit before and after making changes — creating safe checkpoints
• Branch to try risky migrations without affecting the main database
• Roll back if something goes wrong
• Query the database to inspect data
• Diff schemas between commits to understand what changed
• Import/export data without generating large SQL blocks in context

GFS includes a Model Context Protocol (MCP) server for programmatic access to all GFS operations.

gfs mcp
# or explicitly
gfs mcp stdio

Designed for direct integration with MCP-compatible clients.

# Start as a background daemon
gfs mcp start

# Check daemon status
gfs mcp status

# Stop the daemon
gfs mcp stop

# Start in foreground (default port: 3000)
gfs mcp web

# Custom port
gfs mcp web --port 8080

gfs mcp --path /path/to/repo

GFS supports Git-style revision notation for referencing commits in commands like checkout, schema show, and schema diff:

• HEAD - Current commit
• main - Branch tip (any branch name)
• abc123... - Full commit hash (64 characters)
• HEAD~1 - Parent of HEAD (previous commit)
• HEAD~5 - 5th ancestor of HEAD
• main~3 - 3 commits before main branch tip

Examples:

gfs checkout HEAD~1                    # Checkout previous commit
gfs schema diff HEAD~5 HEAD           # Compare schema with 5 commits ago
gfs schema show main~3                # View schema from 3 commits back

List available database providers and their supported versions.

gfs providers
gfs providers postgres    # Show details for a specific provider

Initialize a new GFS repository.

gfs init --database-provider <provider> --database-version <version>

Show the current state of storage and compute resources.

gfs status
gfs status --output json

Commit the current database state.

gfs commit -m "commit message"

Show the commit history.

gfs log
gfs log -n 10              # Limit to 10 commits
gfs log --full-hash         # Show full 64-char hashes

Switch to a different commit or branch.

gfs checkout <commit_hash>       # Checkout a specific commit
gfs checkout -b <branch_name>   # Create and checkout a new branch
gfs checkout <branch_name>      # Checkout an existing branch

Execute SQL queries or open an interactive database terminal.

gfs query "SELECT * FROM users"   # Execute a query
gfs query                         # Open interactive terminal

Options: --database, --path

Database schema operations: extract, show, and diff.

gfs schema extract [--output <file>] [--compact]
gfs schema show <commit> [--metadata-only] [--ddl-only]
gfs schema diff <commit1> <commit2> [--pretty] [--json]

Export data from the running database.

gfs export --output-dir <dir> --format <fmt>

Formats: sql (plain-text SQL), custom (PostgreSQL binary dump)

Import data into the running database.

gfs import --file <path> [--format <fmt>]

Supports .sql, .dump, and .csv files. Format is inferred from file extension when omitted.

Read or write repository config.

gfs config user.name              # Read
gfs config user.name "John Doe"   # Write

Manage the database container.

gfs compute start     # Start the container
gfs compute stop      # Stop the container
gfs compute status    # Show container status
gfs compute logs      # View container logs

GFS uses Docker to manage database containers. Make sure Docker is installed and running before using GFS.

• Docker (latest version recommended)
• Bash/Zsh shell
• curl for installation
• tar for extracting releases

# Start Docker Desktop or Docker daemon
# On macOS/Windows: Start Docker Desktop
# On Linux: sudo systemctl start docker

If the default port is already in use, stop the conflicting service or check gfs status for the assigned port.

1. Check that the container is running: docker ps
2. Verify the connection details with: gfs status
3. Ensure Docker has network access

• Rust (latest stable version)
• Docker
• Cargo

git clone https://github.com/Guepard-Corp/gfs.git
cd gfs
cargo build

Run commands using cargo:

cargo run --bin gfs init --database-provider postgres --database-version 17 [--port 65432]
cargo run --bin gfs commit -m "v1"
cargo run --bin gfs log
cargo run --bin gfs status

cargo test                        # Run all tests
cargo test-all                    # Full suite including E2E (sequential)
cargo test -- --test-threads=1    # Alternative sequential execution
cargo cov                         # Generate coverage report
cargo test <test_name>            # Run specific tests
cargo test -- --nocapture         # Run with output

Optional: Better test reports and code coverage

• cargo-nextest: Faster, clearer test output. Install with cargo install cargo-nextest, then run cargo nextest run or cargo nt.
• cargo-llvm-cov: Code coverage. Install with cargo install cargo-llvm-cov (requires rustup component add llvm-tools-preview). Run cargo llvm-cov --html --open for an HTML report.

cargo build --release

The binary will be available at target/release/gfs.

We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

Please see our CONTRIBUTING.md for detailed guidelines on:

• How to submit contributions
• Code contribution workflow
• Good first issues to get started
• Development best practices

For quick questions, join our Discord community.

• Discord: Join our community
• YouTube: Watch the demo
• Issues: Report bugs or request features

Check Roadmap

This project is licensed under MIT License. See the LICENSE file for details.