9 · Atlas Cloud (optional)

TL;DR

Objective — optionally register your schema with Atlas Cloud for versioned, team-visible migration tracking: open the SSH tunnel, build a baseline migration from the staging schema, push it to Atlas Cloud, apply the baseline to staging, and wire up GitHub CI to gate future schema changes.

User part + done-when

👤 User part — the CI setup is dashboard work: in Atlas Cloud, open Set Up CI → GitHub → CLI and copy the token. An agent handles the SSH tunnel, the baseline build, the push, and the apply.

Done when the baseline migration is built from the staging schema, pushed to Atlas Cloud (ERD renders), staging shows “Synced” (migrate status: OK), and the GitHub CI token is configured.  ·  ⏱ ~20–30 min  ·  🔀 mixed (👤 Atlas Cloud token, 🤖 CLI).

Background

If you have a license, this registers a baseline migration built from your staging database into Atlas Cloud, then gates future schema changes through CI.

Whether to do this page at all:

🔵 OPTIONAL — requires an active Atlas Cloud license

Skip this entire page if you don’t have an Atlas Cloud plan — nothing downstream depends on it. The free workflow (mysqldump --no-data + diff, plus php artisan migrate:status and a GUI like TablePlus / DBeaver) already covers schema snapshots and comparison; you used it on page 5. Atlas Cloud adds versioned, team-visible migration tracking with an ERD and CI gating.

flowchart LR
  Tunnel[SSH tunnel to staging DB] --> Baseline[Register baseline migration]
  Baseline --> Atlas[Atlas Cloud ERD]
  Change[Future schema change] --> CI[CI migration gate]
  CI --> Atlas

Steps

1. Open the SSH tunnel

Tunnel the staging MySQL port to localhost so Atlas can reach it.

1. Open the tunnel and confirm the staging URL is set.

   ssh -L 3307:127.0.0.1:3306 <staging-alias> -N &
   ps aux | grep "ssh -L"
   echo "Staging URL: $ATLAS_STAGING_URL"   # if empty, run `direnv allow` in the project root
   # Expected: the tunnel process is running; $ATLAS_STAGING_URL is non-empty

   • ✅ The tunnel is up and $ATLAS_STAGING_URL resolves.

2. Create the schema baseline

Export the live staging schema and generate a baseline migration from it.

1. Inspect, diff, and mark the baseline applied locally.

   # Backup existing migrations before rebuild (never blind rm)
   ATLAS_MIG_DIR=packages/ZajModules/Database/Atlas/migrations
   if [ -d "$ATLAS_MIG_DIR" ] && [ "$(ls -A "$ATLAS_MIG_DIR" 2>/dev/null)" ]; then
     mv "$ATLAS_MIG_DIR" "${ATLAS_MIG_DIR}.bak.$(date +%Y%m%d-%H%M%S)"
   fi
   mkdir -p "$ATLAS_MIG_DIR"
   
   # Export the live staging schema
   atlas schema inspect -u "$ATLAS_STAGING_URL" --format '{{ sql . }}' \
     > packages/ZajModules/Database/Atlas/schema/current.sql
   grep -c "CREATE TABLE" packages/ZajModules/Database/Atlas/schema/current.sql   # sanity-check table count
   
   # Generate the baseline migration
   atlas migrate diff baseline \
     --dir "file://packages/ZajModules/Database/Atlas/migrations" \
     --to "file://packages/ZajModules/Database/Atlas/schema/current.sql" \
     --dev-url "docker://mysql/8/dev"
   
   # Mark it applied locally (substitute the generated timestamp)
   atlas migrate apply \
     --dir "file://packages/ZajModules/Database/Atlas/migrations" \
     --url "$ATLAS_LOCAL_URL" \
     --baseline "YOUR_TIMESTAMP"
   # Expected: a baseline migration generated and marked applied against the local URL

   • ✅ A baseline migration is generated from the staging schema and marked applied locally.

3. Push to Atlas Cloud

Publish the baseline migration directory to Atlas Cloud.

1. Push the migrations directory.

   atlas migrate push YOUR_PROJECT_NAME \
     --dir "file://packages/ZajModules/Database/Atlas/migrations" \
     --dev-url "docker://mysql/8/dev"
   # Expected: a project URL is returned; the ERD tab shows your tables

   • ✅ The push returns a URL and the ERD tab shows your tables.

Open the returned URL — the ERD tab should show your tables.

4. Apply the baseline to staging

Register staging against the pushed baseline and confirm it’s synced.

1. Apply the baseline and check status.

   atlas migrate apply \
     --dir "file://packages/ZajModules/Database/Atlas/migrations" \
     --url "$ATLAS_STAGING_URL" \
     --baseline "YOUR_TIMESTAMP"
   
   atlas migrate status \
     --dir "file://packages/ZajModules/Database/Atlas/migrations" \
     --url "$ATLAS_STAGING_URL"
   # expect: Migration Status: OK

   • ✅ Migration Status: OK — staging is registered and synced.

5. Wire up GitHub CI

Gate future schema changes through CI by registering a cloud token and the cloud environments.

Who does this

👤 User opens Atlas Cloud → Set Up CI → GitHub → CLI in the browser and copies the aci_… token — a dashboard action an agent can’t perform.

1. Copy the token, set the secret, and register the databases.

   1. Atlas Cloud → Set Up CI → GitHub → CLI → copy the token (aci_…).

   2. Store the secret without putting the token in shell history:

      printf '%s' 'aci_…' | gh secret set ATLAS_CLOUD_TOKEN --repo OWNER/REPO
      # Or: gh secret set ATLAS_CLOUD_TOKEN < /path/to/token-file

   3. Add the cloud environments to atlas.hcl.

   4. Register databases: atlas migrate apply --env cloud-staging --baseline "YOUR_TIMESTAMP".

   • ✅ The CI token is stored as ATLAS_CLOUD_TOKEN, cloud envs are in atlas.hcl, and databases are registered.

Checklist

Do not mark this step done until every box below is checked.

• 🤖 Baseline created — baseline migration created from the staging schema.
• 🤖 Pushed to Atlas Cloud — ERD renders correctly.
• 🤖 Staging synced — staging registered and showing “Synced” (migrate status: OK).
• 🔀 CI configured — GitHub CI token configured (ATLAS_CLOUD_TOKEN) (👤 copy token from Atlas Cloud).

→Next step

That closes the optional staging tracks. Continue to Phase 6 · SuperAdmin setup — brand and configure the app on staging.