Volume

Source: src/Railway/Volume.ts

A Railway.Volume is block disk in a Project. Create it disconnected (no service) and attach later with MountVolume, or pass service to attach at create time.

Railway has no labels. Ownership is stamped into the volume name via createPhysicalName. mountPath updates in place. Changing project, environment, or region replaces the Volume.

Create a Volume

Pass a Project and a mount path. Alchemy generates a unique name. The volume is disconnected until you attach a Service.

const site = yield* Railway.Project("Site");
const data = yield* Railway.Volume("Data", {
  project: site,
  mountPath: "/data",
});

Changing project replaces the Volume

The Volume is created in the new Project. The old Volume is deleted.

Mount path

mountPath is the path in the container. Updating it is in place.

const data = yield* Railway.Volume("Data", {
  project: site,
  mountPath: "/app/data",
});

Environment

Defaults to the Project’s primary environment. Pass a Railway.Environment (or { environmentId }) to target another one.

const staging = yield* Railway.Environment("Staging", { project: site });
const data = yield* Railway.Volume("StagingData", {
  project: site,
  environment: staging,
  mountPath: "/data",
});

Changing environment replaces the Volume

The Volume is created in the new environment. The old Volume is deleted.

Region

Omit region to use Railway’s default. Changing it replaces the Volume.

const data = yield* Railway.Volume("Data", {
  project: site,
  mountPath: "/data",
  region: "us-west2",
});

Changing region replaces the Volume

Volumes cannot move region. A new Volume is created, then the old one is deleted.

Size

sizeMB on attributes is the observed plan default. Railway’s public VolumeCreateInput has no size field; growing is Pro-dashboard-only. Passing sizeMB on props is IaC-parity documentation — it is not applied.

const data = yield* Railway.Volume("Data", {
  project: site,
  mountPath: "/data",
});
// data.sizeMB is the plan default (e.g. 5120 on Hobby)

Attach to a Service

Pass service to attach at create time. Omit it and attach later with MountVolume. One volume per service.

const api = yield* Railway.Service("Api", {
  project: site,
  image: "hashicorp/http-echo",
});
const data = yield* Railway.Volume("Data", {
  project: site,
  mountPath: "/data",
  service: api,
});

One volume per service

A second volume on the same Service fails with Railway.MultipleVolumes. Railway does not give each replica its own disk.

Backups

Snapshot a mounted volume with VolumeBackup. Railway only backups attached volumes. Restore is destructive — see restoreVolumeBackup.

const snap = yield* Railway.VolumeBackup("Nightly", { volume: data });

Module-scope declarations

Declare the Project once. Pass it into every child. Resource-valued props accept the resource or an Effect producing it.

src/data.ts

import * as Railway from "alchemy/Railway";

export const Site = Railway.Project("Site");
export const Data = Railway.Volume("Data", {
  project: Site,
  mountPath: "/data",
});