Module: github.com/railwayapp/railway-go-sdk (import name railway).
Author .railway/railway.go using this module, then railway config plan /
railway config apply. One repository (or monorepo) for the whole
environment: one file describing every resource. One repository per service:
one file per repository, each with a named partial (see
Multi-repo projects).
package main
import "github.com/railwayapp/railway-go-sdk"
func Railway() railway.Project {
db := railway.Postgres("db")
web := railway.ServiceNamed("web", railway.ServiceConfig{
"source": railway.Github("org/app"),
"start": "./app",
"env": map[string]any{
"DATABASE_URL": db.Env("DATABASE_URL"),
},
// Per-environment tracing switches; omit the block to leave tracing off.
"tracing": map[string]any{"enabled": true, "autoInstrumentation": true},
})
return railway.ProjectNamed("my-app", []any{db, web})
}Put a go.mod next to .railway/railway.go (the CLI go runs from that
directory):
module railway-config
go 1.22
require github.com/railwayapp/railway-go-sdk v0.6.0
Config as Code migration: railway config migrate --lang go.
Docker Hub and GHCR image sources can follow new image tags automatically.
Pass a railway.AutoUpdates value as the autoUpdates option of
railway.Image: Type is the policy (railway.AutoUpdatesPatch,
railway.AutoUpdatesMinor or railway.AutoUpdatesDisabled) and Schedule
the weekly UTC maintenance windows updates may run in. Each
railway.AutoUpdateWindow has a Day (0 Sunday through 6 Saturday), a
StartHour (0 to 23, inclusive) and an EndHour (1 to 24, exclusive, after
StartHour). The windows are validated when the file is evaluated, so a bad
day or hour fails railway config plan instead of the apply.
nginx := railway.ServiceNamed("nginx", railway.ServiceConfig{
"source": railway.Image("nginx:latest", map[string]any{
"autoUpdates": railway.AutoUpdates{
Type: railway.AutoUpdatesPatch,
// Saturdays 02:00 to 06:00 UTC and Sundays 02:00 to 06:00 UTC.
Schedule: []railway.AutoUpdateWindow{
{Day: 6, StartHour: 2, EndHour: 6},
{Day: 0, StartHour: 2, EndHour: 6},
},
},
}),
})autoUpdates only applies to Docker Hub and GHCR images (nginx:latest,
docker.io/library/nginx, ghcr.io/acme/api); railway.Image panics for
other registries and railway.Github never accepts it. The raw
map[string]any form that railway config pull writes out is still accepted
and validated the same way.
CDN caching is set per service and per environment, for the service's public
domains. The settings live on the edge and apply without a deploy. Pass a
railway.ServiceCdn value as the cdn option of a service:
web := railway.ServiceNamed("web", railway.ServiceConfig{
"cdn": railway.ServiceCdn{Enabled: true},
})
swr := false
docs := railway.ServiceNamed("docs", railway.ServiceConfig{
"cdn": railway.ServiceCdn{
Enabled: true,
DefaultTtlSeconds: 86400,
HtmlCaching: railway.ServiceCdnHtmlCachingForce,
StaleWhileRevalidate: &swr,
PurgeOnDeploy: railway.ServiceCdnPurgeOnDeployAll,
},
})Enabled caches responses from the service's public domains at Railway's
edge. It needs a public domain and cannot be combined with Railway
Authentication. The other knobs tune the cache and each has a default:
DefaultTtlSeconds: how long the edge keeps a cacheable response withoutCache-Controlheaders of its own, in seconds. Defaults to7200.HtmlCaching: whether HTML documents are cached.railway.ServiceCdnHtmlCachingAutofollows the response headers,Forcecaches them regardless,Neverleaves them uncached. Defaults toauto.StaleWhileRevalidate: honourstale-while-revalidateCache-Controldirectives, serving a stale copy while the edge refreshes it. A*boolbecause the default istrue;nilleaves the default.PurgeOnDeploy: what a successful deploy purges from the cache.railway.ServiceCdnPurgeOnDeployHtmlkeeps immutable assets warm,Allclears everything,Offpurges nothing. Defaults tohtml.
Railway serialises the block only while caching is on, and only the knobs that
differ from the defaults. Leaving the block out, Enabled: false and nil
all mean the same thing: no caching, and no drift in railway config plan.
ServiceCdn{Enabled: true} is a service caching with the defaults, so a knob
set to its default does not plan as drift either. The raw map[string]any
form that railway config pull writes out is accepted and validated the same
way.
Requires a Railway CLI that compiles cdn. Older CLIs drop the block when
compiling the config.
A Railway Function is a single file of TypeScript that runs on the Bun runtime
image with no repository or build step. railway.Fn takes the path of that
file under codeFile, reads it when the config is evaluated, and compiles it
into the function image plus a base64-encoded start command, the same shape
the dashboard and railway functions push produce:
// .railway/railway.go, with the source in .railway/hook.ts
hook := railway.Fn("hook", railway.ServiceConfig{
"codeFile": "hook.ts",
"env": map[string]any{"SECRET": railway.Shared("WEBHOOK_SECRET")},
})A relative codeFile is resolved against the directory of the Go file that
calls Fn, so paths are relative to railway.go no matter where railway config plan runs. runtime picks the image from railway.FunctionImages and
defaults to "bun". To pin another image version pass source instead:
railway.Fn("hook", railway.ServiceConfig{
"codeFile": "hook.ts",
"source": railway.Image("ghcr.io/railwayapp/function-bun:1.2.16"),
})The source is limited to 98,295 bytes of UTF-8 (railway.FunctionSourceMaxBytes,
just under 96 KB): the whole payload is one argument of the start command, the
kernel caps a single argument at 128 KiB, and the base64 has to fit after the
./run.sh prefix. Fn panics past that, with the same error Railway returns
on apply. codeFile and start are mutually exclusive — railway.FunctionStartCommand(code)
builds the start command from a string on its own.
A named partial lets each repository manage its own slice of a Railway
environment. Declare const Partial = "<name>" in railway.go (same role as
export const partial in TypeScript and PARTIAL in Python). The CLI records
which partial owns each resource; omitting a resource then only deletes it if
your partial owns it. A partial name is 1 to 64 characters from a-z, A-Z,
0-9, ., _, and -.
An api repository owns the API service and its database:
// api/.railway/railway.go
package main
import "github.com/railwayapp/railway-go-sdk"
const Partial = "api"
func Railway() railway.Project {
db := railway.Postgres("postgres")
api := railway.ServiceNamed("api", railway.ServiceConfig{
"env": map[string]any{
"DATABASE_URL": db.Env("DATABASE_URL"),
},
})
return railway.ProjectNamed("acme", []any{api, db})
}A web repository owns the frontend service:
// web/.railway/railway.go
package main
import "github.com/railwayapp/railway-go-sdk"
const Partial = "web"
func Railway() railway.Project {
web := railway.ServiceNamed("web", railway.ServiceConfig{})
return railway.ProjectNamed("acme", []any{web})
}After both repositories apply, partial api owns service.api and
database.postgres, and partial web owns service.web. Removing db from
the api file deletes the database on the next api apply. Nothing the web
file does can touch it.
Ownership rules the CLI enforces on every plan and apply:
- A resource declared in a file whose partial does not own it fails with
Cannot manage service "api": already managed by partial "web".Move the declaration to the owning repository, or remove it from the owner first. - A file without
Partialfails in an environment that already has named partials. Once any partial has a name, every file targeting that environment must declare one. - A named partial only deletes resources it owns. Resources owned by other partials, or not yet owned by any, are left alone when missing from your file.
- The first
railway config applyfrom a partial claims ownership of every resource the file declares, even when the plan shows no configuration changes. - Do not rename a partial after apply. The resources stay owned by the old name and the renamed file fails the foreign-resource check.
Apply from each repository's own pipeline; Railway does not read .railway/
during deploys.