Gfs
Git For database Systems
Install / Use
/learn @Guepard-Corp/GfsREADME
Table of Contents
- 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
Important Notice
This project is under active development. Expect changes, incomplete features, and evolving APIs.
What is GFS?
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.
Built for AI Agents
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.
Supported Databases
- PostgreSQL (versions 13-18)
- MySQL (versions 8.0-8.1)
Run gfs providers to see all available providers and their supported versions.
Features
- 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)
Installation
curl -fsSL https://gfs.guepard.run/install | bash
Quick Start
1. Check available database providers
gfs providers
This shows all supported database providers and their versions.
2. Create a new project directory
mkdir my_project
cd my_project
3. Initialize the repository
gfs init --database-provider postgres --database-version 17
This creates a .gfs directory and starts a PostgreSQL database in a Docker container.
4. Check status
gfs status
This shows the current state of your storage and compute resources.
5. Query your database
# Execute a SQL query directly
gfs query "SELECT 1"
# Or open an interactive terminal session
gfs query
6. Make changes and commit
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"
7. View commit history
gfs log
8. Time travel through history
gfs checkout <commit_hash>
Your database will be restored to that exact state.
9. Work with branches
gfs checkout -b feature-branch # Create and switch to a new branch
gfs checkout main # Switch back to main
AI Agent Setup
Connect your AI agent to GFS in under a minute.
Claude Code
GFS works with Claude Code out of the box via MCP:
claude mcp add gfs -- gfs mcp --path /path/to/your/repo
Claude Desktop
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.
Cursor / Cline / Windsurf
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.
What agents can do with GFS
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
MCP Server
GFS includes a Model Context Protocol (MCP) server for programmatic access to all GFS operations.
Stdio mode (default)
gfs mcp
# or explicitly
gfs mcp stdio
Designed for direct integration with MCP-compatible clients.
HTTP mode
# 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
Specifying a Repository Path
gfs mcp --path /path/to/repo
Command Reference
Revision References
GFS supports Git-style revision notation for referencing commits in commands like checkout, schema show, and schema diff:
HEAD- Current commitmain- Branch tip (any branch name)abc123...- Full commit hash (64 characters)HEAD~1- Parent of HEAD (previous commit)HEAD~5- 5th ancestor of HEADmain~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
gfs providers
List available database providers and their supported versions.
gfs providers
gfs providers postgres # Show details for a specific provider
gfs init
Initialize a new GFS repository.
gfs init --database-provider <provider> --database-version <version>
gfs status
Show the current state of storage and compute resources.
gfs status
gfs status --output json
gfs commit
Commit the current database state.
gfs commit -m "commit message"
gfs log
Show the commit history.
gfs log
gfs log -n 10 # Limit to 10 commits
gfs log --full-hash # Show full 64-char hashes
gfs checkout
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
gfs query
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
gfs schema
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]
gfs export
Export data from the running database.
gfs export --output-dir <dir> --format <fmt>
Formats: sql (plain-text SQL), custom (PostgreSQL binary dump)
gfs import
Import data into the running database.
