cloudflare-d1 0.1.0

data/README.md

@@ -0,0 +1,253 @@
+# Cloudflare D1 Gem
+
+[![CI](https://github.com/your-username/cloudflare-d1/actions/workflows/ci.yml/badge.svg)](https://github.com/your-username/cloudflare-d1/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/cloudflare-d1.svg)](https://badge.fury.io/rb/cloudflare-d1)
+
+Ruby adapters for [Cloudflare D1](https://developers.cloudflare.com/d1/) - SQLite at the edge.
+
+Provides both **ActiveRecord** and **Sequel** adapters to use D1 databases from Ruby applications.
+
+## Features
+
+- **ActiveRecord adapter** - Full Rails integration with migrations
+- **Sequel adapter** - Lightweight ORM for non-Rails apps
+- **Database management** - Rake tasks for creating/dropping databases
+- **Local development** - Use local SQLite for dev, D1 for production
+- **Cloudflare Containers** - Example Roda app deployable to Cloudflare
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "cloudflare-d1"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install cloudflare-d1
+```
+
+## Usage
+
+### ActiveRecord (Rails)
+
+Configure in `config/database.yml`:
+
+```yaml
+production:
+  adapter: cloudflare_d1
+  account_id: <%= ENV['CLOUDFLARE_ACCOUNT_ID'] %>
+  api_token: <%= ENV['CLOUDFLARE_API_TOKEN'] %>
+  database_id: <%= ENV['DATABASE_ID'] %>
+```
+
+Use standard ActiveRecord:
+
+```ruby
+class User < ActiveRecord::Base
+end
+
+# CRUD operations
+user = User.create(name: "Alice", email: "alice@example.com")
+User.where(email: "alice@example.com").first
+user.update(name: "Alice Smith")
+user.destroy
+```
+
+Run migrations:
+
+```bash
+rake db:create      # Create D1 database
+rake db:migrate     # Run migrations
+rake db:rollback    # Rollback migrations
+```
+
+### Sequel (Non-Rails)
+
+Connect to D1:
+
+```ruby
+require "sequel"
+require "sequel/adapters/cloudflare_d1"
+
+DB = Sequel.connect(
+  adapter: :cloudflare_d1,
+  account_id: ENV["CLOUDFLARE_ACCOUNT_ID"],
+  api_token: ENV["CLOUDFLARE_API_TOKEN"],
+  database: ENV["DATABASE_ID"]
+)
+
+# Use Sequel
+DB[:users].insert(name: "Bob", email: "bob@example.com")
+DB[:users].where(email: "bob@example.com").all
+DB[:users].where(id: 1).update(name: "Robert")
+DB[:users].where(id: 1).delete
+```
+
+Run migrations:
+
+```bash
+rake sequel:db:migrate
+```
+
+## Local Development
+
+For local development, use SQLite directly instead of making API calls:
+
+```ruby
+# config/database.yml
+development:
+  adapter: sqlite3
+  database: db/development.sqlite3
+
+production:
+  adapter: cloudflare_d1
+  account_id: <%= ENV['CLOUDFLARE_ACCOUNT_ID'] %>
+  api_token: <%= ENV['CLOUDFLARE_API_TOKEN'] %>
+  database_id: <%= ENV['DATABASE_ID'] %>
+```
+
+Or for Sequel:
+
+```ruby
+if ENV["RACK_ENV"] == "production"
+  DB = Sequel.connect(adapter: :cloudflare_d1, ...)
+else
+  DB = Sequel.connect("sqlite://db/development.db")
+end
+```
+
+## Examples
+
+### Roda + Cloudflare Containers
+
+See the complete example in [`examples/roda/`](examples/roda/):
+
+```bash
+cd examples/roda
+./setup.sh  # Automated setup and deployment
+```
+
+Features:
+- Full CRUD API
+- Automatic migrations
+- Deployable to Cloudflare Containers
+- Local development with SQLite
+
+## Configuration
+
+### Environment Variables
+
+Set these environment variables:
+
+```bash
+export CLOUDFLARE_ACCOUNT_ID=your_account_id
+export CLOUDFLARE_API_TOKEN=your_api_token
+export DATABASE_ID=your_database_uuid
+```
+
+Get your credentials:
+- **Account ID**: `wrangler whoami` or Cloudflare dashboard
+- **API Token**: Dashboard → My Profile → API Tokens
+  - Create token with "Edit Cloudflare Workers" template
+  - Include D1 Database permissions
+- **Database ID**: `wrangler d1 create my-database`
+
+### Creating a D1 Database
+
+Using Wrangler:
+
+```bash
+wrangler d1 create my-database
+```
+
+Or using the gem:
+
+```bash
+# ActiveRecord
+rake db:create
+
+# Sequel
+DATABASE_NAME=my-database rake sequel:db:create
+```
+
+## Rake Tasks
+
+### ActiveRecord
+
+```bash
+rake db:create              # Create D1 database
+rake db:drop                # Drop D1 database
+rake db:list                # List all D1 databases
+rake db:migrate             # Run migrations
+rake db:rollback            # Rollback migrations
+rake db:migrate_status      # Show migration status
+rake db:reset               # Drop, create, migrate
+rake db:setup               # Create and migrate
+```
+
+### Sequel
+
+```bash
+rake sequel:db:create       # Create D1 database
+rake sequel:db:drop         # Drop D1 database
+rake sequel:db:list         # List all D1 databases
+rake sequel:db:migrate      # Run migrations
+rake sequel:db:rollback     # Rollback migrations
+rake sequel:db:status       # Show migration status
+rake sequel:db:reset        # Drop, create, migrate
+rake sequel:db:setup        # Create and migrate
+```
+
+## Limitations
+
+Due to D1's architecture:
+
+- **No DDL transactions** - Schema changes aren't wrapped in transactions
+- **No savepoints** - Transaction savepoints not supported
+- **No connection pooling** - Each query is an HTTP request
+- **API-only access** - D1 is not directly accessible outside Cloudflare
+
+These are D1 limitations, not gem limitations.
+
+## Development
+
+After checking out the repo:
+
+```bash
+bundle install
+rake test
+```
+
+To install this gem onto your local machine:
+
+```bash
+bundle exec rake install
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## Releasing
+
+See [RELEASING.md](RELEASING.md) for release instructions.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Links
+
+- [Cloudflare D1 Documentation](https://developers.cloudflare.com/d1/)
+- [Cloudflare Containers](https://developers.cloudflare.com/containers/)
+- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)
+- [RubyGems](https://rubygems.org/gems/cloudflare-d1)

data/RELEASING.md

@@ -0,0 +1,199 @@
+# Releasing cloudflare-d1 Gem
+
+This document describes the process for releasing new versions of the `cloudflare-d1` gem.
+
+## Prerequisites
+
+### 1. RubyGems API Key
+
+Set up your RubyGems API key as a GitHub secret:
+
+1. Get your API key from [RubyGems.org](https://rubygems.org/profile/edit)
+   - Sign in to RubyGems
+   - Go to "Edit Profile"
+   - Under "API Access", create a new API key with push permissions
+
+2. Add to GitHub repository secrets:
+   - Go to repository Settings → Secrets and variables → Actions
+   - Click "New repository secret"
+   - Name: `RUBYGEMS_API_KEY`
+   - Value: Your RubyGems API key
+
+### 2. Repository Permissions
+
+Make sure you have:
+- Write access to the repository
+- Permission to push tags
+- Permission to create releases
+
+## Release Process
+
+### 1. Update Version
+
+Edit `lib/cloudflare/d1/version.rb`:
+
+```ruby
+module Cloudflare
+  module D1
+    VERSION = "0.2.0"  # Update this
+  end
+end
+```
+
+### 2. Update Changelog
+
+Edit `CHANGELOG.md`:
+
+```markdown
+## [0.2.0] - 2024-01-15
+
+### Added
+- New feature description
+
+### Changed
+- Changed feature description
+
+### Fixed
+- Bug fix description
+```
+
+### 3. Commit Changes
+
+```bash
+git add lib/cloudflare/d1/version.rb CHANGELOG.md
+git commit -m "Bump version to 0.2.0"
+git push origin master
+```
+
+### 4. Create and Push Tag
+
+```bash
+# Create annotated tag
+git tag -a v0.2.0 -m "Release version 0.2.0"
+
+# Push tag to trigger release workflow
+git push origin v0.2.0
+```
+
+### 5. Watch Release Build
+
+The GitHub Actions workflow will automatically:
+1. Run all tests
+2. Build the gem
+3. Publish to RubyGems.org
+4. Create GitHub release with gem artifact
+5. Generate release notes
+
+Monitor the workflow at:
+https://github.com/your-username/cloudflare-d1/actions
+
+### 6. Verify Release
+
+Check that the gem is available:
+
+```bash
+gem list cloudflare-d1 --remote --all
+```
+
+Or visit: https://rubygems.org/gems/cloudflare-d1
+
+## Manual Release (If Needed)
+
+If automated release fails:
+
+```bash
+# Build gem
+gem build cloudflare-d1.gemspec
+
+# Test locally (optional)
+gem install ./cloudflare-d1-0.2.0.gem
+
+# Push to RubyGems
+gem push cloudflare-d1-0.2.0.gem
+```
+
+## Versioning
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** version (1.0.0): Breaking changes
+- **MINOR** version (0.2.0): New features, backward compatible
+- **PATCH** version (0.1.1): Bug fixes, backward compatible
+
+Examples:
+- `0.1.0` → `0.2.0`: Added Sequel adapter (new feature)
+- `0.2.0` → `0.2.1`: Fixed connection bug (bug fix)
+- `0.2.1` → `1.0.0`: Changed API (breaking change)
+
+## Troubleshooting
+
+### Release workflow failed
+
+Check the Actions logs:
+```bash
+# View recent workflow runs
+gh run list --workflow=release.yml
+
+# View logs for specific run
+gh run view <run-id> --log
+```
+
+Common issues:
+- **Tests failed**: Fix tests and create new tag
+- **RubyGems authentication failed**: Check `RUBYGEMS_API_KEY` secret
+- **Gem already exists**: Version already published, bump version
+
+### Yank a release (if needed)
+
+If you need to remove a problematic release:
+
+```bash
+gem yank cloudflare-d1 -v 0.2.0
+```
+
+**Note:** Only yank for serious issues (security, broken functionality). Prefer releasing a patch version instead.
+
+## Release Checklist
+
+Before releasing:
+
+- [ ] All tests pass locally
+- [ ] RuboCop violations fixed
+- [ ] Version bumped in `version.rb`
+- [ ] CHANGELOG updated
+- [ ] README updated (if needed)
+- [ ] Examples tested
+- [ ] Breaking changes documented
+
+After releasing:
+
+- [ ] Gem appears on RubyGems.org
+- [ ] GitHub release created
+- [ ] Release notes look good
+- [ ] Announcement (optional):
+  - Twitter/X
+  - Ruby Weekly
+  - Blog post
+
+## Pre-release Versions
+
+For beta/RC releases:
+
+```ruby
+# lib/cloudflare/d1/version.rb
+VERSION = "0.2.0.beta.1"
+```
+
+```bash
+git tag -a v0.2.0.beta.1 -m "Release version 0.2.0.beta.1"
+git push origin v0.2.0.beta.1
+```
+
+Install pre-release:
+```bash
+gem install cloudflare-d1 --pre
+```
+
+## Questions?
+
+Open an issue or discussion on GitHub.

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/cloudflare-d1.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "lib/cloudflare/d1/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "cloudflare-d1"
+  spec.version = Cloudflare::D1::VERSION
+  spec.authors = ["Ben"]
+  spec.email = ["ben@dee.mx"]
+
+  spec.summary = "ActiveRecord and Sequel adapters for Cloudflare D1 databases"
+  spec.description = "Custom ActiveRecord and Sequel adapters that allow Ruby applications to use Cloudflare D1 databases via the REST API"
+  spec.homepage = "https://github.com/ben/cloudflare-d1"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/ben/cloudflare-d1"
+  spec.metadata["changelog_uri"] = "https://github.com/ben/cloudflare-d1/blob/master/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Development dependencies
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rubocop", "~> 1.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "webmock", "~> 3.0"
+  spec.add_development_dependency "activerecord", ">= 6.0"
+  spec.add_development_dependency "sequel", ">= 5.0"
+end

data/examples/roda/.dockerignore

@@ -0,0 +1,14 @@
+.git
+.gitignore
+README.md
+.env
+.env.*
+*.log
+tmp/
+log/
+coverage/
+.bundle/
+vendor/bundle
+.rspec
+spec/
+test/

data/examples/roda/.gitignore

@@ -0,0 +1,11 @@
+.env
+.env.*
+*.log
+tmp/
+log/
+.bundle/
+vendor/bundle
+.wrangler/
+db/*.db
+db/*.db-shm
+db/*.db-wal

data/examples/roda/Dockerfile

@@ -0,0 +1,21 @@
+FROM ruby:3.2-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy Gemfile and install dependencies
+COPY Gemfile Gemfile.lock ./
+RUN bundle install --without development test
+
+# Copy application code
+COPY . .
+
+# Expose port
+EXPOSE 8080
+
+# Run the application
+CMD ["ruby", "app.rb"]

data/examples/roda/Gemfile

@@ -0,0 +1,12 @@
+source "https://rubygems.org"
+
+gem "roda", "~> 3.0"
+gem "puma", "~> 6.0"
+gem "sequel", "~> 5.0"
+gem "cloudflare-d1", path: "../.."
+gem "rack", "~> 3.0"
+
+group :development, :test do
+  gem "sqlite3", "~> 1.6"  # Local SQLite for development
+  gem "rackup"
+end

data/examples/roda/Gemfile.lock

@@ -0,0 +1,35 @@
+PATH
+  remote: ../..
+  specs:
+    cloudflare-d1 (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    bigdecimal (3.3.1)
+    nio4r (2.7.5)
+    puma (6.6.1)
+      nio4r (~> 2.0)
+    rack (3.2.4)
+    rackup (2.2.1)
+      rack (>= 3)
+    rake (13.3.1)
+    roda (3.97.0)
+      rack
+    sequel (5.98.0)
+      bigdecimal
+
+PLATFORMS
+  arm64-darwin-24
+
+DEPENDENCIES
+  cloudflare-d1!
+  puma (~> 6.0)
+  rack (~> 3.0)
+  rackup
+  rake
+  roda (~> 3.0)
+  sequel (~> 5.0)
+
+BUNDLED WITH
+   2.4.19