---
title: "Object storage"
description: "Store backups and recovery history in your S3-compatible object storage."
section: "Guides"
source_url: "https://sqlstyle.com/docs/object-storage"
---
SQLStyle writes full snapshots and incremental recovery history to your
S3-compatible bucket. Your application data stays in infrastructure you control.

See [backup and recovery history](/docs/backup-and-recovery-history) for the
capture, catalog, upload, and controller-fencing path behind these objects.

## Create a storage profile

The hosted CLI stores the complete non-secret provider configuration. The
authenticated SQLStyle account and selected project are attached automatically;
the profile also stores the provider, bucket, region, endpoint, access-key ID,
retention policy, and provider-derived checksum mode.

```sh
sqlstyle storage profiles create \
  --name production \
  --provider aws_s3 \
  --bucket app-dbh \
  --region us-east-1 \
  --access-key-id "$AWS_ACCESS_KEY_ID" \
  --retention 15m/1h/4h/24h
```

The built-in provider keys are `aws_s3`, `cloudflare_r2`, `tigris`, and
`backblaze_b2`. An account administrator can configure additional provider keys
for other S3-compatible services.

Some providers identify the provider account through the endpoint. For example,
a Cloudflare R2 profile stores the Cloudflare account ID as part of its endpoint:

```sh
sqlstyle storage profiles create \
  --name production-r2 \
  --provider cloudflare_r2 \
  --bucket app-dbh \
  --endpoint "https://${CLOUDFLARE_ACCOUNT_ID}.r2.cloudflarestorage.com" \
  --access-key-id "$R2_ACCESS_KEY_ID" \
  --retention 15m/1h/4h/24h
```

The CLI's optional `--account-id` selector refers to the SQLStyle product
account. It is not an AWS, Cloudflare, Tigris, or Backblaze account identifier.
Normally the authenticated CLI account supplies it automatically.

## Keep the secret local

The secret access key always remains a runtime or toolbox input:

```sh
export SQLSTYLE_STORAGE_SECRET_ACCESS_KEY='...'
```

The secret is not uploaded to SQLStyle servers. Treat it as an application
deployment secret and scope it to the required bucket and operations.

Hosted releases contain the SQLStyle backend address; it is not application
configuration. The database-scoped API key and database name select the hosted
profile, which supplies defaults for the storage configuration:

```js
import { DatabaseSync } from "@sqlstyle/database";

const db = new DatabaseSync("app.db", {
  sqlstyle: {
    name: "app/main",
    apiKey: process.env.SQLSTYLE_API_KEY,
    storage: {
      secretAccessKey: process.env.SQLSTYLE_STORAGE_SECRET_ACCESS_KEY,
    },
  },
});
```

Provider, account namespace, database ID, bucket, access-key ID, region,
endpoint, retention, and checksum mode are fetched from the profile. Any field
set in `storage` overrides the corresponding profile value. The secret
has no profile value and must always be supplied locally.

## Retention syntax

Retention is an optional slash-separated sequence of increasing intervals:

```text
15m/1h/4h/24h
```

Supported units are seconds (`s`), minutes (`m`), hours (`h`), and days (`d`). The final interval is the cutoff.

Retention is recovery-plan aware. It does not delete objects merely because they are old:

- objects beyond the recovery state accepted by SQLStyle are not selected for a normal restore;
- deletion waits for a surviving verified recovery plan;
- connected replica watermarks can prevent removal of required local history;
- manual deletion is a preview unless explicitly executed.

## S3 behavior

The storage implementation:

- retries PUT and multipart operations;
- uses multipart upload for large objects;
- validates size and checksum during reads;
- paginates object listings;
- uses conditional deletion when safely removing a selected object.

## Validate recovery

Do not treat upload success alone as a restore test. Use the restore CLI:

```sh
sqlstyle database app/main recovery status
sqlstyle database app/main recovery verify --mode plan
sqlstyle database app/main recovery verify --mode checksum
```

See [restore and recovery](/docs/restore-and-recovery) for restore targets and verification modes.