GitHub PocketDB 🚀

Use GitHub as a database! A PocketBase-compatible solution that stores your data as JSON files in GitHub repositories and serves files through GitHub's CDN.

🎯 Why GitHub PocketDB?

• 🆓 Free hosting for public repositories
• 🌐 Global CDN for fast file delivery via GitHub
• 📦 No backend required - pure static site hosting
• 🔄 Version controlled data and files
• 🔌 PocketBase compatible API for easy migration
• ⚡ Built-in caching for optimal performance
• 🛡️ Reliable - GitHub's 99.9% uptime SLA

🚀 Quick Start

Installation

npm install github-pocket-db

Basic Usage

import { GitHubPocketDB } from 'github-pocket-db';

// Configure your GitHub database
const db = new GitHubPocketDB({
	owner: 'your-username',
	repo: 'your-repo',
	token: process.env.GITHUB_TOKEN, // Only needed for write operations
	branch: 'main'
});

// Initialize (loads schema from GitHub)
await db.init();

// Use the familiar PocketBase API!
const records = await db.collection('users').getList(1, 50);
const user = await db.collection('users').getOne('user-id');

// Files are automatically served via GitHub CDN
console.log(user.avatar); // → https://raw.githubusercontent.com/...

📋 Migration from PocketBase

Step 1: Export Your PocketBase Data

First, backup your PocketBase schema and data:

# Your schema is already available as pb_schema.json
# Export your storage directory (already done if you have /storage folder)

Step 2: Run Migration

# Install the package
npm install github-pocket-db

# Run migration
npx github-pocket-db migrate your-username your-repo your-github-token ./pb_schema.json ./storage

# Or using environment variable
GITHUB_TOKEN=your-token npx github-pocket-db migrate your-username your-repo "" ./pb_schema.json ./storage

Step 3: Update Your Code

Replace your PocketBase imports:

// OLD
import PocketBase from 'pocketbase';
const pb = new PocketBase('https://your-pocketbase-url');

// NEW
import { GitHubPocketDB } from 'github-pocket-db';
const db = new GitHubPocketDB({
	owner: 'your-username',
	repo: 'your-repo'
});
await db.init();

That's it! Your existing code will work with minimal changes.

📚 API Reference

Configuration

interface GitHubDBConfig {
	owner: string; // GitHub username/organization
	repo: string; // Repository name
	branch?: string; // Branch (default: 'main')
	token?: string; // GitHub token for write operations
	dataPath?: string; // Data directory (default: 'data')
	storagePath?: string; // Storage directory (default: 'storage')
	cacheTTL?: number; // Cache TTL in seconds (default: 300)
}

Collections API

// List records with pagination and filtering
const result = await db.collection('posts').getList(1, 20, {
	sort: 'created desc',
	filter: 'status = "published"'
});

// Get single record
const post = await db.collection('posts').getOne('post-id');

// Create record
const newPost = await db.collection('posts').create({
	title: 'Hello World',
	content: 'My first post'
});

// Update record
const updatedPost = await db.collection('posts').update('post-id', {
	title: 'Updated Title'
});

// Delete record
await db.collection('posts').delete('post-id');

File Handling

// Upload files with record creation
const postWithImage = await db.collection('posts').create(
	{
		title: 'Post with Image',
		content: 'Content here'
	},
	{
		image: [
			{
				name: 'photo.jpg',
				type: 'image/jpeg',
				size: 150000,
				content: fileBuffer
			}
		]
	}
);

// Files are automatically available via GitHub CDN
console.log(postWithImage.image[0]);
// → https://raw.githubusercontent.com/user/repo/main/storage/collection_id/record_id/photo_xyz.jpg

🏗️ Repository Structure

After migration, your repository will have this structure:

your-repo/
├── pb_schema.json              # PocketBase schema definition
├── data/                       # JSON data files
│   ├── users.json             # User records
│   ├── posts.json             # Post records
│   └── ...                    # Other collections
├── storage/                   # File storage
│   ├── collection_id/
│   │   ├── record_id/
│   │   │   ├── file.jpg       # Actual files
│   │   │   ├── file.jpg.attrs # File metadata
│   │   │   └── ...
│   │   └── ...
│   └── ...
└── your-app-files/            # Your application code

🔧 Advanced Usage

Custom Data Processing

// Access collections directly
const collections = db.getCollections();
console.log(
	'Available collections:',
	collections.map((c) => c.name)
);

// Clear cache when needed
db.clearAllCache();

// Custom file URL generation
const fileUrl = db.getFileURL(record, 'filename.jpg');

Read-Only Mode

For production sites, you can omit the GitHub token to run in read-only mode:

const db = new GitHubPocketDB({
	owner: 'your-username',
	repo: 'your-repo'
	// No token = read-only mode
});

Environment Variables

# .env file
GITHUB_TOKEN=ghp_your_token_here
GITHUB_OWNER=your-username
GITHUB_REPO=your-repo

const db = new GitHubPocketDB({
	owner: process.env.GITHUB_OWNER!,
	repo: process.env.GITHUB_REPO!,
	token: process.env.GITHUB_TOKEN
});

🔐 Security & Permissions

GitHub Token Permissions

For write operations, your GitHub token needs:

• repo scope for private repositories
• public_repo scope for public repositories

Read-Only Deployment

For production sites, deploy without the GitHub token for security:

• ✅ Read data from public repositories
• ✅ Serve files via GitHub CDN
• ❌ No write operations (secure)

🚀 Framework Integration

SvelteKit Example

// src/lib/db.ts
import { GitHubPocketDB } from 'github-pocket-db';
import { writable } from 'svelte/store';

const db = new GitHubPocketDB({
	owner: 'your-username',
	repo: 'your-repo'
});

await db.init();

export const posts = writable([]);

export async function loadPosts() {
	const result = await db.collection('posts').getList();
	posts.set(result.items);
	return result.items;
}

Next.js Example

// lib/db.ts
import { GitHubPocketDB } from 'github-pocket-db';

const db = new GitHubPocketDB({
	owner: process.env.GITHUB_OWNER!,
	repo: process.env.GITHUB_REPO!
});

export async function getPosts() {
	await db.init();
	return db.collection('posts').getList();
}

📊 Performance & Caching

• Automatic caching with configurable TTL
• GitHub CDN for global file delivery
• Efficient pagination for large datasets
• Minimal API calls through smart caching

// Configure cache TTL (in seconds)
const db = new GitHubPocketDB({
	owner: 'user',
	repo: 'repo',
	cacheTTL: 600 // 10 minutes
});

🐛 Troubleshooting

Common Issues

Migration fails with "File not found"

# Ensure schema file exists
ls -la pb_schema.json

# Check file permissions
chmod 644 pb_schema.json

GitHub API rate limiting

// Add token to increase rate limits
const db = new GitHubPocketDB({
	owner: 'user',
	repo: 'repo',
	token: process.env.GITHUB_TOKEN // Increases limits from 60 to 5000/hour
});

Files not loading

// Ensure repository is public, or use token for private repos
// GitHub raw URLs require public repos for anonymous access

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Inspired by PocketBase for the amazing API design
• Built with Octokit for GitHub API integration
• Designed for the Jamstack and static site generation era

Made with ❤️ for developers who want simple, reliable, and free database solutions.