cloudflare-d1 0.1.0

data/examples/roda/README.md

@@ -0,0 +1,459 @@
+# Roda + Cloudflare D1 + Containers Example
+
+This example demonstrates deploying a Roda application using Cloudflare Containers with a D1 database backend.
+
+## Architecture
+
+```
+Internet Request
+    ↓
+Cloudflare Worker (worker.js)
+    ↓
+Container Instance (Durable Object)
+    ↓
+Roda App (Ruby)
+    ↓
+Cloudflare D1 Database (SQLite via REST API)
+```
+
+## Features
+
+- **Roda** - Fast, simple Ruby web framework
+- **Sequel** - Database toolkit for Ruby
+- **Cloudflare D1** - SQLite database at the edge
+- **Cloudflare Containers** - Run containerized apps on Workers
+- **RESTful API** - Full CRUD operations for users
+
+## Prerequisites
+
+1. **Cloudflare Account** with Workers Paid plan
+2. **Wrangler CLI**:
+   ```bash
+   npm install -g wrangler
+   wrangler login
+   ```
+3. **Docker** running locally
+4. **Ruby 3.2+** (for local development)
+
+## Setup
+
+### 1. Create D1 Database
+
+```bash
+# Create a new D1 database
+wrangler d1 create roda-api-db
+
+# Note the database ID from the output
+# Add it to your secrets (see step 3)
+```
+
+### 2. Install Dependencies
+
+```bash
+bundle install
+```
+
+### 3. Configure Secrets
+
+Set your Cloudflare credentials and database ID as Worker secrets:
+
+```bash
+# Your Cloudflare account ID
+wrangler secret put CLOUDFLARE_ACCOUNT_ID
+# Enter: your_account_id
+
+# Your Cloudflare API token (needs D1 permissions)
+wrangler secret put CLOUDFLARE_API_TOKEN
+# Enter: your_api_token
+
+# Your D1 database UUID (from step 1)
+wrangler secret put DATABASE_ID
+# Enter: your_database_uuid
+```
+
+These secrets are stored in the Worker and passed to the container at runtime via `worker.js`.
+
+**To get your credentials:**
+- Account ID: `wrangler whoami` or Cloudflare dashboard
+- API Token: Dashboard → My Profile → API Tokens → Create Token
+  - Template: "Edit Cloudflare Workers"
+  - Permissions: Include D1 Database permissions
+
+### 4. Update wrangler.jsonc
+
+Edit `wrangler.jsonc` and update:
+- `name`: Must be unique across Cloudflare (change `roda-d1-api` to something unique)
+- `routes`: Optional, configure custom domain
+
+## Local Development
+
+The app uses **local SQLite** for development (since D1 is only accessible via Cloudflare's API).
+
+### Run Locally
+
+```bash
+# Install dependencies
+bundle install
+
+# Run the app (uses local SQLite)
+ruby app.rb
+```
+
+**No environment variables needed** - it automatically uses `db/development.db`.
+
+### Test Locally
+
+```bash
+# Create a user
+curl -X POST http://localhost:8080/users \
+  -H "Content-Type: application/json" \
+  -d '{"name": "John Doe", "email": "john@example.com"}'
+
+# List users
+curl http://localhost:8080/users
+
+# Get user by ID
+curl http://localhost:8080/users/1
+
+# Update user
+curl -X PUT http://localhost:8080/users/1 \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Jane Doe"}'
+
+# Delete user
+curl -X DELETE http://localhost:8080/users/1
+```
+
+### How It Works
+
+The app detects the environment:
+
+```ruby
+if ENV["RACK_ENV"] == "production"
+  # Use Cloudflare D1 (in container)
+  DB = Sequel.connect(adapter: :cloudflare_d1, ...)
+else
+  # Use local SQLite (in development)
+  DB = Sequel.connect("sqlite://db/development.db")
+end
+```
+
+**In production** (container): Uses D1 via HTTP API
+**In development** (local): Uses SQLite file directly
+
+Same migrations work for both!
+
+### Alternative: Test Against Real D1
+
+If you need to test against the actual D1 database:
+
+```bash
+# Set environment variables
+export RACK_ENV=production
+export CLOUDFLARE_ACCOUNT_ID=your_account_id
+export CLOUDFLARE_API_TOKEN=your_api_token
+export DATABASE_ID=your_database_uuid
+
+# Run locally (will use D1 API)
+ruby app.rb
+```
+
+**Note:** This makes real HTTP requests to Cloudflare's API on every query (slow for development).
+
+## Deployment
+
+### 1. Deploy to Cloudflare
+
+```bash
+# Make sure Docker is running
+docker info
+
+# Deploy the application
+wrangler deploy
+```
+
+**Note:** First deployment takes several minutes as Cloudflare provisions container infrastructure.
+
+**Migrations run automatically** when the container starts. No manual migration step needed.
+
+### 2. Check Status
+
+```bash
+# List containers
+wrangler containers list
+
+# List container images
+wrangler containers images list
+
+# View logs
+wrangler tail
+```
+
+### 3. Test Deployed App
+
+```bash
+# Replace with your deployed URL
+export API_URL=https://roda-d1-api.your-subdomain.workers.dev
+
+# Health check
+curl $API_URL/health
+
+# Create user
+curl -X POST $API_URL/users \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Alice", "email": "alice@example.com"}'
+
+# List users
+curl $API_URL/users
+
+# Get user
+curl $API_URL/users/1
+```
+
+## API Endpoints
+
+### Root
+```
+GET /
+```
+Returns API information and available endpoints.
+
+### Users
+
+#### List all users
+```
+GET /users
+```
+
+Response:
+```json
+{
+  "users": [
+    {
+      "id": 1,
+      "name": "John Doe",
+      "email": "john@example.com",
+      "created_at": "2024-01-01T00:00:00Z",
+      "updated_at": "2024-01-01T00:00:00Z"
+    }
+  ]
+}
+```
+
+#### Get user by ID
+```
+GET /users/:id
+```
+
+Response:
+```json
+{
+  "user": {
+    "id": 1,
+    "name": "John Doe",
+    "email": "john@example.com",
+    "created_at": "2024-01-01T00:00:00Z",
+    "updated_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+#### Create user
+```
+POST /users
+Content-Type: application/json
+
+{
+  "name": "John Doe",
+  "email": "john@example.com"
+}
+```
+
+Response: `201 Created`
+```json
+{
+  "user": {
+    "id": 1,
+    "name": "John Doe",
+    "email": "john@example.com",
+    "created_at": "2024-01-01T00:00:00Z",
+    "updated_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+#### Update user
+```
+PUT /users/:id
+Content-Type: application/json
+
+{
+  "name": "Jane Doe",
+  "email": "jane@example.com"
+}
+```
+
+Response:
+```json
+{
+  "user": {
+    "id": 1,
+    "name": "Jane Doe",
+    "email": "jane@example.com",
+    "created_at": "2024-01-01T00:00:00Z",
+    "updated_at": "2024-01-01T00:00:01Z"
+  }
+}
+```
+
+#### Delete user
+```
+DELETE /users/:id
+```
+
+Response: `204 No Content`
+
+## Migrations
+
+Migrations run automatically on container boot. To add a new migration:
+
+1. Create a file in `db/migrations/` with format `00X_description.rb`:
+   ```ruby
+   # db/migrations/002_add_age_to_users.rb
+   Sequel.migration do
+     up do
+       alter_table(:users) do
+         add_column :age, Integer
+       end
+     end
+
+     down do
+       alter_table(:users) do
+         drop_column :age
+       end
+     end
+   end
+   ```
+
+2. Deploy:
+   ```bash
+   wrangler deploy  # Migration runs on boot
+   ```
+
+## Project Structure
+
+```
+examples/roda/
+├── Dockerfile           # Container image definition
+├── Gemfile             # Ruby dependencies
+├── Gemfile.lock        # Locked dependency versions
+├── app.rb              # Roda application
+├── worker.js           # Cloudflare Worker (routes to container)
+├── wrangler.jsonc      # Cloudflare deployment configuration
+├── db/
+│   └── migrations/     # Database migrations (run on boot)
+└── README.md           # This file
+```
+
+## Configuration
+
+### Container Settings (wrangler.jsonc)
+
+- **max_instances**: Maximum concurrent container instances (default: 10)
+- **instance_type**: Container size - `lite`, `basic`, `standard-1` through `standard-4`
+- **sleepAfter**: How long to keep container alive after inactivity (default: "10m")
+
+### Worker Routing Strategies
+
+The `worker.js` file uses a single stateful container instance:
+
+```javascript
+const containerStub = env.RODA_CONTAINER.getByName("main");
+```
+
+**Alternative strategies:**
+
+1. **Load balanced (stateless)**:
+   ```javascript
+   const id = Math.floor(Math.random() * 3);
+   const containerStub = env.RODA_CONTAINER.getById(id.toString());
+   ```
+
+2. **Session-based (sticky sessions)**:
+   ```javascript
+   const sessionId = request.headers.get("X-Session-ID") || "default";
+   const containerStub = env.RODA_CONTAINER.getByName(sessionId);
+   ```
+
+## Troubleshooting
+
+### Container not starting
+
+Check logs:
+```bash
+wrangler tail
+```
+
+Verify Docker is running:
+```bash
+docker info
+```
+
+### Database connection errors
+
+Verify secrets are set:
+```bash
+wrangler secret list
+```
+
+Test D1 connection:
+```bash
+wrangler d1 execute roda-api-db --command="SELECT 1"
+```
+
+### Build errors
+
+Clear Docker cache:
+```bash
+docker system prune -a
+```
+
+Rebuild:
+```bash
+wrangler deploy
+```
+
+### "Class not found" errors
+
+Make sure:
+- `class_name` matches between `containers` and `durable_objects.bindings`
+- `new_sqlite_classes` includes the class name
+- You've run `wrangler deploy` after changing configuration
+
+## Development Tips
+
+1. **Use local Ruby for faster iteration** - Test changes locally before deploying
+2. **Monitor logs** - Keep `wrangler tail` running during development
+3. **Version your migrations** - Use Sequel migrations for database changes
+4. **Test error handling** - Containers can fail, handle errors gracefully
+5. **Monitor costs** - Containers use compute time, monitor usage in dashboard
+
+## Limitations
+
+- Container cold starts take a few seconds
+- Maximum 10 concurrent instances (configurable)
+- No persistent filesystem (use D1 for data)
+- Must use linux/amd64 architecture
+- Requires Workers Paid plan
+
+## Learn More
+
+- [Cloudflare Containers](https://developers.cloudflare.com/containers/)
+- [Cloudflare D1](https://developers.cloudflare.com/d1/)
+- [Roda Framework](http://roda.jeremyevans.net/)
+- [Sequel ORM](https://sequel.jeremyevans.net/)
+- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)
+
+## License
+
+MIT

data/examples/roda/app.rb

@@ -0,0 +1,165 @@
+require "roda"
+require "sequel"
+require "sequel/adapters/cloudflare_d1"
+require "json"
+
+# Connect to database
+# In development: Use local SQLite
+# In production: Use Cloudflare D1 via API
+if ENV["RACK_ENV"] == "production"
+  DB = Sequel.connect(
+    adapter: :cloudflare_d1,
+    account_id: ENV["CLOUDFLARE_ACCOUNT_ID"],
+    api_token: ENV["CLOUDFLARE_API_TOKEN"],
+    database: ENV["DATABASE_ID"]
+  )
+else
+  # Local development with SQLite
+  DB = Sequel.connect("sqlite://db/development.db")
+end
+
+# Run migrations on startup
+Sequel.extension :migration
+puts "Running migrations..."
+Sequel::Migrator.run(DB, File.join(__dir__, "db/migrations"))
+puts "Migrations complete!"
+
+class App < Roda
+  plugin :json
+  plugin :all_verbs
+  plugin :status_handler
+  plugin :error_handler
+
+  status_handler(404) do
+    { error: "Not found" }
+  end
+
+  error_handler do |e|
+    { error: e.message }
+  end
+
+  route do |r|
+    r.root do
+      {
+        message: "Cloudflare D1 + Roda API",
+        version: "1.0.0",
+        endpoints: {
+          users: {
+            list: "GET /users",
+            show: "GET /users/:id",
+            create: "POST /users",
+            update: "PUT /users/:id",
+            delete: "DELETE /users/:id"
+          }
+        }
+      }
+    end
+
+    r.on "users" do
+      r.is do
+        # GET /users - List all users
+        r.get do
+          users = DB[:users].all
+          { users: users }
+        end
+
+        # POST /users - Create a new user
+        r.post do
+          data = JSON.parse(r.body.read)
+
+          unless data["name"] && data["email"]
+            response.status = 400
+            next { error: "Name and email are required" }
+          end
+
+          begin
+            user_id = DB[:users].insert(
+              name: data["name"],
+              email: data["email"],
+              created_at: Time.now,
+              updated_at: Time.now
+            )
+
+            user = DB[:users].where(id: user_id).first
+            response.status = 201
+            { user: user }
+          rescue Sequel::UniqueConstraintViolation
+            response.status = 422
+            { error: "Email already exists" }
+          end
+        end
+      end
+
+      r.on Integer do |user_id|
+        r.is do
+          # GET /users/:id - Get a specific user
+          r.get do
+            user = DB[:users].where(id: user_id).first
+
+            unless user
+              response.status = 404
+              next { error: "User not found" }
+            end
+
+            { user: user }
+          end
+
+          # PUT /users/:id - Update a user
+          r.put do
+            user = DB[:users].where(id: user_id).first
+
+            unless user
+              response.status = 404
+              next { error: "User not found" }
+            end
+
+            data = JSON.parse(r.body.read)
+
+            begin
+              DB[:users].where(id: user_id).update(
+                name: data["name"] || user[:name],
+                email: data["email"] || user[:email],
+                updated_at: Time.now
+              )
+
+              updated_user = DB[:users].where(id: user_id).first
+              { user: updated_user }
+            rescue Sequel::UniqueConstraintViolation
+              response.status = 422
+              { error: "Email already exists" }
+            end
+          end
+
+          # DELETE /users/:id - Delete a user
+          r.delete do
+            user = DB[:users].where(id: user_id).first
+
+            unless user
+              response.status = 404
+              next { error: "User not found" }
+            end
+
+            DB[:users].where(id: user_id).delete
+            response.status = 204
+            ""
+          end
+        end
+      end
+    end
+  end
+end
+
+# Run the application with Puma
+require "puma"
+
+port = ENV.fetch("PORT", 8080).to_i
+
+puts "Starting Roda + Cloudflare D1 API on port #{port}..."
+puts "Database: #{ENV['DATABASE_ID']}"
+
+Rack::Handler::Puma.run(
+  App.freeze.app,
+  Port: port,
+  Host: "0.0.0.0",
+  Threads: "1:5"
+)

data/examples/roda/db/migrations/001_create_users.rb

@@ -0,0 +1,17 @@
+Sequel.migration do
+  up do
+    create_table(:users) do
+      primary_key :id
+      String :name, null: false
+      String :email, null: false
+      DateTime :created_at
+      DateTime :updated_at
+
+      index :email, unique: true
+    end
+  end
+
+  down do
+    drop_table(:users)
+  end
+end