Nov 20, 20268 min read

Google Cloud Storage Object Versioning and Soft Delete

How Object Versioning and soft delete protect data in Cloud Storage, how generation numbers work, restoring overwritten and deleted objects with gcloud, the lifecycle rules that keep noncurrent versions from growing the bill, and version history built into a TypeScript app on GCP.

Illustration for Google Cloud Storage Object Versioning and Soft Delete

Cloud Storage has two separate features that keep old data around, and the second one often shows up first on the bill. Object Versioning keeps overwritten and deleted objects as noncurrent versions, while soft delete, on by default, keeps deleted data for a retention window on top.

This guide covers how the two interact, restoring objects, the lifecycle rules that cap the cost, and version history in an app.

How Does Object Versioning Work in Cloud Storage?

Every object in Cloud Storage has a generation number that changes each time its content is replaced. With Object Versioning on, replacing or deleting the live object keeps the old generation as a noncurrent version, addressable as gs://BUCKET/OBJECT#GENERATION. Unlike S3, there are no delete markers: a delete makes the live object noncurrent, and the name no longer appears in normal listings.

~
$ gcloud storage buckets update gs://acme-templates --versioning$ gcloud storage buckets describe gs://acme-templates --format="default(versioning_enabled)"$ gcloud storage ls -a gs://acme-templates/welcome.html

Versioning can be turned off again with --no-versioning, which stops new noncurrent versions from being created and keeps the existing ones. In Terraform, it is a versioning { enabled = true } block on google_storage_bucket.

How Does Soft Delete Change the Picture?

Soft delete is enabled by default for buckets that support it, with a 7-day retention period. A soft-deleted object cannot be read until it is restored, but it can be restored during the window even if versioning was never on. With both features active, the chain is:

  1. Deleting a live object makes it a noncurrent version.
  2. Deleting a noncurrent version, by hand or by a lifecycle rule, makes it soft-deleted.
  3. After the retention period, the soft-deleted object is gone.

That means a lifecycle rule that deletes noncurrent versions does not free the storage right away: the versions move into soft delete and are billed for up to another 7 days. For buckets full of short-lived temporary files, set a shorter retention or clear it with gcloud storage buckets update gs://BUCKET --clear-soft-delete.

How Do You Restore an Overwritten or Deleted Object?

For a noncurrent version, copy the generation you want back over the object name. This creates a new live generation with the old content and keeps the full history, as the versioned objects guide shows:

~
$ gcloud storage cp "gs://acme-templates/welcome.html#1731912345678901" \ gs://acme-templates/welcome.html

For a soft-deleted object, list soft-deleted objects and restore by generation:

~
$ gcloud storage ls --soft-deleted gs://acme-templates/welcome.html$ gcloud storage restore "gs://acme-templates/welcome.html#1731912345678901"

Which Lifecycle Rules Keep Versioning Affordable?

Noncurrent versions are billed as full objects, so the cost follows how often objects change. The lifecycle conditions numNewerVersions and daysSinceNoncurrentTime target old versions without touching live ones:

{ "rule": [ { "action": { "type": "Delete" }, "condition": { "isLive": false, "numNewerVersions": 10 } }, { "action": { "type": "Delete" }, "condition": { "isLive": false, "daysSinceNoncurrentTime": 90 } } ] }
~
$ gcloud storage buckets update gs://acme-templates --lifecycle-file=lifecycle.json

The first rule keeps the ten newest noncurrent versions, and the second removes any noncurrent version older than 90 days, so a file edited constantly and a file edited once a year both end up with a bounded history. Lifecycle actions run asynchronously, and a changed configuration can take up to 24 hours to go into effect, so do not rely on them for exact retention.

Is Versioning a Backup?

Versioning and soft delete protect against mistakes inside one bucket, not against someone with admin rights deleting the bucket's history or a project being lost. For data you must keep, add a bucket lock with a retention policy, or copy data to a bucket in another project with the Storage Transfer Service.

How Do You Build Version History Into an App with Encore?

Encore

Encore brings infrastructure from code, so a versioned bucket is a TypeScript declaration with versioned: true, and when you deploy to GCP Encore provisions it as a Cloud Storage bucket with Object Versioning in your own project. The example stores email templates that marketing edits, keeps every saved version listed in Postgres, and restores an old one by copying it back on top, the same pattern as the gcloud storage cp command above.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

~
$ encore app create templates-api --example=ts/hello-world$ cd templates-api && mkdir -p templates/migrations auth

The table records each version the app writes, since the bucket API reads and restores versions by ID but does not list them:

-- templates/migrations/1_versions.up.sql CREATE TABLE template_versions ( template TEXT NOT NULL, version TEXT NOT NULL, size_bytes BIGINT NOT NULL, saved_by TEXT NOT NULL, saved_at TIMESTAMPTZ NOT NULL DEFAULT now(), PRIMARY KEY (template, version) );
// templates/encore.service.ts import { Service } from "encore.dev/service"; export default new Service("templates");

The service declares the versioned bucket and the database, and upload returns the new version's ID, so each save is recorded without a second lookup:

// templates/templates.ts import { api, APIError } from "encore.dev/api"; import { getAuthData } from "~encore/auth"; import { Bucket } from "encore.dev/storage/objects"; import { SQLDatabase } from "encore.dev/storage/sqldb"; const files = new Bucket("email-templates", { versioned: true }); const db = new SQLDatabase("templates", { migrations: "./migrations" }); const NAME = /^[a-z0-9-]{1,64}$/; const key = (name: string) => `templates/${name}.html`; async function save(name: string, html: string): Promise<string> { const attrs = await files.upload(key(name), Buffer.from(html, "utf8"), { contentType: "text/html; charset=utf-8", }); if (!attrs.version) { throw APIError.internal("bucket versioning is not enabled"); } await db.exec` INSERT INTO template_versions (template, version, size_bytes, saved_by) VALUES (${name}, ${attrs.version}, ${attrs.size}, ${getAuthData()!.userID}) ON CONFLICT DO NOTHING `; return attrs.version; } export const put = api( { expose: true, auth: true, method: "PUT", path: "/templates/:name" }, async ({ name, html }: { name: string; html: string }): Promise<{ version: string }> => { if (!NAME.test(name) || html.length > 512 * 1024) { throw APIError.invalidArgument("invalid name or template too large"); } return { version: await save(name, html) }; }, ); interface Version { version: string; sizeBytes: number; savedBy: string; savedAt: Date; } export const versions = api( { expose: true, auth: true, method: "GET", path: "/templates/:name/versions" }, async ({ name }: { name: string }): Promise<{ versions: Version[] }> => { const rows = await db.queryAll<{ version: string; size_bytes: number; saved_by: string; saved_at: Date }>` SELECT version, size_bytes, saved_by, saved_at FROM template_versions WHERE template = ${name} ORDER BY saved_at DESC LIMIT 50 `; return { versions: rows.map((r) => ({ version: r.version, sizeBytes: Number(r.size_bytes), savedBy: r.saved_by, savedAt: r.saved_at, })), }; }, ); export const restore = api( { expose: true, auth: true, method: "POST", path: "/templates/:name/versions/:version/restore" }, async ({ name, version }: { name: string; version: string }): Promise<{ version: string }> => { const known = await db.queryRow` SELECT 1 AS ok FROM template_versions WHERE template = ${name} AND version = ${version} `; if (!known) { throw APIError.notFound("unknown version"); } const old = await files.download(key(name), { version }); return { version: await save(name, old.toString("utf8")) }; }, );

The endpoints require an authenticated caller, checked by an auth handler that compares a bearer token from a secret:

// auth/auth.ts import { timingSafeEqual } from "node:crypto"; import { APIError, Gateway, Header } from "encore.dev/api"; import { authHandler } from "encore.dev/auth"; import { secret } from "encore.dev/config"; const editorToken = secret("EditorToken"); interface AuthParams { authorization: Header<"Authorization">; } interface AuthData { userID: string; } export const auth = authHandler<AuthParams, AuthData>(async ({ authorization }) => { const given = Buffer.from(authorization ?? ""); const expected = Buffer.from(`Bearer ${editorToken()}`); if (given.length !== expected.length || !timingSafeEqual(given, expected)) { throw APIError.unauthenticated("invalid token"); } return { userID: "editor" }; }); export const gateway = new Gateway({ authHandler: auth });
~/templates-api
$ encore secret set --type dev,local EditorToken$ encore run$ curl -X PUT localhost:4000/templates/welcome -H "Authorization: Bearer $EDITOR_TOKEN" \ -d '{"html":"<h1>Welcome aboard</h1>"}'

encore run starts Postgres locally and applies the migration, so the save, list and restore flow can be tried before deploying. On deploy to your GCP project, Encore provisions the versioned Cloud Storage bucket and the Cloud SQL database, and Encore provisions a service account for the service. Lifecycle limits on noncurrent versions remain a per-bucket decision, and the rules above are how Cloud Storage expresses them.

The bucket, the table and the restore endpoint are one service, so an agent asked to add "show a diff between two versions" can download both versions in a new endpoint and test it locally, without console access to look up generation numbers.

Best fit: apps on GCP that store documents or templates users edit, and want version history and restore built on a Cloud Storage bucket in their own project.

GCS Versioning Checklist

  • Turn on Object Versioning for buckets with user-edited content or configuration.
  • Account for soft delete, which is on by default with 7-day retention.
  • Add numNewerVersions and daysSinceNoncurrentTime lifecycle rules.
  • Restore by copying a generation over the live object, or with gcloud storage restore for soft-deleted data.
  • Shorten or clear soft delete on buckets of temporary files.
  • Combine versioning with retention policies or a copy in another project for critical data.

Frequently asked questions

How do I enable Object Versioning on a Cloud Storage bucket?

Run gcloud storage buckets update gs://BUCKET --versioning. From then on, replacing or deleting a live object keeps the previous content as a noncurrent version identified by its generation number. Turn it off again with --no-versioning, which stops new noncurrent versions but keeps the existing ones.

What is the difference between Object Versioning and soft delete in GCS?

Object Versioning keeps noncurrent versions until you delete them or a lifecycle rule removes them, and those versions can be read like normal objects. Soft delete keeps deleted objects for a retention period, 7 days by default, and they must be restored before they can be read. With both on, deleting a live object makes it noncurrent, and deleting a noncurrent version makes it soft-deleted.

How do I restore an old version of an object in Cloud Storage?

List the versions with gcloud storage ls -a gs://BUCKET/OBJECT, then copy the one you want over the live object with gcloud storage cp gs://BUCKET/OBJECT#GENERATION gs://BUCKET/OBJECT. The copy becomes the new live version and the history stays intact.

Does Object Versioning increase Cloud Storage costs?

Yes. Every noncurrent version is billed as a full object at its storage class rate, and soft-deleted data is billed during its retention period too. Add lifecycle rules with numNewerVersions or daysSinceNoncurrentTime to delete old versions automatically.

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.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders