What S3 versioning does on upload and delete, delete markers, why a versioned bucket keeps growing, lifecycle rules for noncurrent versions, restoring an old version, and when versioning is worth turning on.

S3 versioning keeps every write to a key as a separate version, so an overwrite or delete no longer destroys the previous data. It is cheap protection against a bad deploy or a script that deletes the wrong prefix, and it is also how a bucket quietly doubles in size when nobody adds a lifecycle rule.
This guide covers delete markers, restores and how to keep the cost bounded.
A bucket is in one of three states: unversioned, enabled or suspended. The S3 versioning docs note that a bucket can never return to unversioned once versioning is on; suspending it only stops new versions from being created.
With versioning enabled, each PUT to a key creates a new version with its own version ID, and the newest one is the current version that a plain GET returns. Older versions become noncurrent and stay billable at full storage price.
aws s3api put-bucket-versioning --bucket app-contracts \
--versioning-configuration Status=Enabled
aws s3api list-object-versions --bucket app-contracts --prefix contracts/c_123.pdf \
--query '{Versions: Versions[].[VersionId,IsLatest,LastModified,Size], Markers: DeleteMarkers[].[VersionId,IsLatest]}'
Deleting a key without a version ID does not delete anything. S3 adds a delete marker as the current version, so GET returns 404 and listings hide the key, while every earlier version is still there. Deleting with an explicit --version-id is the only way to remove a version permanently.
This makes restores straightforward:
# Restore an overwritten object by copying an older version over it
aws s3api copy-object --bucket app-contracts --key contracts/c_123.pdf \
--copy-source "app-contracts/contracts/c_123.pdf?versionId=3HL4kqtJlcpXroDTDmJ.rmSpXd3dIbrHY"
Every overwrite of a 10 MB file adds another 10 MB of noncurrent data, so a bucket of frequently updated files grows with every write rather than with the number of keys. A lifecycle rule bounds it by expiring noncurrent versions after a number of days while keeping a fixed number of the newest ones, as described in the lifecycle configuration docs:
{
"Rules": [
{
"ID": "expire-old-versions",
"Status": "Enabled",
"Filter": {},
"NoncurrentVersionExpiration": { "NoncurrentDays": 30, "NewerNoncurrentVersions": 3 },
"Expiration": { "ExpiredObjectDeleteMarker": true },
"AbortIncompleteMultipartUpload": { "DaysAfterInitiation": 7 }
}
]
}
Apply it with aws s3api put-bucket-lifecycle-configuration --bucket app-contracts --lifecycle-configuration file://lifecycle.json, and ExpiredObjectDeleteMarker removes delete markers whose versions have all expired, which otherwise slow down listings. For noncurrent data that must be kept longer, a NoncurrentVersionTransitions entry can move it to a cheaper storage class first.
Versioning pays off for buckets holding data that cannot be regenerated: user uploads, signed documents, exports that customers download later. It is also a prerequisite for S3 replication and Object Lock. For build artifacts, caches or thumbnails that can be recreated from a source, it mostly adds cost. MFA delete adds another layer by requiring the root account's MFA device to delete a version or change the versioning state, which protects against stolen credentials but makes automation harder.
Best fit: versioning plus a noncurrent-version lifecycle rule on buckets of user data, and no versioning on buckets of derived files.
Encore brings infrastructure from code to object storage: a bucket is a variable in the service that uses it, versioning is a field in its config, and on deploy Encore creates an S3 bucket in your AWS account or a Cloud Storage bucket on GCP and provisions an IAM role for the service that uses it. The object storage docs cover the full API, including reading a specific version:
Run in your terminal to get started locally.
package contracts
import (
"context"
"io"
"net/http"
"encore.dev"
"encore.dev/beta/errs"
"encore.dev/storage/objects"
"encore.dev/storage/sqldb"
)
var Signed = objects.NewBucket("signed-contracts", objects.BucketConfig{Versioned: true})
var db = sqldb.NewDatabase("contracts", sqldb.DatabaseConfig{Migrations: "./migrations"})
//encore:api auth raw method=PUT path=/contracts/:id/document
func UploadDocument(w http.ResponseWriter, req *http.Request) {
ctx := req.Context()
id := encore.CurrentRequest().PathParams.Get("id")
key := "contracts/" + id + ".pdf"
wr := Signed.Upload(ctx, key, objects.WithUploadAttrs(objects.UploadAttrs{ContentType: "application/pdf"}))
if _, err := io.Copy(wr, req.Body); err != nil {
wr.Abort(err)
errs.HTTPError(w, err)
return
}
if err := wr.Close(); err != nil {
errs.HTTPError(w, err)
return
}
// Record which version this signature produced, so it can be served later
// even after the document is replaced.
attrs, err := Signed.Attrs(ctx, key)
if err != nil {
errs.HTTPError(w, err)
return
}
if _, err := db.Exec(ctx,
`INSERT INTO contract_versions (contract_id, object_version, size_bytes) VALUES ($1, $2, $3)`,
id, attrs.Version, attrs.Size); err != nil {
errs.HTTPError(w, err)
return
}
w.WriteHeader(http.StatusNoContent)
}
// readVersion opens a specific earlier version of a contract document.
func readVersion(ctx context.Context, id, version string) *objects.Reader {
return Signed.Download(ctx, "contracts/"+id+".pdf", objects.WithVersion(version))
}
encore run provides local object storage on the filesystem and starts Postgres for the contract_versions table, so the upload flow can be exercised without an AWS account, and the databases docs cover the migration that creates the table. The bucket itself lives in your AWS account, so the lifecycle rule for noncurrent versions is added there, in the S3 console or with the CLI command above, as the infrastructure configuration docs describe for provisioned resources.
An AI coding agent that needs document history can turn on Versioned: true and store the version ID in the same change, and the reviewer sees the storage decision and the code relying on it together.
Best fit: services storing user documents on AWS or GCP that need old versions readable by ID.
Enable versioning on buckets of user data, add the noncurrent-version lifecycle rule in the same change, and practice one restore so the delete marker behavior is not a surprise during an incident. Record version IDs in your database when an old version has business meaning, such as the exact document a customer signed.
No. Once versioning is enabled it can only be suspended, not removed. A suspended bucket stops creating new versions for new writes, but every version stored before suspension stays in the bucket and keeps costing storage until it is deleted or expired.
A simple DELETE does not remove data. S3 adds a delete marker as the new current version, so GET returns 404, while all previous versions remain and can be restored by deleting the marker or copying an old version back.
Add a lifecycle rule with NoncurrentVersionExpiration, for example NoncurrentDays 30 and NewerNoncurrentVersions 3, plus ExpiredObjectDeleteMarker. Old versions are then deleted after 30 days except the three most recent, and leftover delete markers are cleaned up.
Declare it with objects.NewBucket and set Versioned: true in objects.BucketConfig. Attrs returns the Version of an object, and Download accepts objects.WithVersion to read a specific earlier version.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.