File Storage

FraiseQL provides file management capabilities with local filesystem and S3 storage backends.

Overview

File storage features:

• Multipart file uploads via GraphQL
• File type validation and size limits
• Image processing (resize, format conversion)
• S3-compatible storage backends
• Signed URLs for secure access

Configuration

Local Storage

[files]
enabled = true
backend = "local"

[files.local]
path = "/var/fraiseql/uploads"
url_prefix = "/files"

S3 Storage

[files]
enabled = true
backend = "s3"

[files.s3]
bucket = "my-app-files"
region = "us-east-1"
access_key_id = "${AWS_ACCESS_KEY_ID}"
secret_access_key = "${AWS_SECRET_ACCESS_KEY}"

# Optional: custom endpoint for S3-compatible storage
endpoint = "https://s3.example.com"

# URL generation
url_style = "path"  # or "virtual_hosted"

S3-Compatible Storage

MinIO

[files.s3]
bucket = "uploads"
endpoint = "http://minio:9000"
access_key_id = "${MINIO_ACCESS_KEY}"
secret_access_key = "${MINIO_SECRET_KEY}"
force_path_style = true

DigitalOcean Spaces

[files.s3]
bucket = "my-space"
region = "nyc3"
endpoint = "https://nyc3.digitaloceanspaces.com"
access_key_id = "${DO_SPACES_KEY}"
secret_access_key = "${DO_SPACES_SECRET}"

Cloudflare R2

[files.s3]
bucket = "my-bucket"
endpoint = "https://account-id.r2.cloudflarestorage.com"
access_key_id = "${R2_ACCESS_KEY}"
secret_access_key = "${R2_SECRET_KEY}"

File Upload

GraphQL Mutation

import fraiseql
from fraiseql import Upload

@fraiseql.type
class FileInfo:
    id: fraiseql.ID
    filename: str
    mime_type: str
    size: int
    url: str

@fraiseql.mutation(sql_source="fn_upload_file", operation="CREATE")
def upload_file(
    file: Upload,
    folder: str = "uploads"
) -> FileInfo:
    """Upload a file and return its info."""
    pass

Client Upload

JavaScript

const uploadFile = async (file) => {
    const formData = new FormData();

    // GraphQL multipart request format
    formData.append('operations', JSON.stringify({
        query: `
            mutation UploadFile($file: Upload!) {
                uploadFile(file: $file) {
                    id
                    filename
                    url
                }
            }
        `,
        variables: { file: null }
    }));

    formData.append('map', JSON.stringify({ '0': ['variables.file'] }));
    formData.append('0', file);

    const response = await fetch('/graphql', {
        method: 'POST',
        body: formData
    });

    return response.json();
};

Python

import httpx

def upload_file(file_path: str):
    with open(file_path, 'rb') as f:
        files = {
            'operations': (None, json.dumps({
                'query': '''
                    mutation UploadFile($file: Upload!) {
                        uploadFile(file: $file) { id url }
                    }
                ''',
                'variables': {'file': None}
            })),
            'map': (None, json.dumps({'0': ['variables.file']})),
            '0': (file_path, f, 'application/octet-stream')
        }

        response = httpx.post('http://localhost:8080/graphql', files=files)
        return response.json()

TypeScript

async function uploadFile(file: File): Promise<UploadResult> {
    const formData = new FormData();

    formData.append('operations', JSON.stringify({
        query: `
            mutation UploadFile($file: Upload!) {
                uploadFile(file: $file) { id url }
            }
        `,
        variables: { file: null }
    }));

    formData.append('map', JSON.stringify({ '0': ['variables.file'] }));
    formData.append('0', file);

    const response = await fetch('/graphql', {
        method: 'POST',
        body: formData
    });

    return response.json();
}

interface UploadResult {
    data?: {
        uploadFile: {
            id: string;
            url: string;
        };
    };
}

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "mime/multipart"
    "net/http"
    "os"
)

func uploadFile(filePath string) (map[string]interface{}, error) {
    file, err := os.Open(filePath)
    if err != nil {
        return nil, err
    }
    defer file.Close()

    body := &bytes.Buffer{}
    writer := multipart.NewWriter(body)

    operations := map[string]interface{}{
        "query": `mutation UploadFile($file: Upload!) { uploadFile(file: $file) { id url } }`,
        "variables": map[string]interface{}{"file": nil},
    }
    opsJSON, _ := json.Marshal(operations)
    writer.WriteField("operations", string(opsJSON))

    mapping := map[string][]string{"0": {"variables.file"}}
    mapJSON, _ := json.Marshal(mapping)
    writer.WriteField("map", string(mapJSON))

    part, _ := writer.CreateFormFile("0", filePath)
    io.Copy(part, file)
    writer.Close()

    req, _ := http.NewRequest("POST", "http://localhost:8080/graphql", body)
    req.Header.Set("Content-Type", writer.FormDataContentType())

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    return result, nil
}

File Validation

Size Limits

[files.limits]
max_file_size_mb = 50
max_request_size_mb = 100
max_files_per_request = 10

Type Validation

[files.validation]
# Allowed MIME types
allowed_types = [
    "image/jpeg",
    "image/png",
    "image/webp",
    "application/pdf",
    "text/csv"
]

# Or allow by extension
allowed_extensions = [".jpg", ".png", ".pdf", ".csv"]

# Validate actual content, not just extension
validate_content = true

Per-Field Limits

from typing import Annotated

@fraiseql.type
class Profile:
    avatar: Annotated[
        str,
        fraiseql.field(
            file_upload=True,
            max_size_mb=5,
            allowed_types=["image/jpeg", "image/png"]
        )
    ]

Image Processing

Configuration

[files.images]
enabled = true

# Generate thumbnails
[files.images.thumbnails]
enabled = true
sizes = [
    { name = "small", width = 150, height = 150 },
    { name = "medium", width = 300, height = 300 },
    { name = "large", width = 600, height = 600 }
]
fit = "cover"  # cover, contain, fill

# Format conversion
[files.images.conversion]
enabled = true
format = "webp"
quality = 85

Accessing Thumbnails

query {
    user(id: "123") {
        avatar  # Original
        avatarSmall: avatar(size: "small")
        avatarMedium: avatar(size: "medium")
    }
}

Signed URLs

Secure, time-limited access to files.

Configuration

[files.signed_urls]
enabled = true
expiry_seconds = 3600  # 1 hour
signing_key = "${FILE_SIGNING_KEY}"

Generate Signed URL

query {
    getFileUrl(fileId: "file-123", expiresIn: 300) {
        url
        expiresAt
    }
}

S3 Presigned URLs

[files.s3]
use_presigned_urls = true
presigned_url_expiry_seconds = 3600

File Metadata

Database Schema

CREATE TABLE tb_file (
    pk_file BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    id UUID DEFAULT gen_random_uuid() UNIQUE NOT NULL,
    filename TEXT NOT NULL,
    original_filename TEXT NOT NULL,
    mime_type TEXT NOT NULL,
    size_bytes BIGINT NOT NULL,
    storage_path TEXT NOT NULL,
    storage_backend TEXT NOT NULL DEFAULT 'local',
    checksum TEXT,  -- SHA-256
    metadata JSONB DEFAULT '{}',
    uploaded_by UUID REFERENCES tb_user(id),
    created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_file_uploaded_by ON tb_file(uploaded_by);
CREATE INDEX idx_file_mime_type ON tb_file(mime_type);

GraphQL Type

@fraiseql.type
class File:
    id: fraiseql.ID
    filename: str
    original_filename: str
    mime_type: str
    size_bytes: int
    url: str
    thumbnails: list[Thumbnail] | None
    uploaded_by: User | None
    created_at: fraiseql.DateTime

File Download

Direct Download

[files]
download_path = "/files"

Access files at:

GET /files/{file-id}/{filename}
GET /files/{file-id}/download  # Force download header

Streaming Large Files

[files.streaming]
enabled = true
chunk_size_kb = 64

Virus Scanning

ClamAV Integration

[files.scanning]
enabled = true
scanner = "clamav"

[files.scanning.clamav]
host = "clamav"
port = 3310
timeout_seconds = 30

# Action on infected file
on_infected = "reject"  # or "quarantine"

Metrics

Metric	Description
fraiseql_file_uploads_total	Total uploads
fraiseql_file_upload_bytes_total	Bytes uploaded
fraiseql_file_downloads_total	Total downloads
fraiseql_file_download_bytes_total	Bytes downloaded
fraiseql_file_upload_duration_ms	Upload latency
fraiseql_file_validation_failures_total	Validation failures

Best Practices

Use S3 for Production

# Development
[files]
backend = "local"

# Production
[files]
backend = "s3"

Validate All Uploads

[files.validation]
validate_content = true
allowed_types = ["image/jpeg", "image/png", "application/pdf"]
max_file_size_mb = 10

Caution

Always set validate_content = true to validate actual file content rather than trusting the file extension. This prevents malicious uploads disguised as allowed file types.

Use Signed URLs with Short Expiry

[files.signed_urls]
enabled = true
expiry_seconds = 300  # Short expiry for security

Enable Virus Scanning

[files.scanning]
enabled = true
scanner = "clamav"

Troubleshooting

Upload Fails

1. Check file size limits
2. Verify MIME type is allowed
3. Check storage permissions
4. Review virus scan results

S3 Access Denied

1. Verify credentials
2. Check bucket policy
3. Verify IAM permissions
4. Check CORS configuration

Slow Uploads

1. Enable streaming
2. Check network bandwidth
3. Use regional S3 endpoint
4. Consider multipart uploads

Next Steps

Security

Security — File access control

Deployment

Deployment — Production file storage