File Storage

FileField और ImageField uploaded files को एक storage backend के माध्यम से store करते हैं, जिसे आप field के storage parameter से सेट करते हैं।

Storage backend एक बार बनाएँ और उसी location में files रखने वाले हर field पर reuse करें।

Minimal example

from contextlib import asynccontextmanager

from fastapi import FastAPI
from sqlalchemy import JSON, Integer, String, create_engine
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from starlette_admin import ImageField
from starlette_admin.contrib.sqla import Admin, ModelView
from starlette_admin.storage import LocalStorage

engine = create_engine("sqlite:///admin.sqlite")

local = LocalStorage(base_dir="uploads", name="local")


class Base(DeclarativeBase):
    pass


class Book(Base):
    __tablename__ = "book"

    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    title: Mapped[str] = mapped_column(String(200))
    cover: Mapped[dict | None] = mapped_column(JSON, nullable=True)


class BookView(ModelView):
    fields = [
        "id",
        "title",
        ImageField("cover", storage=local, upload_folder="covers"),
    ]


@asynccontextmanager
async def lifespan(app: FastAPI):
    Base.metadata.create_all(engine)
    yield


app = FastAPI(lifespan=lifespan)

admin = Admin(engine, title="Bookstore", secret_key="change-me")
admin.add_view(BookView(Book))
admin.mount_to(app)

जब user admin के माध्यम से cover upload करता है, admin:

• file को uploads/covers/ में save करता है
• cover column में JSON metadata object store करता है

Database में कभी file स्वयं, filesystem path, या binary data नहीं रहता।

Database में क्या store होता है

Admin file upload को model field में serialized FileInfo object के रूप में represent करता है।

{
  "filename": "product-photo.jpg",
  "content_type": "image/jpeg",
  "size": 204800,
  "storage": "s3",
  "key": "uploads/products/a1b2c3_product-photo.jpg",
  "url": "https://..."
}

• filename: sanitized original filename, display के लिए उपयोगी
• content_type: upload के समय detect किया गया MIME type
• size: bytes में file size
• storage: registered backend name — URL generation और deletion के लिए file location resolve करने में उपयोगी
• key: storage-relative path या object key
• url: cached public URL

LocalStorage खाली url value store करता है, क्योंकि URLs active request पर निर्भर करते हैं। S3Storage public या presigned URL store करता है, आपकी configuration के अनुसार।

Backend कुछ भी हो, FileField render time पर stored value पर भरोसा करने के बजाय URL को storage.url() से regenerate करता है।

ImageField width और height जोड़ता है।

Admin हर filename को store करने से पहले secure_filename से sanitize करता है: path components strip करता है और [A-Za-z0-9_.-] से बाहर के characters _ से replace कर देता है। Security देखें।

Storage backends

Local storage

from starlette_admin.storage import LocalStorage

local = LocalStorage(base_dir="uploads", name="local")

Admin files इस route के माध्यम से serve करता है:

/_files/{storage}/{path}

आपको किसी extra static file configuration की आवश्यकता नहीं।

LocalStorage.url() current request context से URLs बनाता है, इसलिए stored url field खाली रहता है और on demand recompute होता है।

Amazon S3 storage

from starlette_admin.storage import S3Storage

s3 = S3Storage(
    bucket="my-bucket",
    prefix="admin/",
    region="eu-west-1",
    public=False,
)

Optional dependencies इंस्टॉल करें:

pip install starlette-admin[s3]

इससे aiobotocore इंस्टॉल होता है।

जब आप endpoint_url provide करते हैं, तब admin URLs इस रूप में बनाता है:

{endpoint_url}/{bucket}/{key}

AWS virtual-hosted format का उपयोग करने के बजाय।

Multiple files (multiple=True)

एक ही field में कई uploads accept करने के लिए FileField या ImageField पर multiple=True सेट करें।

from starlette_admin import FileField
from starlette_admin.contrib.sqla import ModelView
from starlette_admin.storage import LocalStorage

local = LocalStorage(base_dir="uploads/attachments", name="attachments")


class TicketView(ModelView):
    fields = [
        "id",
        "subject",
        FileField(
            "attachments",
            storage=local,
            upload_folder="tickets/",
            multiple=True,
        ),
    ]

Database FileInfo objects की एक JSON list store करता है, और admin प्रत्येक file को validation तथा storage के माध्यम से स्वतंत्र रूप से process करता है।

Validation

Validation इस क्रम में चलती है:

1. accept
2. max_size
3. custom validators

Custom validator एक callable है जो request, field, एक UploadFile, और पूरे submitted form values पाता है। उसे None return करना चाहिए या ValueError raise करना चाहिए।

निम्नलिखित उदाहरण filetype library से वास्तविक file contents validate करता है:

import filetype
from starlette.datastructures import UploadFile
from starlette.requests import Request
from starlette_admin.fields import BaseField

ALLOWED_DOCUMENT_MIME_TYPES = {
    "application/pdf",
    "application/msword",
    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
}


def validate_document_type(
    request: Request, field: BaseField, upload: UploadFile, form_values: dict
) -> None:
    upload.file.seek(0)
    try:
        header = upload.file.read(2048)
        kind = filetype.guess(header)
        detected = kind.mime if kind else "application/octet-stream"
    finally:
        upload.file.seek(0)

    if detected not in ALLOWED_DOCUMENT_MIME_TYPES:
        raise ValueError(
            f"Invalid file type '{detected}'. Only PDF, DOC, and DOCX are allowed."
        )

File cleanup की सीमाएँ

starlette-admin files को storage backend में upload करता है और database में FileInfo metadata लिखता है, पर failure या deletion के बाद files clean up नहीं करता। इसके दो व्यवहार निकलते हैं:

• Failed transactions: यदि upload पूरा होने के बाद database transaction rollback हो जाती है, file storage backend में रह जाती है। Storage writes का कोई rollback mechanism नहीं होता।
• Deletions और updates: Row delete करने या file replace करने से database से FileInfo reference हट जाता है, पर पुरानी file LocalStorage या S3Storage में बनी रहती है।

यह design storage layer को सरल रखता है और application-level errors को destructive operations trigger करने से रोकता है। Tradeoff यह है कि orphaned files जमा होती जाती हैं। Storage को असीमित बढ़ने से रोकने के लिए उन्हें स्वयं reconcile करें। एक common pattern है periodic background job जो storage backend की keys को database की active FileInfo references से diff करता है।

Transactional alternative

यदि आपके application को file storage operations को database writes के साथ transactional चाहिए, तो ऐसी library का उपयोग करें जो file storage को SQLAlchemy unit of work से जोड़े।

Field के storage= parameter के बजाय sqlalchemy-file उपयोग करें। वह files को ORM flush और rollback cycle के हिस्से के रूप में store करता है, इसलिए failed transaction या row deletion matching file write को undo कर देता है। Working example के लिए examples/13-sqlachemy-file देखें।

आगे क्या

• फ़ील्ड्स: FileField और ImageField संदर्भ.
• Export & Import: Export bundles में files कैसे शामिल होती हैं।
• Security: Automatic sanitization और validation behavior.