{"componentChunkName":"component---src-gatsby-theme-chronoblog-templates-note-js","path":"/notes/supabase-migrations-github-actions/","result":{"data":{"mdx":{"parent":{"__typename":"File","fields":{"gitLogLatestDate":"2026-11-20 18:00:09 +0100"}},"id":"99f9ca43-351a-50c2-8af0-c4f9d5f36ba7","excerpt":"Schema changes for a hosted Supabase project belong in versioned SQL files. The  Supabase CLI  applies those files in filename order and…","frontmatter":{"title":"Supabase migrations with GitHub Actions","date":"2026-11-20 16:20:00 UTC","job_ad":null,"job_ad_id":null,"job_ad_url":null,"tags":["supabase","postgres","github-actions","migrations"],"cover":{"childImageSharp":{"fluid":{"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAKCAYAAAC0VX7mAAAACXBIWXMAAAPoAAAD6AG1e1JrAAAAk0lEQVQoz82RyQ7CMBBD8/8fCRJJF0DN0knSzHQxajjCCYrESO/isSxZVjj41LZt+BTgVfsq8B3q8MrWMnZSXMBlhXMC72YIryBaMAylalNeUabn31mGs1L9FATXnit7htIXj8YQgp8Ro6BrE/ouIyeBHQqMDmibCBoFNHL1Gu2rtgfcb4TzyVeC5x9UPnyUv1/5AXGbFZi2205oAAAAAElFTkSuQmCC","aspectRatio":2.0869565217391304,"src":"/static/df768b80a04275d742af0dcd0b047f13/c4ecb/cover.png","srcSet":"/static/df768b80a04275d742af0dcd0b047f13/57ab0/cover.png 192w,\n/static/df768b80a04275d742af0dcd0b047f13/f4739/cover.png 384w,\n/static/df768b80a04275d742af0dcd0b047f13/c4ecb/cover.png 768w","srcWebp":"/static/df768b80a04275d742af0dcd0b047f13/dd090/cover.webp","srcSetWebp":"/static/df768b80a04275d742af0dcd0b047f13/ae504/cover.webp 192w,\n/static/df768b80a04275d742af0dcd0b047f13/fef30/cover.webp 384w,\n/static/df768b80a04275d742af0dcd0b047f13/dd090/cover.webp 768w","sizes":"(max-width: 768px) 100vw, 768px","presentationWidth":768,"presentationHeight":366},"resize":{"src":"/static/df768b80a04275d742af0dcd0b047f13/c4ecb/cover.png"}}}},"fields":{"slug":"/notes/supabase-migrations-github-actions/","readingTime":{"text":"5 min read"}},"body":"function _extends() { _extends = Object.assign || function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }\n\nfunction _objectWithoutProperties(source, excluded) { if (source == null) return {}; var target = _objectWithoutPropertiesLoose(source, excluded); var key, i; if (Object.getOwnPropertySymbols) { var sourceSymbolKeys = Object.getOwnPropertySymbols(source); for (i = 0; i < sourceSymbolKeys.length; i++) { key = sourceSymbolKeys[i]; if (excluded.indexOf(key) >= 0) continue; if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue; target[key] = source[key]; } } return target; }\n\nfunction _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }\n\n/* @jsxRuntime classic */\n\n/* @jsx mdx */\nvar _frontmatter = {\n  \"title\": \"Supabase migrations with GitHub Actions\",\n  \"date\": \"2026-11-20 16:20:00 UTC\",\n  \"cover\": \"./cover.png\",\n  \"tags\": [\"supabase\", \"postgres\", \"github-actions\", \"migrations\"],\n  \"canonical_url\": \"https://sevic.dev/notes/supabase-migrations-github-actions/\"\n};\nvar layoutProps = {\n  _frontmatter: _frontmatter\n};\nvar MDXLayout = \"wrapper\";\nreturn function MDXContent(_ref) {\n  var components = _ref.components,\n      props = _objectWithoutProperties(_ref, [\"components\"]);\n\n  return mdx(MDXLayout, _extends({}, layoutProps, props, {\n    components: components,\n    mdxType: \"MDXLayout\"\n  }), mdx(\"p\", null, \"Schema changes for a hosted Supabase project belong in versioned SQL files. The \", mdx(\"a\", _extends({\n    parentName: \"p\"\n  }, {\n    \"href\": \"https://supabase.com/docs/guides/cli\"\n  }), \"Supabase CLI\"), \" applies those files in filename order and records each one in \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"supabase_migrations.schema_migrations\"), \". A GitHub Action can run \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"supabase db push\"), \" when migration files land on the production branch, so the hosted database stays aligned with git.\"), mdx(\"p\", null, \"The \", mdx(\"a\", _extends({\n    parentName: \"p\"\n  }, {\n    \"href\": \"https://sevic.dev/notes/supabase-basics-nodejs/\"\n  }), \"Supabase basics\"), \" note applies a first schema from the SQL Editor. This post covers migration files, the session-pooler connection GitHub-hosted runners need, a workflow that pushes on changes under \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"supabase/migrations\"), \", and pitfalls. Workflow syntax is the same as in \", mdx(\"a\", _extends({\n    parentName: \"p\"\n  }, {\n    \"href\": \"https://sevic.dev/notes/github-actions-101/\"\n  }), \"GitHub actions 101\"), \".\"), mdx(\"h3\", {\n    \"id\": \"prerequisites\"\n  }, \"Prerequisites\"), mdx(\"ul\", null, mdx(\"li\", {\n    parentName: \"ul\"\n  }, \"A Supabase project\"), mdx(\"li\", {\n    parentName: \"ul\"\n  }, \"The Supabase CLI (\", mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"supabase --version\"), \" locally, so you can pin the same version in CI)\"), mdx(\"li\", {\n    parentName: \"ul\"\n  }, \"A GitHub repository with Actions enabled\")), mdx(\"h3\", {\n    \"id\": \"migration-files\"\n  }, \"Migration files\"), mdx(\"p\", null, \"Initialize the CLI config once, then add a migration. \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"supabase migration new\"), \" creates an empty SQL file under \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"supabase/migrations\"), \" with a timestamp prefix:\"), mdx(\"pre\", null, mdx(\"code\", _extends({\n    parentName: \"pre\"\n  }, {\n    \"className\": \"language-bash\"\n  }), \"supabase init\\nsupabase migration new create_todos\\n\")), mdx(\"pre\", null, mdx(\"code\", _extends({\n    parentName: \"pre\"\n  }, {\n    \"className\": \"language-sql\"\n  }), \"-- supabase/migrations/20261120162000_create_todos.sql\\ncreate table if not exists public.todos (\\n  id bigint generated always as identity primary key,\\n  title text not null,\\n  done boolean not null default false,\\n  created_at timestamptz not null default now()\\n);\\n\")), mdx(\"p\", null, \"The next change is a new file. Leave a file that production has already applied unchanged:\"), mdx(\"pre\", null, mdx(\"code\", _extends({\n    parentName: \"pre\"\n  }, {\n    \"className\": \"language-bash\"\n  }), \"supabase migration new add_todo_priority\\n\")), mdx(\"pre\", null, mdx(\"code\", _extends({\n    parentName: \"pre\"\n  }, {\n    \"className\": \"language-sql\"\n  }), \"alter table public.todos\\n  add column if not exists priority integer not null default 0;\\n\")), mdx(\"p\", null, \"Replay the files against a local database before you push them:\"), mdx(\"pre\", null, mdx(\"code\", _extends({\n    parentName: \"pre\"\n  }, {\n    \"className\": \"language-bash\"\n  }), \"supabase start\\nsupabase db reset\\n\")), mdx(\"p\", null, mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"db reset\"), \" rebuilds the local database and runs every file in \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"supabase/migrations\"), \" in order.\"), mdx(\"h3\", {\n    \"id\": \"session-pooler-from-github-actions\"\n  }, \"Session pooler from GitHub Actions\"), mdx(\"p\", null, \"GitHub-hosted runners are IPv4-only. The direct database host (\", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"db.<project-ref>.supabase.co\"), \") is IPv6 unless the project has the IPv4 add-on, so a push from Actions often never connects.\"), mdx(\"p\", null, \"Use the \", mdx(\"strong\", {\n    parentName: \"p\"\n  }, \"session pooler\"), \" string from Dashboard \\u2192 Connect \\u2192 Session pooler. It is IPv4, and port \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"5432\"), \" keeps a real Postgres session, which DDL needs. Port \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"6543\"), \" is transaction mode and is the wrong target for \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"db push\"), \".\"), mdx(\"table\", null, mdx(\"thead\", {\n    parentName: \"table\"\n  }, mdx(\"tr\", {\n    parentName: \"thead\"\n  }, mdx(\"th\", _extends({\n    parentName: \"tr\"\n  }, {\n    \"align\": null\n  }), \"Piece\"), mdx(\"th\", _extends({\n    parentName: \"tr\"\n  }, {\n    \"align\": null\n  }), \"Value\"))), mdx(\"tbody\", {\n    parentName: \"table\"\n  }, mdx(\"tr\", {\n    parentName: \"tbody\"\n  }, mdx(\"td\", _extends({\n    parentName: \"tr\"\n  }, {\n    \"align\": null\n  }), mdx(\"strong\", {\n    parentName: \"td\"\n  }, \"User\")), mdx(\"td\", _extends({\n    parentName: \"tr\"\n  }, {\n    \"align\": null\n  }), mdx(\"inlineCode\", {\n    parentName: \"td\"\n  }, \"postgres.<project-ref>\"))), mdx(\"tr\", {\n    parentName: \"tbody\"\n  }, mdx(\"td\", _extends({\n    parentName: \"tr\"\n  }, {\n    \"align\": null\n  }), mdx(\"strong\", {\n    parentName: \"td\"\n  }, \"Password\")), mdx(\"td\", _extends({\n    parentName: \"tr\"\n  }, {\n    \"align\": null\n  }), \"Database password, percent-encoded\")), mdx(\"tr\", {\n    parentName: \"tbody\"\n  }, mdx(\"td\", _extends({\n    parentName: \"tr\"\n  }, {\n    \"align\": null\n  }), mdx(\"strong\", {\n    parentName: \"td\"\n  }, \"Host\")), mdx(\"td\", _extends({\n    parentName: \"tr\"\n  }, {\n    \"align\": null\n  }), \"Session pooler host, copied from Connect\")), mdx(\"tr\", {\n    parentName: \"tbody\"\n  }, mdx(\"td\", _extends({\n    parentName: \"tr\"\n  }, {\n    \"align\": null\n  }), mdx(\"strong\", {\n    parentName: \"td\"\n  }, \"Port\")), mdx(\"td\", _extends({\n    parentName: \"tr\"\n  }, {\n    \"align\": null\n  }), mdx(\"inlineCode\", {\n    parentName: \"td\"\n  }, \"5432\"))), mdx(\"tr\", {\n    parentName: \"tbody\"\n  }, mdx(\"td\", _extends({\n    parentName: \"tr\"\n  }, {\n    \"align\": null\n  }), mdx(\"strong\", {\n    parentName: \"td\"\n  }, \"Database\")), mdx(\"td\", _extends({\n    parentName: \"tr\"\n  }, {\n    \"align\": null\n  }), mdx(\"inlineCode\", {\n    parentName: \"td\"\n  }, \"postgres\"))))), mdx(\"pre\", null, mdx(\"code\", _extends({\n    parentName: \"pre\"\n  }, {\n    \"className\": \"language-text\"\n  }), \"postgresql://postgres.<project-ref>:<encoded-password>@<pooler-host>:5432/postgres\\n\")), mdx(\"p\", null, \"The pooler host looks like \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"aws-1-eu-west-1.pooler.supabase.com\"), \". The \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"aws-N\"), \" prefix is a cluster index, not something you can derive from the region. Copy it from the Connect dialog.\"), mdx(\"p\", null, mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"<project-ref>\"), \" is the id in the dashboard URL: \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"https://supabase.com/dashboard/project/<project-ref>\"), \".\"), mdx(\"p\", null, \"Characters such as \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"@\"), \", \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"#\"), \", \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"%\"), \", and \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"/\"), \" in the database password break that URI. Percent-encode the whole password before you interpolate it. \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"urllib.parse.quote\"), \" with \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"safe=''\"), \" encodes every reserved character, including \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"/\"), \".\"), mdx(\"h3\", {\n    \"id\": \"github-action\"\n  }, \"GitHub Action\"), mdx(\"p\", null, \"Store the values in Settings \\u2192 Secrets and variables \\u2192 Actions:\"), mdx(\"ul\", null, mdx(\"li\", {\n    parentName: \"ul\"\n  }, mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"SUPABASE_DB_PASSWORD\"), \" - database password for the project\"), mdx(\"li\", {\n    parentName: \"ul\"\n  }, mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"SUPABASE_PROJECT_ID\"), \" - the project ref\")), mdx(\"p\", null, \"The pooler host is not a secret. Put it in the workflow \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"env\"), \" after you copy it from Connect.\"), mdx(\"p\", null, \"This workflow runs on a push to \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"master\"), \" that touches \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"supabase/migrations/**\"), \", and from the Actions tab via \", mdx(\"strong\", {\n    parentName: \"p\"\n  }, \"Run workflow\"), \" (\", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"workflow_dispatch\"), \"). Change \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"master\"), \" if production follows another branch. \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"--yes\"), \" skips the CLI confirmation prompt so the job does not wait for input.\"), mdx(\"pre\", null, mdx(\"code\", _extends({\n    parentName: \"pre\"\n  }, {\n    \"className\": \"language-yml\"\n  }), \"# .github/workflows/deploy-migrations.yml\\nname: Deploy Migrations to Production\\n\\non:\\n  push:\\n    branches:\\n      - master\\n    paths:\\n      - 'supabase/migrations/**'\\n  workflow_dispatch:\\n\\njobs:\\n  deploy:\\n    runs-on: ubuntu-latest\\n    env:\\n      SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }}\\n      SUPABASE_PROJECT_ID: ${{ secrets.SUPABASE_PROJECT_ID }}\\n      # Dashboard \\u2192 Connect \\u2192 Session pooler. Do not guess the aws-N prefix.\\n      SUPABASE_POOLER_HOST: aws-1-eu-west-1.pooler.supabase.com\\n\\n    steps:\\n      - uses: actions/checkout@v4\\n\\n      - uses: supabase/setup-cli@v1\\n        with:\\n          version: 2.67.1 # same version as local `supabase --version`\\n\\n      - name: Push migrations\\n        run: |\\n          ENCODED=$(python3 -c \\\"import urllib.parse, os; print(urllib.parse.quote(os.environ['SUPABASE_DB_PASSWORD'], safe=''))\\\")\\n          supabase db push --yes --db-url \\\"postgresql://postgres.${SUPABASE_PROJECT_ID}:${ENCODED}@${SUPABASE_POOLER_HOST}:5432/postgres\\\"\\n\")), mdx(\"p\", null, mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"actions/checkout\"), \" is required so the runner has the \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"supabase/migrations\"), \" directory. \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"supabase/setup-cli\"), \" installs the CLI. Pin \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"version\"), \" to the CLI you already use locally, so a later release does not change push behavior on its own.\"), mdx(\"p\", null, mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"db push\"), \" compares those files with \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"supabase_migrations.schema_migrations\"), \" on the remote database and applies only the pending ones, in filename order. A push that does not change \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"supabase/migrations\"), \" does not start this workflow. \", mdx(\"strong\", {\n    parentName: \"p\"\n  }, \"Run workflow\"), \" on the Actions tab applies whatever is already pending, which is useful after you fix a secret or the pooler host.\"), mdx(\"p\", null, mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"db push --db-url\"), \" authenticates with the database password. \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"supabase link\"), \" uses \", mdx(\"inlineCode\", {\n    parentName: \"p\"\n  }, \"SUPABASE_ACCESS_TOKEN\"), \" and then opens the direct database host, which is the connection GitHub-hosted runners often cannot reach.\"), mdx(\"h3\", {\n    \"id\": \"pitfalls\"\n  }, \"Pitfalls\"), mdx(\"ul\", null, mdx(\"li\", {\n    parentName: \"ul\"\n  }, mdx(\"strong\", {\n    parentName: \"li\"\n  }, \"Direct host from Actions\"), \" - \", mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"db.<project-ref>.supabase.co\"), \" is IPv6 unless the IPv4 add-on is enabled. Use the session pooler host on port \", mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"5432\"), \".\"), mdx(\"li\", {\n    parentName: \"ul\"\n  }, mdx(\"strong\", {\n    parentName: \"li\"\n  }, \"Transaction pooler\"), \" - port \", mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"6543\"), \" is the wrong mode for migrations. Session mode is port \", mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"5432\"), \", and the user is \", mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"postgres.<project-ref>\"), \".\"), mdx(\"li\", {\n    parentName: \"ul\"\n  }, mdx(\"strong\", {\n    parentName: \"li\"\n  }, \"Guessed pooler host\"), \" - \", mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"aws-0\"), \" and \", mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"aws-1\"), \" are both real. Copy the host from Dashboard \\u2192 Connect \\u2192 Session pooler.\"), mdx(\"li\", {\n    parentName: \"ul\"\n  }, mdx(\"strong\", {\n    parentName: \"li\"\n  }, \"Raw password in the URI\"), \" - encode it before building \", mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"--db-url\"), \". An unencoded \", mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"@\"), \" or \", mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"#\"), \" makes the CLI parse the wrong host.\"), mdx(\"li\", {\n    parentName: \"ul\"\n  }, mdx(\"strong\", {\n    parentName: \"li\"\n  }, \"Editing an applied file\"), \" - the remote history is the filename version. Changing SQL that already ran does not run it again, and git and production drift apart. Add a new migration.\"), mdx(\"li\", {\n    parentName: \"ul\"\n  }, mdx(\"strong\", {\n    parentName: \"li\"\n  }, \"Renaming a file after it was pushed\"), \" - the history row no longer matches, and the next push treats it as a different migration.\"), mdx(\"li\", {\n    parentName: \"ul\"\n  }, mdx(\"strong\", {\n    parentName: \"li\"\n  }, \"Dashboard SQL on production\"), \" - schema and migration history can disagree, and \", mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"db push\"), \" fails. Prefer a new migration for the intended change. Use \", mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"supabase db pull\"), \" or \", mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"supabase migration repair\"), \" when you intentionally adopt SQL that was applied outside the CLI.\"), mdx(\"li\", {\n    parentName: \"ul\"\n  }, mdx(\"strong\", {\n    parentName: \"li\"\n  }, \"Statements that cannot run in a transaction\"), \" - the CLI runs each migration file in a transaction. Leave \", mdx(\"inlineCode\", {\n    parentName: \"li\"\n  }, \"CREATE INDEX CONCURRENTLY\"), \" out of these files.\"), mdx(\"li\", {\n    parentName: \"ul\"\n  }, mdx(\"strong\", {\n    parentName: \"li\"\n  }, \"Missing \", mdx(\"inlineCode\", {\n    parentName: \"strong\"\n  }, \"--yes\")), \" - the job hangs on the confirmation prompt and then fails.\")));\n}\n;\nMDXContent.isMDXComponent = true;"}},"pageContext":{"id":"99f9ca43-351a-50c2-8af0-c4f9d5f36ba7"}},"staticQueryHashes":["1961101537","2542493696"]}