Fine

An open-source backend platform for building full-stack apps on Cloudflare.

Fine provides database access, authentication, file storage, and row-level security—all deployable to the edge with Cloudflare Workers, D1, and R2. Originally built to power Fine.dev, it's now available for anyone to self-host, extend, and contribute to.

---

✨ Features

• 🔐 Authentication – Session-based auth via email/password or magic links
• 🥮 D1 Database API – RESTful access with full CRUD support
• 📆 R2 File Storage – Entity-linked uploads, downloads, and permissions
• 🔐 Row-Level Security (RLS) – Policy-based access per user
• 🔐 Secrets Management – Secure config binding in Workers
• 🤖 AI Assistant Integration – Bring LLMs into your workflows (optional)

---

🚀 Quick Start

The simplest way to get started is by generating a project at https://fine.dev.

Setup and Deploy manually

1. Configure Cloudflare Workers
2. Set up D1 Database
3. Create R2 Bucket
4. Deploy the worker
5. Set up environment variables:

Environment Variables

• DB: D1 Database binding
• STORAGE_BUCKET: R2 Bucket binding for file storage
• BYPASS_AUTH: Set to true to bypass authentication (development only)
• VERSION: API version information

6. Run:

1npm install
2npm run dev

Before first run:

1npx wrangler d1 execute BAAS_DATABASE_NAME --local --file=./schema.sql

To deploy:

1npm run deploy

⚠️ Fine is currently in alpha. CLI and self-hosting workflows are actively improving.

---

🌐 Stay Connected

• 🗨️ Discord
• 🕊️ X
• 🌎 fine.dev

Built for builders. Powered by Cloudflare. Fully yours to self-host.

---

📂 Storage API

The Storage API allows clients to upload, download, and manage files, with access control tied to database entity permissions.

Architecture

Files are stored in Cloudflare R2 and linked to database entities. Access permissions are inherited from the database's Row-Level Security (RLS) policies - if a user has access to an entity, they can access its associated files.

Database Integration

All files are linked to database entities. To list files associated with any entity, you should query the database table directly. This ensures the database remains the single source of truth for file references.

File Organization

Files are stored in R2 with the following path structure:

{table}/{id}/{field}/{filename}

For example, a user's profile picture might be stored at:

users/user123/avatar/profile.jpg

API Endpoints

Upload a File

POST /storage/upload
Content-Type: multipart/form-data

Form Data:
- file: The file to upload
- entity: JSON object with {table, id, field}
- metadata: (optional) JSON object with custom metadata

Download a File

GET /storage/download/:table/:id/:field/:filename

Delete a File

DELETE /storage/delete/:table/:id/:field/:filename

Example Usage: User Profile Picture

Upload a profile picture:

1const formData = new FormData();
2formData.append('file', fileInput.files[0]);
3formData.append('entity', JSON.stringify({
4  table: 'users',
5  id: 'user123',
6  field: 'avatar'
7}));
8
9fetch('/storage/upload', {
10  method: 'POST',
11  body: formData,
12  headers: {
13    'Authorization': 'Bearer your-token'
14  }
15});

Display a profile picture:

1<img src="/storage/download/users/user123/avatar/profile.jpg" alt="Profile Picture">

Listing user profile pictures:

1// Query the database to find file references
2fetch('/db/tables/users?select=id,avatar')
3  .then(response => response.json())
4  .then(data => {
5    // Process the file references from the database
6    const users = data.data;
7    users.forEach(user => {
8      if (user.avatar) {
9        // Display avatar using the download endpoint
10        const avatarUrl = `/storage/download/users/${user.id}/avatar/${user.avatar}`;
11        // Use the URL as needed
12      }
13    });
14  });

Access Control

File operations inherit RLS policies from the referenced entity:

• To upload/update a file: User needs UPDATE permission on the entity
• To download files: User needs SELECT permission on the entity
• To delete a file: User needs DELETE permission on the entity

🔐 D1 Database API with Row Level Security

Before first run, you need to migrate the database:

npx wrangler d1 execute BAAS_DATABASE_NAME --local --file=./schema.sql  

Row Level Security (RLS)

This API implements Row Level Security, allowing you to define access policies at the row level. RLS restricts which rows can be retrieved by normal database operations based on user identity.

How RLS Works

1. Each database operation (SELECT/INSERT/UPDATE/DELETE) is filtered through security policies.
2. Policies define conditions for when operations are allowed.
3. Two types of security checks:
   • using_clause: Filters which rows users can SELECT, UPDATE, or DELETE
   • withcheck_clause: Filters which rows users can INSERT or UPDATE

Setting Up RLS Policies

Policies are stored in the _policies table. Here's how to create a policy:

1-- Example: Allow users to see only their own todos
2INSERT INTO _policies (table_name, action, using_clause) 
3VALUES ('todos', 'select', 'user_id = $$CURRENT_USER$$');
4
5-- Example: Allow users to insert only todos they own
6INSERT INTO _policies (table_name, action, withcheck_clause) 
7VALUES ('todos', 'insert', 'user_id = $$CURRENT_USER$$');
8
9-- Example: Allow users to update their own todos
10INSERT INTO _policies (table_name, action, using_clause, withcheck_clause) 
11VALUES (
12  'todos', 
13  'update', 
14  'user_id = $$CURRENT_USER$$', 
15  'user_id = $$CURRENT_USER$$'
16);
17
18-- Example: Allow users to delete their own todos
19INSERT INTO _policies (table_name, action, using_clause) 
20VALUES ('todos', 'delete', 'user_id = $$CURRENT_USER$$');

Special variables in policy expressions:

• $$CURRENT_USER$$: The ID of the authenticated user
• $$CURRENT_ROLE$$: The role of the authenticated user (if available)

Testing with cURL

Here are examples of how to use cURL to test the database endpoints:

SELECT - Get all records

1# Get all todos
2curl -X GET "http://localhost:8787/db/tables/todos"
3
4# Filter by field
5curl -X GET "http://localhost:8787/db/tables/todos?completed=false"
6
7# Advanced filtering, limit, and ordering
8curl -X GET "http://localhost:8787/db/tables/todos?title.like=important&limit=10&order=created_at%20DESC"

SELECT - Get a specific record

1# Get todo by ID
2curl -X GET "http://localhost:8787/db/tables/todos/123"

INSERT - Create a new record

1# Create a new todo
2curl -X POST "http://localhost:8787/db/tables/todos" \
3  -H "Content-Type: application/json" \
4  -d '{"title": "Buy groceries", "user_id": "user123", "completed": false}'

UPDATE - Update records

1# Update todo by ID
2curl -X PATCH "http://localhost:8787/db/tables/todos/123" \
3  -H "Content-Type: application/json" \
4  -d '{"completed": true}'
5
6# Update with a WHERE condition
7curl -X PATCH "http://localhost:8787/db/tables/todos" \
8  -H "Content-Type: application/json" \
9  -d '{
10    "data": {"completed": true},
11    "where": {"user_id": "user123"}
12  }'

DELETE - Delete records

1# Delete todo by ID
2curl -X DELETE "http://localhost:8787/db/tables/todos/123"
3
4# Delete with a WHERE condition
5curl -X DELETE "http://localhost:8787/db/tables/todos" \
6  -H "Content-Type: application/json" \
7  -d '{
8    "where": {"completed": true}
9  }'

Advanced filtering examples

1# Greater than
2curl -X GET "http://localhost:8787/db/tables/todos?priority.gt=3"
3
4# Less than or equal to
5curl -X GET "http://localhost:8787/db/tables/todos?created_at.lte=2023-12-31"
6
7# Not equal
8curl -X GET "http://localhost:8787/db/tables/todos?status.neq=cancelled"
9
10# LIKE pattern matching
11curl -X GET "http://localhost:8787/db/tables/todos?title.like=meeting"