XII. Admin processes

Run admin/management tasks as one-off processes

“One-off admin processes should be run in an identical environment as the regular long-running processes of the app.” – 12factor.net

When to use

Database migrations, REPL shells, one-time scripts.

Why it matters

  • Consistency: Admin scripts should run against the same code and config as the app. Don’t run SQL migrations manually from your laptop if the app uses a specific ORM version.

Signs of Violation

  • Connect to Production DB from local laptop to modify schema.
  • Editing data directly in DB instead of using a script.

Explanation

Problem

Drift. Your laptop environment (libs, versions) might be different from prod, causing the migration to fail or corrupt data.

Solution

Ship the admin scripts with the app. Run them on the platform.

Real world analogy

Tools in the car trunk. The jack and spare tire (Admin Tools) travel with the car (App). You don’t keep the jack at home; you might need it on the road.

Pros and Cons

Pros Cons
  • Reproducibility
  • Safety
    		•
  • Need access to run commands on prod (SSH/kubectl exec)
    		•

    Comparison

    • REPL: rails console or tinker are examples of Admin Processes.

    Code example

    Typescript

    Bad (Violation)

    Good (Adherence)

    PHP

    Bad (Violation)

    Good (Adherence)