Solutions — releasing everything together
A Solution is the set of things that make up one product: an app, the database behind it, the buckets it writes to, the domains it answers on. Group them once, and you can release them in one movement — in the right order, with anything that would break refused before it runs.
Most platforms deploy an app. They cannot order a database migration in front of that deploy, because they do not own the database. We do, so we can.
Make one
waymaker host solution create "Acme Portal"
waymaker host solution surface add acme-portal --kind app --id <app-id>
waymaker host solution surface add acme-portal --kind database --id <database-id>
waymaker host solution surfaces acme-portal
A surface belongs to exactly one Solution. Attaching something another Solution already owns is refused, and tells you which one has it. A Solution can hold as many of a kind as you like — three buckets and two databases is fine.
See what a release would do — before it does it
waymaker host solution plan acme-portal
0. migrate database would_apply schema changes apply before any app that reads them
1. deploy app would_apply deploys after its database, so it never boots
against an un-migrated schema
This applies nothing. It is where you find out that a database is not ready, or that an app has no repository, before anything irreversible happens. It does save the plan, as a release you can apply by its id, and that replaces any earlier plan for the Solution that applied nothing. If two people plan the same Solution, the later plan is the one that can be applied. If any step would refuse, the whole release refuses — nothing partial, nothing to undo.
The order is worked out from how your surfaces are connected. You do not configure it.
Where migrations come from
From your repo. Keep each migration as a file in db/migrations/, named so they sort in the
order they should run:
db/migrations/001-accounts.sql
db/migrations/002-orders.sql
db/migrations/010-order-status.sql
The plan reads that directory at the release commit — the commit your staged build was made from
when the Solution releases by release, or the tip of the tracked branch when it releases by push —
and compares it with what the database has already run. Only the files it has not run become a
migrate step, and the plan names each one with the commit it came from:
0. migrate database would_apply schema changes apply before any app that reads them
source: repo acme/portal@3f9c2a1:db/migrations
010-order-status.sql
Nothing new, no migrate step. The plan pins that commit and a fingerprint of each file, and apply reads the same files at the same commit. If a file changed, or the commit cannot be read, apply refuses and runs nothing.
Somewhere else? Point the database at another directory, or at the repository of another app in the same Solution:
waymaker host db migrations-source <database-id> --path supabase/migrations
waymaker host db migrations-source <database-id> --repo https://github.com/acme/portal-api
waymaker host db migrations-source <database-id> --clear # back to db/migrations
A repository no app in the Solution builds is refused.
No repo convention at all? Pass your migrations to the plan instead, and the same file to apply:
waymaker host solution plan acme-portal --migrations ./migrations.json
waymaker host solution release apply <release-id> --migrations ./migrations.json
{ "<app slug, app id or database id>": [{ "name": "001_add_orders", "sql": "CREATE TABLE orders (...);" }] }
When a plan refuses over migrations
| The plan says | Why | What to do |
|---|---|---|
cannot tell which migrations are pending (…) | GitHub or the database could not be read, or there is no staged build to release yet | Fix what it names and plan again. The plan never assumes "nothing pending". |
… sort before the newest applied migration … the ledger and the repo disagree | The database's history was run under different names, or a file was added out of order | Rename the files to match what ran, or pass migrations for this release. Running "pending" here would re-run or skip SQL. |
no migrations found at db/migrations in … — set a path override or pass migrations | Not a refusal: the app deploys against the schema already live | Set the migrations source if they live elsewhere. |
Release it
waymaker host solution release apply <release-id>
Apply runs the plan you already looked at, not a fresh one computed at the last moment. Steps run in order and stop at the first failure; later steps are skipped rather than attempted, because a problem that stops one surface usually affects the next.
A migrate step runs exactly the SQL the plan reviewed. From the repo, each file is read again at the
pinned commit and must match; from --migrations, apply must be given the same SQL. Passing
--migrations to apply for a plan made without them is refused before anything runs — re-plan with
them so they are reviewed.
Refusing is the point. Deploying an app whose migration has not run is exactly the failure the ordering exists to prevent.
When a release stops half way
It happens. Some steps are live, some never ran, and the record says which:
waymaker host solution release status <release-id>
From there you either continue or stop, deliberately:
waymaker host solution release resume <release-id>
waymaker host solution release abandon <release-id> --reason "waiting on the schema review"
Resume does not replay. It works out the plan again against how things are now, and carries across every step that already applied so it is not run twice. A migration that ran once does not run again.
Abandon undoes nothing. Steps that applied stay applied and keep their evidence. Releases only go forwards: to change what is live, release again.
Until you do one or the other, a new plan for that Solution is refused — planning over unfinished work is how you end up running a migration twice.
Data region and the Data Location Statement
A Solution can have a data region: syd, sin, fra, lon or iad. Until it is pinned, the region
is a record, not a commitment. Pinning makes it one, and it is permanent.
waymaker host solution update acme-portal --region fra # owner; refused once pinned
waymaker host solution pin-region acme-portal # owner; cannot be undone
waymaker host solution region-exception add acme-portal --kind transactional_email --reason "..."
waymaker host solution region-exception remove acme-portal --kind transactional_email
Once a Solution is pinned, creating a database or a storage bucket outside its region is refused with 409 and
out_of_region. The message names both regions and the two ways out: create it in the Solution's
region, or have an owner record an exception (with no --id for something that does not exist yet).
The Data Location Statement says where each part of the Solution is and how firmly that is controlled. It is a technical schedule, not legal advice. Every version is kept and never changes.
waymaker host solution location statement acme-portal # latest, as Markdown
waymaker host solution location statement acme-portal -n 3 --format pdf --out statement-v3.pdf
waymaker host solution location versions acme-portal
waymaker host solution location diff acme-portal 2 3
waymaker host solution location drift acme-portal # expected vs observed
waymaker host solution location generate acme-portal # owner; a new version only if something changed
--format takes md, json or pdf, and a PDF needs --out. Pass --drift-ack to generate after
putting a drifted part back. Any member can read the statement; only an owner can issue one.
From an AI assistant, the same operations are the host_solution_region_pin,
host_solution_region_exception_add|remove and host_data_location_* MCP tools
(tool reference). Quote the statement's wording and strength labels as they are
returned: do not restate a location more strongly than the statement does.
Release on merge
A Solution's release_policy is one of three values:
| Value | In the Host app | What a merge to the live branch does |
|---|---|---|
release | After approval | Builds a staged copy; Live changes when someone applies a release |
push | Each tool on its own | Deploys each tool by itself, straight to Live; no migrations run |
merge | Automatically, in order | Plans one release for the merge and applies it, in order |
Moving a Solution to merge is owner only, and it is a delegation: the release_policy_changed
event records who made it, when, and the exact sentence of what they delegated, naming each
repository and branch.
Under merge, once the merged commit's staged build has succeeded, the Solution plans the release
with the same planner as solution plan and applies it with its own credential. A merge release
waits for a person (merge_wait: person, with merge_wait_reason) when:
-
the live branch does not require a reviewed pull request and block force-push, or a ruleset can be bypassed;
-
a migration was not run, with the same file contents, on the staged copy's current database branch;
-
a migration has any statement that is not a standard additive change. The allowlist (
ADDITIVE_STATEMENTS) is:CREATE TABLE(not… AS);CREATE [UNIQUE] INDEX,CREATE SEQUENCE,CREATE TYPE … AS ENUM,CREATE SCHEMA;CREATE EXTENSION IF NOT EXISTSforpgcrypto,"uuid-ossp",citext,pg_trgm,hstoreorvectoronly;ALTER TABLE … ADD COLUMN / ADD CONSTRAINT / VALIDATE CONSTRAINT / ALTER COLUMN … SET DEFAULT / SET NOT NULL, with no function calls beyond a few safe ones (now(),gen_random_uuid(),lower()…), because a new column's default and aCHECKrun on every existing row. An index expression follows the same rule. A safe name counts only unqualified or aspg_catalog.now();public.now()is held;COMMENT ON;BEGINandCOMMIT, with no options.
Everything else waits for a person, including every
INSERT(an upsert andINSERT … SELECTincluded),CREATE TABLE … AS, views,ALTER TYPE,SET,SELECT, and everyUPDATEandDELETE. A single statement longer than 64 KB is not read, so it waits for a person too; -
a migration also hits the second layer, which names the kind: any
DROP,TRUNCATE,RENAME, a column type change,UPDATE,DELETE,MERGE, row-security changes (CREATE/ALTER/DROP POLICY,ENABLE/DISABLE/FORCE/NO FORCE ROW LEVEL SECURITY, aGRANTorREVOKEto or fromanon,authenticatedorPUBLIC), role changes and role grants,SET ROLE,set_config(,OWNER TO,SECURITY DEFINER, and more; -
a migration cannot be read. That covers a control character other than tab and newline (a lone carriage return included;
\r\nis read as a newline), any mention ofstandard_conforming_stringsorbackslash_quote, aDOblock, aCALL, a function or procedure body, any$$quoting, aU&"…"name, or a name with non-ASCII characters. The reason names the file and the kind of statement, never the SQL; -
a migration would lock a table that already has rows while it scans it. The reason names the statement and why, or the safe form where one runs in a migration file:
CREATE [UNIQUE] INDEXon an existing table → building an index on an existing table blocks writes while it builds, so this waits for a person to apply (a migration file runs in one transaction, so an index can't be built without blocking writes);ADD CONSTRAINT … FOREIGN KEYorCHECKwithoutNOT VALID→ add itNOT VALID, thenVALIDATE CONSTRAINTin a later migration;ADD CONSTRAINT … UNIQUEorPRIMARY KEYbuilt in place, orEXCLUDE→ building an index on an existing table blocks writes while it builds, so this waits for a person to apply;ALTER COLUMN … SET NOT NULL→ addCHECK (column IS NOT NULL) NOT VALID, validate it later, then set it;ADD COLUMN … GENERATED, or a new column with an inlineREFERENCES,CHECK,UNIQUEorPRIMARY KEY→ add the plain column, then the constraintNOT VALID;ADD COLUMNwith aserial,bigserialorsmallserialtype, or aDEFAULTthat calls any function butnow()or aCURRENT_*one (gen_random_uuid(),random(),nextval(…), …) → add the column with no default or a constant one, thenSET DEFAULTand fill existing rows in batches. A volatile default fills every existing row under a lock that blocks reads and writes.
UNIQUEorPRIMARY KEY … USING INDEX <an existing index>attaches an index without building one, and goes ahead;… USING INDEX TABLESPACE …builds one in place, and waits.None of these applies to a table the same release creates (without
IF NOT EXISTS): it is new and empty; -
the database has end-user sign-in on, and a migration creates a table in
public(or with no schema) withoutALTER TABLE <that table> ENABLE ROW LEVEL SECURITYanywhere in the same release. Names compare as Postgres reads them:"Notes"is notnotes. If the sign-in setting cannot be read, the release waits too. Turning row-level security on is itself a row-security change, so that release still waits for a person, who applies it as usual; -
a step the Solution cannot run itself, or a pin is not the branch head.
A safe database change that the staged copy has already run goes ahead on its own, and so does a
database's sign-in deploy, once automatic database changes are switched on for the platform. Until
then a release with any database step waits for a person, with merge_wait_reason "automatic database
changes aren't switched on yet, so a person needs to release this". Anything else waits for a person
too: apply it with solution release apply as usual. A migration file that does not read back byte
for byte (a byte-order mark, for one) also waits for a person.
Before a merge release runs a migration it reads the database's migration ledger again. If the ledger
holds a migration that was not there at plan time and is not one of the release's own files, the
release is refused with nothing applied.
Before an automatic database change runs its first statement, and before an automatic sign-in deploy
(deploy_auth) changes anything, it takes a restore point of the database. A resumed step keeps its
first point, and checks it is still there first; if it has been deleted, nothing runs. If the point
cannot be taken, nothing runs: the release is refused (merge_release_refused),
the owners and releasers are told, and a person can apply it as usual. A database change you apply
yourself takes no restore point. When an automatic change fails, the release records a category
(syntax, permission, lock_timeout, constraint, unavailable, ledger or other) and which file
stopped it, never the database's own message or the SQL.
release status lists each point under rollback_points, with the step, when it was taken, and the
call that restores it, without confirm. An owner or releaser of the Solution restores one by adding
"confirm": true:
{ "action": "release_rollback", "database_id": "<database>", "release_id": "<release>", "ordinal": 0, "confirm": true }
on host-postgres-operations. It restores only a point the release recorded for that database (no
other id is accepted), refuses while any release of the Solution is applying, and overwrites everything
written to the database since the point. ordinal is needed only when one release changed the database
more than once.
Restore points are kept for 7 days after the release settles (applied, failed, refused,
abandoned or expired), or 30 days after a release stopped partway (partially_applied), then
deleted; a release that is still planned or applying keeps its points until it settles. A deleted
point is listed with "expired": true and no restore call, and release_rollback on it answers 410.
A merge release still waiting for a person after 14 days becomes expired and is never applied.
The release list and release status return initiated_by (merge or user), merge_wait,
merge_wait_reason, github_actor and commit_sha for each release.
Events, in the Solution's activity:
| Event | When |
|---|---|
merge_release_planned / merge_release_waiting | Planned; waiting for a person, a build, or an unfinished release |
merge_release_queued | Behind a release that is applying |
merge_release_applied / merge_release_failed | Applied, or stopped at a step |
merge_release_refused | Its plan would refuse, or the Live schema moved since the plan |
merge_release_superseded / merge_release_already_live | A newer merge replaced it; the commit was already Live |
merge_release_expired | Waited 14 days for a person |
merge_notice_sent / merge_notice_failed | A notice to the org's owners and the Solution's owners and releasers (a count, never an address) |
The Host app also shows whether the live branch is protected. Set up staging (create a staging
branch at the live branch's head) is not offered yet: Host cannot create branches in your
repositories until its repository access includes writing, and the setup_staging action answers
409 until then. Create staging yourself for now. Their
CLI and MCP commands are not out yet.
Every branch gets its own copy
Every branch gets its own copy of the whole Solution: its front end, its back end and its data. Build on a branch, or in a worktree on your machine, and nothing you do there touches Live. Merge it, and Host releases the change in order.
A pull request on one of the Solution's repositories builds that branch as a copy, with its own database branch when the app has a database. A pull request from an owner or releaser gets a real copy of the data; anyone else's gets the Solution's masked copy, or no data. Every copy has its sign-in tables emptied. The Help page Every Branch Gets Its Own Copy says what this means for the people using it.
Work in a worktree
Each command below is marked available once released until it ships in the CLI and MCP server.
- waymaker host dev
[--app <app>] [--env-file .env.local](available once released): reads the current git branch (a detached HEAD is refused), finds or creates that branch's own database copy, and writesWAYMAKER_DATABASE_URLplus the app's Staging values into the env file. It replaces only the lines between its two marker lines (shown after this list). - waymaker host db branch connect
<app> [--git-branch <b>](available once released): the same, printed to stdout instead of written to a file. - MCP host_postgres_branch_connect
{ app_id, git_branch }(available once released): the same, for an agent. It never returns the Live database.
The env file's marker lines (a marker, not a command):
# --- waymaker host dev ---
WAYMAKER_DATABASE_URL=...
# --- waymaker host dev ---
The Live branch is refused. On the Solution's Live branch each of these answers 409: "This is your Live branch. Host won't hand out the Live database for local work. Use a feature branch." No flag overrides it, and nothing is written. A viewer gets 403: only someone who may manage the database receives a branch address.
List the copies
- waymaker host solution branches
<slug>(available once released), or MCP host_solution_branches{ slug }(available once released), callslist_branchesonhost-solution-operations. Any member of the Solution's org may call it.
It returns each open copy (its tool, branch, address, whether it has its own database and whether
that is a real or masked copy, the last change, and cost_to_date_usd from the billing rate
table), the staged builds, and the worktree copies as a count per database. It never returns a
database branch id, a connection string or a worktree branch's name. A failed read is a 500 with a
fixed message, never a partial list.
Change how branches work (owners)
- waymaker host solution branches set
<slug> [--previews on|off] [--idle-days n] [--parent <branch>|--no-parent](available once released), or MCP host_solution_branch_settings (available once released), callsset_branch_settings:
| Field | What it does |
|---|---|
branch_previews | true (the default): every pull request gets its own copy. false: none do. |
preview_idle_days | A whole number of days, 1 to 90 (default 7). A copy with no change for that long is removed. |
dev_parent_branch_id | The masked branch copies are made from, or null to make them from Live. |
Only an owner may change these (403 otherwise). Each change is recorded in the Solution's activity.
Make copies from a masked branch
A parent is accepted only when Host masked it: masking a branch records it on its database, and
set_branch_settings refuses any other branch with 409, "Mask that branch first. Previews copy
from it, so it must not hold real customer data." The Live branch can never be masked, so it can
never be the parent.
waymaker host db branch create <app> masked-source
waymaker host db branch mask <app> <branchId> # shows what it would change
waymaker host db branch mask <app> <branchId> --confirm # applies it, and records the mask
Then set the parent (dev_parent_branch_id). Deleting a branch removes its record first. A Solution
copying from it keeps its setting, and never falls back to Live: its next copy gets no database, the
owners get one email, and list_branches reports dev_parent: "unproven" until an owner sets a new
parent or null. A worktree connect refuses with 409 while the parent is unavailable.
Who can release
waymaker host solution member add acme-portal <user-id> --role releaser
| Role | Can |
|---|---|
viewer | See the Solution and its release history |
releaser | Also plan and release it |
owner | Also manage who else has access |
A guest can be granted releaser — that is how a contracted developer ships your work without a
seat. It is never automatic: a guest with no grant has no access at all, and revoking their guest
access stops them releasing immediately, whatever their role here says.
Every release keeps its evidence
A release records what each step actually returned — not a status we wrote ourselves. When something
goes wrong, release status tells you which surface refused and what it said, without going near a
log.