Skip to content

Configuring file storage backends

Help us refine file storage!

Our file storage feature is new and still evolving. We’d love to hear about how you’re using it, what’s working, and what additional workflows you’d like to see supported.

Talk to us for 20 min! We’ll give you a $25 gift card as a thank you.

Mathesar’s file data type requires you to configure an S3-compatible object storage backend. File storage allows users to upload, preview, and download files directly within Mathesar.

Configuring file storage and using file columns is optional. By default, Mathesar does not expose file column controls unless a storage backend is set up. If you do not set up a backend, users will not be able to work directly with files in Mathesar.

1. Configure your storage backend

First, you’ll need to decide which S3-compatible object storage backend you’ll use.

Popular options include:

MinIO license considerations

MinIO is licensed under the GNU Affero General Public License v3 (AGPLv3). This license requires that if you modify MinIO and make it available over a network, you must also make your modified source code available to users.

Be sure you understand these obligations before choosing MinIO as your storage backend. See MinIO’s documentation on license compliance for details.

After choosing a backend, you’ll need to follow the basic steps for working with S3-comptiable object storage:

  1. Create a bucket
    • Decide on a unique bucket name.
    • Choose which region your bucket is in (if your platform supports regions).
    • (Optional but recommended) enable versioning or lifecycle policies depending on your retention needs.
  2. Create an API key and secret key
    • Generate credentials with read/write permissions scoped to your bucket.
  3. Note the endpoint URL
    • For example, AWS uses https://s3.[region].amazonaws.com by default.
    • Other providers (Cloudflare R2, DigitalOcean Spaces, MinIO) each provide a specific endpoint.

2. Enable file storage in Mathesar

Enabling file storage requires setting up a new configuration file or environment variable that contains your backend’s connection details.

You’ll either create a file named file_storage.yml or set up the FILE_STORAGE_DICT environment variable. Which you choose depends on how you installed Mathesar:

If you used Docker Compose, create the file_storage.yml file next to your docker-compose.yml file:

mathesar
 ├── docker-compose.yml
 ├── msar/
+└── file_storage.yml

Then, uncomment the following lines in your docker compose file:

volumes:
 - ./msar/static:/code/static
 - ./msar/media:/code/media
# Uncomment the following to mount file_storage.yml and enable
#  an S3-compliant file storage backend
-# - ./file_storage.yml:/code/file_storage.yml
+  - ./file_storage.yml:/code/file_storage.yml

For direct installations, create file_storage.yml in the installation directory you defined while installing Mathesar.

If you deployed to an environment where you can’t use the local filesystem (e.g. DigitalOcean, Railway), you can use the FILE_STORAGE_DICT environment variable instead of a file_storage.yml file.

This variable must contain a JSON representation of the same data that file_storage.yml contains, wrapped in quotes and with quotes escaped. Here’s an example:

FILE_STORAGE_DICT="{\"default\": {\"protocol\": \"s3\", \"nickname\": \"Local object store\", \"prefix\": \"mathesar-storages\", \"kwargs\": {\"client_kwargs\": {\"endpoint_url\": \"http://mathesar-dev-store:9000\", \"region_name\": \"us-east-2\", \"aws_access_key_id\": \"mathesar\", \"aws_secret_access_key\": \"mathesar\"}}}}"

See Environment Variables for links to tools that simplify this process.

3. Configure backend connection details

Here’s where you populate your configuration file.

3a. Retrieve needed information

From your chosen storage backend, collect the following details:

  • Bucket name: corresponds to the prefix field in Mathesar’s config.
  • Endpoint URL: the base URL for your provider’s S3 API.
  • Region name: required by some providers (e.g. AWS). If your provider doesn’t use regions (e.g. Cloudflare R2), set this to "auto".
  • Access key ID: generated credential for programmatic access.
  • Secret access key: generated credential paired with the access key ID.

3b. Basic setup

Once you have those details, update file_storage.yml with your values:

# This config file allows you to configure an S3-compatible
# object storage backend for file columns in Mathesar.
default:
+  protocol: s3
+  nickname: "Backend name"   # A friendly label for this backend
+  prefix: my-mathesar-bucket # This should match your bucket name exactly
+  kwargs:
+    client_kwargs:
+      endpoint_url: https://s3.us-east-2.amazonaws.com
+      region_name: us-east-2
+      aws_access_key_id: YOUR_ACCESS_KEY
+      aws_secret_access_key: YOUR_SECRET_KEY

4. Activate file storage

Once you’ve finished configuring storage, restart Mathesar so it can load the updated file_storage.yml file or environment variable.

docker compose -f docker-compose.yml down
docker compose -f docker-compose.yml up -d

sudo systemctl restart mathesar.service

Use their web interface to restart (often framed as a “redeploy”) Mathesar.

After restarting, file columns will be enabled in your Mathesar installation. To test this, check the UI for adding a new file column.

Tips & technical information

How files are stored

Files are stored in your PostgreSQL database in JSONB columns. A typical file value looks like this:

{
  "uri": "s3://my-mathesar-bucket/my-username/20250919-192215167015/example.csv",
  "mash": "58f47a1eafd567cd9d0bdfa1f42a01978cc6f36eb7937b310b208d9957b7ee8b"
}

With the uri being the path to the file on the storage backend and the mash being a generated, unique value used by Mathesar.

Removing file backends

If you remove a file backend, you’ll no longer see the “File” option in the “add column” dropdown. Existing file data will be preserved in your database, but in Mathesar’s UI you’ll see the underlying JSONB instead of image thumbnails or file icons.