27 File Operations

Once storage is configured, the following file and directory operations are supported.

• Upload: Store files using REST endpoints.

• Download: Retrieve files with optional metadata-only flag.

• Delete: Remove files from storage.

• Move: Rename or relocate files within storage.

• List: Enumerate files in a folder path.

• Uploading a File
  
• Downloading a File
  
• File Management Operations
  
• Storage CLI Commands
  

27.1 Uploading a File

This section describes how to upload files to Oracle Oracle Backend for Firebase Object Storage, covering both DBFS and OCI Object Storage backends. Using the platform-specific SDKs, developers can:

• Upload a file using object reference given that the security rule is valid for the operation
• Manage uploads using the pause, resume, and cancel features.
• Upload large files, which internally creates multiple chunk and uploads serially, making sure that final file md5 hash is correct.

• Prerequisites
  
• Uploading Files Flow
  
• Managing and Monitoring Uploads
  
• Security Considerations
  

27.1.1 Prerequisites

Before uploading files, ensure the following setup is complete:

• Object Storage is enabled for your project via the OBaaS Console.

• You have selected either DBFS (Database File System) or OCI Object Storage as the storage backend.

• Your application configuration includes:

  • ORDS Host IP

  • schema

  • app_name, app_type, app_id, project_id

  • Authentication setup (email/password, social login, or SAML/OIDC)

  • Storage configuration block

27.1.2 Uploading Files Flow

File uploads are performed using the Oracle Backend for Firebase SDK or REST API. The operation uses the addDoc() method to create a new document representing the file.

Document Structure

Each uploaded file is represented as a document with fields such as:

{
  "uuid": "<user_id>",
  "url": "<file_url>",
  "storageRef": "<internal_reference>",
  "createdAt": "<timestamp>"
}

The file content is stored in the backend (DBFS or OCI OBJS), and the document includes a reference to the storage location (using the storageRef field).

Uploading Large Objects

When uploading large files:

• Use DBFS for optimal performance and multipart support.

• OCI Object Storage requires the entire file to be uploaded in a single request.

  Consider increasing timeout settings in your application when uploading via OCI.

Console-Based Uploads

Developers can upload files directly using the Oracle Backend for Firebase Console.

The Console UI allows:

• Navigate to your project’s Object Storage section.

• Selecting a bucket and folder

• Drag-and-drop file upload

• Viewing upload progress and status

Uploaded files are automatically linked to the backend and can be referenced in documents.

See Also:

Storage Console Tasks for detailed steps on how to perform upload related tasks

Error Handling

If the upload fails, the service returns a structured error response:

{
  "error": "<error_message>"
}

Common causes for errors include invalid bucket or path, insufficient access rights, or expired or malformed token.

27.1.3 Managing and Monitoring Uploads

Monitoring upload progress involves tracking the state of a file upload while it is in progress, updating the user interface (UI) to reflect the current upload status, and handling potential errors or completion of the upload. This is useful in scenarios where users upload large files, such as images or videos, and you want to display a progress bar or percentage to inform them about the upload status. Upload operations supports managing the upload task using pause, resume, and cancel methods.

27.1.4 Security Considerations

Uploaded files are subject to Object Storage security rules. These rules determine:

• Who can upload files

• Which paths are writable

• Whether the user is authenticated

Security rules are written in CEL and can use variables like request.auth, request.resource, and path.

The followg example rule restricts uploads to the owner:

match /users/{userid}/photos/{photoid} {
  allow create: if request.auth != null &&
                 request.auth.uid == request.resource.data.uuid;
}

27.2 Downloading a File

This chapter explains how developers can retrieve files stored in Oracle Backend for Firebase Object Storage. It covers both DBFS and OCI Object Storage backends, outlines supported download mechanisms, and highlights Console-based capabilities.

• Prerequisites
  
• Downloading Files Flow
  
• Security Considerations
  

27.2.1 Prerequisites

Before downloading files, ensure that:

• Object Storage is enabled and configured for your project.

• The file to be downloaded exists and is referenced through a valid storageRef or url field in a document.

• The user is authenticated and authorized to access the file, based on security rules.

27.2.2 Downloading Files Flow

Download of storage files can be done using the file reference of the particular object. First step is to create a reference and pass the same to the download method.

Files are downloaded by referencing their storage location, typically stored in a document field such as:

{
  "url": "https://storage.oracle.com/obj123.jpg",
  "storageRef": "obj123"
}

The actual download is performed by issuing a GET request to the file’s URL or using the SDK’s get() method to retrieve the document and extract the file reference.

Public Download URL Generation

Oracle Backend for Firebase supports generating public URLs for files stored in Object Storage.

• Public URLs allow unauthenticated access to files.

• These URLs are typically generated through the Console or SDK.

• Security rules must explicitly allow public read access.

The following example shows the security rule for public access:

match /users/{userid}/photos/{photoid} {
  allow get: if resource.data.isPublic == true;
}

Note:

Public access must be carefully controlled to avoid exposing sensitive data.

Console-Based Downloads

Developers can download files directly using the Oracle Backend for Firebase Console:

• Navigate to the Object Storage section.

• Locate the file using folder/bucket navigation.

• Click the download icon or link next to the file.

• For public files, copy the public URL.

• For secure files, use the signed URL generator (if enabled).

See Also:

Storage Console Tasks for detailed steps on how to perform download related tasks

Error Handling

If a download fails, the service returns a structured error response:

{
  "error": "<error_message>"
}

Common causes for errors include file not found, invalid or expired signed URL, insufficient access rights, missing or incorrect storageRef.

27.2.3 Security Considerations

Access to files stored in Oracle Backend for Firebase Object Storage is governed by CEL-based security rules. These rules determine whether a user can retrieve (GET) or list files from a collection or path. Developers must ensure that appropriate rules are defined to protect sensitive content and enable valid access.

Rule Structure

Security rules for downloading files typically use the get and list methods:

match /users/{userid}/photos/{photoid} {
  allow get: if <condition>;
  allow list: if <condition>;
}

Rules can evaluate:

• request.auth: Authentication context of the user

• resource.data: Stored metadata of the file/document

• request.resource: Incoming request data

• path: Document or collection path

• method: Operation type (get, list)

Common Download Scenarios

1. Public Access

Allow any user to download a file if it is marked as public:

match /posts/{postId} {
  allow get: if resource.data.isPublic == true;
}

2. Owner-Only Access

Allow only the owner of the file to download it:

match /users/{userid}/photos/{photoid} {
  allow get: if request.auth != null &&
              request.auth.uid == resource.data.uuid;
}

3. Conditional Listing

Allow listing of files only if they are public and the user is authenticated:

match /posts/{postId} {
  allow list: if request.auth != null &&
               resource.data.isPublic == true;
}

Wild Card Rules

Use wildcards to apply rules across multiple documents:

match /tasks/{taskId} {
  allow get: if request.auth != null &&
              taskId.matches('^task_' + request.auth.uid + '_.*$');
}

Advanced Rule Logic

Use CEL functions for complex conditions:

• exists(path): Check if a related document exists

• get(path).data.field: Retrieve and evaluate a field from another document

For example:

match /projects/{projectId} {
  allow get: if get(/projects/$(projectId)).data.status == "active";
}

Common Pitfalls

• Missing get rule: Even if list is allowed, individual file access may fail.

• Incorrect uid match: Ensure request.auth.uid matches resource.data.uuid.

• Overly permissive rules: Avoid allowing get without conditions unless intentional.

27.3 File Management Operations

This section outlines the operations available for managing files stored in Oracle Backend for Firebase Object Storage. It includes listing files, reading metadata, deleting files, and folder creation (if supported). These operations apply to both DBFS and OCI Object Storage backends.

• Listing Files
  
• Reading File Metadata
  
• Deleting a File
  
• Directory Operations
  
• Console-Based File Management
  

27.3.1 Listing Files

Developers can list files within a specific folder or path using the list method. This operation retrieves all documents representing files under a given collection or subcollection.

The following is an example of a collection path:

users/{userId}/photos
users/{userId}/recipes/{recipeId}/photos

• To list files in Storage along with pagination options, Oracle Backend for Firebase provides the list() and listAll() methods. These methods allow you to fetch file metadata and optionally paginate the results, especially useful when there are large numbers of files in your storage

• The maxResults parameter specifies the maximum number of items (files) to return in a single call to the list() method

• The pageToken parameter is used to fetch the next set of results when you paginate through the list of files. When you make a list() call with maxResults, Oracle Backend for Firebase returns a token (nextPageToken) that you can use in the next request to retrieve the next batch of results

27.3.2 Reading File Metadata

Object Storage supports the use of the following metadata at the application level.

• name
• bucket
• size
• timeCreated
• updated
• md5Hash
• contentType

27.3.3 Deleting a File

Using reference of a file, delete operation can be called. The actual file in Object Storage is deleted based on the storageRef.

db.collection("users")
  .doc("Scott")
  .collection("recipes")
  .doc("Cookies")
  .collection("photos")
  .doc("photo1")
  .delete()

Note:

Subcollections are not automatically deleted. Manual cleanup may be required.

27.3.4 Directory Operations

Folder creation is backend-dependent. For DBFS, you can have folder-like structures using path conventions. For OCI Object Storage, flat namespace is used wherein folders are simulated using prefixes.

To create a folder:

• Add a document with a path field representing the folder.

• Upload files using the folder path as a prefix.

Example 27-1 Path Convention

bucket/photos/2025/
bucket/recipes/Cookies/photos/

Oracle Backend for Firebase does not expose a dedicated "create folder" API. Folder structures are inferred from document paths and storage references.

27.3.5 Console-Based File Management

The Oracle Backend for Firebase Console supports:

• Listing files by bucket and folder

• Viewing file metadata

• Deleting files using UI

• Simulating folders using path prefixes

See Also:

Storage Console Tasks for detailed steps on how to perform file management tasks

27.4 Storage CLI Commands

Prerequisite

Ensure that the setup of CLI for Oracle Backend for Firebase is complete.

See Also:

Configure the CLI for detailed steps on how to set up the CLI for Oracle Backend for Firebase

• List Files:

  fusabase storage list <directory path> --token=<token> --rows=<rows>

• Retrieve a File:

  fusabase storage get <filepath>

• Delete a File:

  fusabase storage del <filepath>

• Move a File:

  fusabase storage move <filepath> --newpath=<newpath>

• Download a File:

  fusabase storage download <filepath>

• Upload a File:

  Uploads a new file to the storage (less then 16mb). For example:

  fusabase storage upload mydirectory/photo.jpg