SQLite databases deployed on Cloudflare Durable Objects with a REST API and CLI.
git clone https://github.com/layercodedev/sor.git
cd sor/worker
npm install
npm run deploy
export SOR_KEY=$(uuidgen)
echo $SOR_KEY
npx wrangler secret put SOR_API_KEY
echo "✓ API Key set. Configure your CLI with:"
echo " sor config set url https://sor.your-subdomain.workers.dev # Use URL from deploy output above"
echo " sor config set key $SOR_KEY"cd worker
export SOR_KEY=$(uuidgen)
echo "SOR_API_KEY=$SOR_KEY" > .dev.vars
npm run dev
echo "✓ Local dev server running. Configure your CLI with:"
echo " sor config set url http://localhost:8787"
echo " sor config set key $SOR_KEY"# Install globally (recommended)
npm install -g @layercode/sor
# Configure (if you didn't follow the config instructions above after deployment)
sor config set url https://your-worker.your-subdomain.workers.dev
sor config set key $SOR_KEYOr use without installing:
npx @layercode/sor config set url https://your-worker.your-subdomain.workers.devAdd SOR instructions to your AI coding assistant:
Claude:
sor init >> CLAUDE.mdCodex:
sor init >> AGENTS.mdNext time you use your coding agent, it will run sor init automatically and update its CLAUDE.md or AGENTS.md file will the full SOR usage instructions.
# Database management
sor db list # List all databases
sor db create mydb # Create a database
sor db create mydb --desc "My app db" # Create with description
sor db delete mydb # Delete a database
sor db schema mydb # Get database schema
# Execute SQL
sor sql mydb "SELECT * FROM users"
sor sql mydb "INSERT INTO users (name) VALUES (?)" -p '["Alice"]'
sor sql mydb "SELECT * FROM users" -o table # Output as table
sor sql mydb "SELECT * FROM users" -o csv # Output as CSV
# Migrations
sor migrate mydb 001_init "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"
sor migrations mydb # List applied migrations- Worker: Cloudflare Worker routing requests to Durable Objects
- Durable Objects: Each database is a separate DO with SQLite storage (up to 10GB)
- CLI: oclif-based CLI for managing databases and executing SQL
SOR uses a migration system for both user databases and the registry database:
User Database Migrations:
- Applied via
sor migratecommand orPOST /db/:name/migrate - Tracked in each database's
_sor_migrationstable - Ensures safe, atomic schema evolution
System Migrations (Registry):
- Automatically applied to the
_sor_registrydatabase - Defined in
worker/src/system-migrations.ts - Applied on first request after deployment (idempotent)
- Uses the same migration infrastructure as user databases
To add a new system migration:
// worker/src/system-migrations.ts
export const SYSTEM_MIGRATIONS = [
// ... existing migrations
{
name: "002_add_new_column",
sql: "ALTER TABLE dbs ADD COLUMN new_column TEXT"
}
];Deploy the worker and the migration will apply automatically on the next request.
All endpoints require X-API-Key header.
| Method | Endpoint | Description |
|---|---|---|
| GET | /dbs |
List databases |
| POST | /dbs |
Create database {"name": "dbname"} |
| DELETE | /dbs/:name |
Delete database |
| POST | /db/:name/sql |
Execute SQL {"sql": "...", "params": []} |
| POST | /db/:name/migrate |
Run migration {"name": "...", "sql": "..."} |
| GET | /db/:name/migrations |
List migrations |
| GET | /db/:name/schema |
Get database schema |
# Worker
cd worker
npm install
npm test # Run worker tests
npm run dev # Start local dev server
# CLI
cd cli
npm install
npm run build # Build CLI
npm test # Run CLI tests
npm link # Link CLI for local development