Environments: dev, stage, and prod

It worked on your laptop. The notebook showed the right revenue. You pasted the SQL into “the production query” at 6:40 p.m. because the board deck was due. By morning, three other dashboards still used last week’s logic, a secret API key sat in a screenshot, and nobody could say whether staging had been tested at all. Laptop truth is not evil. Treating laptop truth as production truth is how good analysts ship bad numbers.

This is Part 6 of How data actually moves. Part 5 introduced dbt-style models and layers. This part is about environments: dev, stage (or test), and prod; promotion paths; secrets; and who is allowed to write where. You still need quality discipline (Data quality), solid SQL (SQL series), and metric definitions that do not change mid-flight (Metrics that matter). Map the rest of AMS on Learn.

What you’ll learn

What dev, stage, and prod mean for data work (not only software apps)
Why “it worked on my machine” is a data risk, not a joke
A simple promotion path from idea to trusted table
Where secrets belong (and never belong)
Who should write to prod, and what analysts can still own safely
A worked contract table and common failure modes

Environments in plain English

An environment is a place with its own data, credentials, permissions, and purpose. Software teams use dev/stage/prod so bugs die before customers see them. Data teams need the same idea so broken transforms die before executives screenshot them.

Exact names vary. Some shops use “sandbox,” “UAT,” “pre-prod.” The jobs stay similar:

Three data environments: dev for experiments, stage for realistic tests, prod for trusted tables. Laptop truth is not production truth.

Environment	Purpose	Data flavor	Who writes?	Who reads for decisions?
Dev	Explore, break, learn	Sample, subset, or synthetic	Analysts and engineers freely (within policy)	Almost nobody for real decisions
Stage / test	Validate before promote	Production-like, sometimes masked	Automation plus reviewers	Limited QA and stakeholders for sign-off
Prod	Serve trusted consumers	Full, protected, audited	Pipelines and tightly gated humans	BI, ops, leadership

If your company only has “one warehouse and everyone is admin,” you still have environments in theory. You just collapsed them into a single blast radius. Part of growing up as a data team is separating those blast radii on purpose.

Why laptop truth is dangerous

Your laptop is a private universe:

Different data. You filtered to one region, one month, or a CSV export that is already stale.
Different code version. The notebook has three cells you never re-ran in order. Prod has last month’s scheduled job.
Different secrets and network. Your VPN, personal tokens, and cached credentials are not the service account the nightly job uses.
Different packages and warehouse settings. Local Python 3.11 vs server 3.9; session timezone; query slot limits.
No second pair of eyes. The bug that only appears on leap days or fiscal week 53 never hits a PR.

When you say “it works,” people hear “it is safe for the company.” Those are different claims. Local exploration is how good analysis starts. Promotion is how it becomes a shared asset. Skipping promotion is how you get “final_final_v7_USE_THIS.xlsx” culture inside a warehouse.

Rule of thumb: If a number will drive a decision for someone who is not you, it needs a path through shared code, tests, and an environment that is not your laptop alone.

What “prod” means for tables and dashboards

Production is not only the web app customers click. In analytics, prod often means:

Schemas or projects named like analytics, marts, or prod
Scheduled dbt builds and orchestrated jobs (Parts 4 and 5)
BI datasets pinned to those tables
Service accounts that run without your laptop being open
Access reviews, backups, and sometimes legal retention rules

A “prod dashboard” pointed at a personal schema is cosplay. It looks official and fails like a draft.

A simple promotion path

You do not need a 40-page change board for every column rename. You do need a path people can recite:

Explore in dev. Sample data, rough SQL, notebooks OK. Label outputs as exploratory.
Capture the logic in shared code. Repo file, dbt model, scheduled query. Not only a private notebook cell.
Add the minimum tests and docs. Grain sentence, unique key, not-null on the money column. Link metric specs when relevant.
Run in stage against production-like data. Compare row counts, spot-check totals, invite a stakeholder to click the stage dashboard if the change is user-facing.
Review and promote. Pull request, peer review, automated build. Prefer pipeline deploy over hand-editing prod tables.
Watch after release. Freshness, volume, and test status (Part 7). Have a rollback or “previous model version” story.

Small teams compress steps. They should not skip the idea. Even “PR + stage dataset + 24-hour watch” beats silent prod edits.

Secrets: passwords, tokens, and “quick shares”

Environments are partly about credentials:

Warehouse passwords and key pairs
Cloud access keys
SaaS API tokens for extracts
BI service accounts
SSH keys and webhook secrets

Rules that keep you employed:

Never commit secrets to git. Not even “just for a minute.” History remembers.
Never paste production passwords into Slack or tickets. Use a secrets manager or approved vault.
Prefer service accounts for jobs. Jobs should not run as “you” after you leave the company.
Least privilege per environment. Dev credentials should not allow unrestricted prod drops if you can avoid it.
Rotate when people leave or when a leak is suspected. Boring and mandatory.

Analysts inherit pipelines that already have secrets wired in. Your job is not to invent a parallel set of personal keys “because IT is slow.” Your job is to use the approved path or escalate the blocker. Shadow credentials become shadow outages.

Who can write prod?

Writing prod means creating or replacing tables, changing scheduled jobs, or altering the definition consumers trust. Reading prod is different. Many analysts need read access to production marts so decisions use real data. That does not mean everyone should CREATE OR REPLACE those marts from a laptop session.

A healthy split:

Broad read on documented marts for people who answer business questions
Write through automation (CI, orchestrator, dbt Cloud job) after review
Break-glass human write for emergencies, logged, time-limited, rare
Dev write freedom so exploration stays fast

If you are an analyst without prod write, you are not “less technical.” You are on a team that separates exploration from publication. Push logic via PR. Own the definition. Let the pipeline publish. That is adult analytics, not a demotion.

If you are the whole data team, still pretend you have two hats: explorer-you and publisher-you. Explorer-you may be sloppy. Publisher-you needs tests, a second look, and a quiet deploy window.

Worked example: a one-page environment contract

Teams argue less when the contract is written. Here is a lightweight example for a mid-size warehouse that serves finance and marketing dashboards. Adapt names to your stack.

Filled environment contract card showing schema names, who writes, approval path, secrets location, and post-deploy c…

Topic	Dev	Stage	Prod
Schema / project	`dev_analytics`	`stage_analytics`	`analytics`
Data	7-day sample + synthetic PII	Full clone, masked emails	Live full data
Human write	All data team	CI service account only	CI service account only
Break-glass	N/A	Lead + ticket	Two people + ticket, 2-hour window
Promotion	Branch builds	Merge to main → stage job	Green stage + approve → prod job
Secrets	Personal scoped tokens in vault	Job secrets in vault	Job secrets in vault, no personal keys
Dashboards	Personal or draft folder	QA folder	Certified folder only
Post-deploy	Optional	Tests + row-count compare	Tests + 24h freshness watch

Example promotion checklist an analyst can paste into a PR description:

## Change
- Model: fct_revenue_daily
- Why: paid status now includes 'CAPTURED' (metric spec v1.3)

## Checks
- [ ] Grain sentence updated in docs
- [ ] unique + not_null tests still green on stage
- [ ] stage revenue vs prod revenue for last 7 days within 2%
      (or explained by the definition change)
- [ ] Stakeholder sample on stage dashboard: @finance-partner
- [ ] No secrets or warehouse passwords in this PR
- [ ] Rollback: previous model tag / prior job version noted

## Ask
Please approve promote to prod after stage green.

That checklist is boring on purpose. Boring deploys are how you sleep.

Special cases analysts hit every week

“Can I just run this once in prod?”

Maybe for a read-only diagnostic. For a write that changes a shared table, prefer a branch model or a one-off job in stage first. “Once” becomes “the undocumented source of truth.”

Notebooks and Python

Notebooks are excellent for exploration and teaching (Python for analytics). They are weak as silent production unless you graduate them into scheduled scripts with environments and secrets injection. If the notebook creates a table consumers use, treat it as a pipeline with a promotion story, not a personal scratchpad.

Spreadsheets as shadow prod

A Sheet that leadership opens every Monday is an environment, whether IT says so or not. Document its source, freeze the formula change process, and prefer a mart export over hand-typed numbers. The spreadsheets series on this site is about that bridge; environments still apply.

Hotfix under time pressure

Board decks create corner cutting. Time-box the emergency path: break-glass access, pair if possible, write the ticket afterward the same day, and schedule the proper PR within 48 hours. Untracked hotfixes are how environments rot.

How environments connect to quality and metrics

Environments are not bureaucracy for its own sake. They protect the habits you already practiced on this site.

Data quality: Validation in stage catches null spikes and key collisions before consumers trust the number (Data quality).
Metrics: A definition change is a product change. Promote it with a version note the same way you would change a North Star formula (Metrics that matter).
SQL and Python: Exploration stays fast in dev. Publication gets review. That split keeps curiosity alive without making every notebook a silent dependency.

When leadership asks why a number moved after a release, you want a trail: ticket, PR, stage compare, prod deploy time. Environments create that trail. Without them, every surprise becomes a blame conversation about people instead of a path conversation about process.

Common mistakes

One shared admin login for the warehouse. No audit trail, maximum blast radius.
Prod write for everyone “so we move fast.” You move fast into outages.
Stage that is nothing like prod. Then stage green means nothing.
Secrets in notebooks, screenshots, or git. Leaks and broken offboarding.
Dashboard pointed at personal schemas. Official looking, privately maintained.
No rollback plan. Every deploy becomes a prayer.
Skipping tests on “tiny” changes. Tiny filter changes create huge metric swings.
Confusing read access with write rights. Analysts need prod reads; pipelines should own prod writes.

How to practice this week

Draw your real environments on one page: names, who writes, who reads for decisions.
List three tables or dashboards people treat as prod. Confirm they are not fed by personal schemas.
Find one secret in an unsafe place (if any) and move it through the official channel. Do not paste it into chat while “fixing” it.
Take one logic change you would have shipped from a laptop and walk it through a mock PR checklist instead.
Ask who has break-glass prod write. If the answer is “everyone” or “nobody knows,” raise it as a risk, not a blame session.
Pair with engineering (or your future self) on where stage data comes from and whether it is realistic enough to trust.

Quick recap

Dev, stage, and prod separate experiment, validation, and trusted serve.
Laptop truth is incomplete: data, code version, secrets, and review all differ.
Promotion is explore → shared code → tests → stage → review → prod → watch.
Secrets live in vaults and job identities, not git, Slack, or screenshots.
Prefer pipeline writes to prod; keep analyst reads broad and human writes gated.
Next: observability signals (freshness, volume, schema drift, tests) and who gets paged (Part 7).

Sources

Research and further reading used for this article:

dbt Labs: Deployment environments (dev vs deployment environments and why separation matters)
dbt Labs: Environments in dbt (how teams structure development and deployment)
Google Cloud: BigQuery INFORMATION_SCHEMA for tables (inspecting what exists where when comparing environments)
Snowflake: Staging data considerations (staging as a deliberate step before load into destination tables)
OWASP Top Ten (security mindset for secrets handling and access; adapt to data platforms)
Analytics Made Simple: Data quality (validation before you trust a promote)
Analytics Made Simple: Python for analytics (exploration tools that still need a promotion story)
Analytics Made Simple: Learn (related series map)