Waymaker
WaymakerDocs
Developer Documentation
Documentation

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 saysWhyWhat to do
cannot tell which migrations are pending (…)GitHub or the database could not be read, or there is no staged build to release yetFix what it names and plan again. The plan never assumes "nothing pending".
… sort before the newest applied migration … the ledger and the repo disagreeThe database's history was run under different names, or a file was added out of orderRename 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 migrationsNot a refusal: the app deploys against the schema already liveSet 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:

ValueIn the Host appWhat a merge to the live branch does
releaseAfter approvalBuilds a staged copy; Live changes when someone applies a release
pushEach tool on its ownDeploys each tool by itself, straight to Live; no migrations run
mergeAutomatically, in orderPlans 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 EXISTS for pgcrypto, "uuid-ossp", citext, pg_trgm, hstore or vector only;
    • 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 a CHECK run on every existing row. An index expression follows the same rule. A safe name counts only unqualified or as pg_catalog.now(); public.now() is held;
    • COMMENT ON;
    • BEGIN and COMMIT, with no options.

    Everything else waits for a person, including every INSERT (an upsert and INSERT … SELECT included), CREATE TABLE … AS, views, ALTER TYPE, SET, SELECT, and every UPDATE and DELETE. 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, a GRANT or REVOKE to or from anon, authenticated or PUBLIC), 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\n is read as a newline), any mention of standard_conforming_strings or backslash_quote, a DO block, a CALL, a function or procedure body, any $$ quoting, a U&"…" 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] INDEX on 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 KEY or CHECK without NOT VALID → add it NOT VALID, then VALIDATE CONSTRAINT in a later migration;
    • ADD CONSTRAINT … UNIQUE or PRIMARY KEY built in place, or EXCLUDE → 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 → add CHECK (column IS NOT NULL) NOT VALID, validate it later, then set it;
    • ADD COLUMN … GENERATED, or a new column with an inline REFERENCES, CHECK, UNIQUE or PRIMARY KEY → add the plain column, then the constraint NOT VALID;
    • ADD COLUMN with a serial, bigserial or smallserial type, or a DEFAULT that calls any function but now() or a CURRENT_* one (gen_random_uuid(), random(), nextval(…), …) → add the column with no default or a constant one, then SET DEFAULT and fill existing rows in batches. A volatile default fills every existing row under a lock that blocks reads and writes.

    UNIQUE or PRIMARY 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) without ALTER TABLE <that table> ENABLE ROW LEVEL SECURITY anywhere in the same release. Names compare as Postgres reads them: "Notes" is not notes. 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:

EventWhen
merge_release_planned / merge_release_waitingPlanned; waiting for a person, a build, or an unfinished release
merge_release_queuedBehind a release that is applying
merge_release_applied / merge_release_failedApplied, or stopped at a step
merge_release_refusedIts plan would refuse, or the Live schema moved since the plan
merge_release_superseded / merge_release_already_liveA newer merge replaced it; the commit was already Live
merge_release_expiredWaited 14 days for a person
merge_notice_sent / merge_notice_failedA 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 writes WAYMAKER_DATABASE_URL plus 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), calls list_branches on host-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), calls set_branch_settings:
FieldWhat it does
branch_previewstrue (the default): every pull request gets its own copy. false: none do.
preview_idle_daysA whole number of days, 1 to 90 (default 7). A copy with no change for that long is removed.
dev_parent_branch_idThe 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
RoleCan
viewerSee the Solution and its release history
releaserAlso plan and release it
ownerAlso 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.