/supabase-keep-alive and /supabase-keep-alive.yml were down for ~8.5h (02:47Z-11:24Z deploy from the wrong branch) when the last README pass dropped their links; re-verified both 200 now. Point the top-of-README CTA and the babysit-section link at the specific page instead of the bare homepage, and add a one-line "Move off Supabase free-tier pauses: Scribase" CTA near the top. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Supabase keep-alive
Supabase pauses a Free project after about 7 days without database activity. This repository stops that: once a day it makes one real database read through your project's REST API, so the project never looks idle. One workflow file, plain bash and curl, nothing to install or update.
If your project is already paused, restore it first; a workflow cannot unpause it.
Want the workflow with a copy button, no git clone? It's live at
scribase.com/supabase-keep-alive
(raw file: scribase.com/supabase-keep-alive.yml).
Move off Supabase free-tier pauses entirely: Scribase — Postgres that scales to zero and wakes on request instead of pausing, first project free forever.
| You want | Use | Needs |
|---|---|---|
| The fastest fix | The workflow below | A GitHub repository |
| Warnings before a pause can happen | The full script | A GitHub repository |
| No GitHub at all | cron on any machine | A server, Pi or NAS |
| A one-off check from your laptop | The CLI | Node 18+ |
| To stop babysitting it | A backend that does not pause | Nothing |
Set it up in three steps
1. Create a tiny table for the ping to read. Run this once in the Supabase SQL editor. Row
Level Security is on and there is no policy for anon, so the read returns [] and exposes
nothing, but it is still a real query.
create table if not exists keepalive (
id bigint generated always as identity primary key,
created_at timestamptz not null default now()
);
alter table keepalive enable row level security;
grant select on keepalive to anon;
2. Add two repository secrets under Settings, Secrets and variables, Actions:
SUPABASE_URL (like https://abcdefgh.supabase.co) and SUPABASE_ANON_KEY (Project Settings,
API, anon public key).
3. Save this file as .github/workflows/keep-alive.yml, then run it once from the Actions tab
(Run workflow) and read the job summary.
# .github/workflows/keep-alive.yml
# Keeps a free Supabase project from pausing: one real database read a day through the REST API.
# Repository secrets: SUPABASE_URL (https://<ref>.supabase.co) and SUPABASE_ANON_KEY (anon public key).
# No marketplace action, nothing to update: plain bash and curl.
name: Keep Supabase alive
on:
schedule:
- cron: "17 6 * * *" # daily, 06:17 UTC; avoid :00, GitHub's busiest minute
workflow_dispatch: # lets you run it by hand from the Actions tab
permissions: {}
jobs:
ping:
runs-on: ubuntu-latest
steps:
- name: Read one row through the REST API
env:
SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
SUPABASE_ANON_KEY: ${{ secrets.SUPABASE_ANON_KEY }}
TABLE: keepalive # any small table; RLS with no anon policy is fine, the read returns []
run: |
set -u
url="${SUPABASE_URL%/}"
host="${url#*://}"
path="/rest/v1/${TABLE}?select=*&limit=1"
attempt=0
delay=2
while :; do
attempt=$((attempt + 1))
code=$(curl -sS -o body.txt -w '%{http_code}' --max-time 20 \
-H "apikey: $SUPABASE_ANON_KEY" \
-H "Authorization: Bearer $SUPABASE_ANON_KEY" \
-H "Accept: application/json" \
"$url$path") || code=000
echo "GET $path -> HTTP $code (attempt $attempt)"
case "$code" in
540) break ;; # paused: retrying cannot help
000|429|5[0-9][0-9]) # network error, rate limit, server error: retry
if [ "$attempt" -le 3 ]; then
echo " transient, retrying in ${delay}s"
sleep "$delay"
delay=$((delay * 2))
continue
fi
;;
esac
break
done
case "$code" in
2*) title="ok" ;;
540) title="project is PAUSED" ;;
*) title="failed" ;;
esac
{
echo "## Supabase keep-alive: $title"
echo
echo "Project: \`$host\` "
echo "Time: $(date -u +'%Y-%m-%d %H:%M:%S UTC') "
echo "Request: \`GET $path\` -> HTTP $code after $attempt attempt(s)"
if [ "$code" = "540" ]; then
echo
echo "Restore it in the Supabase dashboard: open the project and click **Restore project**. Free projects can be restored for one year after pausing."
fi
} >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
case "$code" in
2*)
echo "ok: $host answered, the project is awake"
exit 0 ;;
540)
echo "::error::$host answered HTTP 540: the project is paused. Restore it in the Supabase dashboard (Restore project); a workflow cannot unpause it."
exit 1 ;;
401|403)
echo "::error::anon key rejected by $host (HTTP $code). Check that SUPABASE_ANON_KEY belongs to this project."
exit 1 ;;
404)
echo "::error::table '$TABLE' not found through the REST API (HTTP 404). Create it (SQL in the README) or change TABLE."
exit 1 ;;
000)
echo "::error::could not reach $host (DNS, TLS or timeout after $attempt attempts). Check SUPABASE_URL."
exit 1 ;;
*)
echo "::error::$host answered HTTP $code: $(tr -d '\n' < body.txt | cut -c1-200)"
exit 1 ;;
esac
That is the whole setup. The workflow is self-contained: no uses: line and nothing fetched from
this repository, so nothing here can break it later. It retries on network errors, 429 and 5xx
(2s, 4s, 8s), treats an already-paused project (HTTP 540) as a clear failure instead of retrying,
and writes a job summary. The same file is at examples/keep-alive.yml
(raw).
What a run prints:
GET /rest/v1/keepalive?select=*&limit=1 -> HTTP 200 (attempt 1)
ok: abcdefgh.supabase.co answered, the project is awake
and when the project is already paused:
GET /rest/v1/keepalive?select=*&limit=1 -> HTTP 540 (attempt 1)
::error::abcdefgh.supabase.co answered HTTP 540: the project is paused. Restore it in the Supabase dashboard (Restore project); a workflow cannot unpause it.
The full script, with early warnings
Most hand-rolled keep-alive workflows fail silently: the cron is weekly and one run is skipped, or
GitHub turns the schedule off. keepalive.sh does the same ping and also warns,
as workflow annotations and in the job summary, when:
- the previous successful run is older than 5 days (
INPUT_WARN_AFTER_DAYS); - the cron in your workflow is weekly or monthly, which leaves no margin inside 7 days;
- the repository has had no push for 45+ days. "In a public repository, scheduled workflows are automatically disabled when no repository activity has occurred in 60 days" (GitHub docs).
Copy the script into your own repository once, so the job depends on nothing outside it:
mkdir -p .github
curl -fsSL -o .github/keepalive.sh \
https://git.ereboslab.com/caelum0x/supabase-keep-alive-action/raw/tag/v1/keepalive.sh
git add .github/keepalive.sh && git commit -m "add supabase keep-alive script"
Then use examples/full-checks.yml as the workflow. Its core is:
permissions:
contents: read
actions: read # lets the script read this workflow's previous runs
jobs:
ping:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Keep-alive ping
env:
INPUT_URL: ${{ secrets.SUPABASE_URL }}
INPUT_ANON_KEY: ${{ secrets.SUPABASE_ANON_KEY }}
INPUT_TABLE: keepalive # or INPUT_RPC: keepalive_ping
INPUT_GITHUB_TOKEN: ${{ github.token }}
run: bash .github/keepalive.sh
Several projects from one repository: examples/multi-project.yml (a matrix, one pair of secrets per project).
Each run does, in order: GET /rest/v1/ (catches a paused project and a wrong key), then the
table read or rpc call (the real database query), with retries, then the warnings, then a summary
table of check, request, HTTP status, latency and attempts.
Settings
All settings are environment variables. Only the first two are required.
| Variable | Default | What it does |
|---|---|---|
INPUT_URL |
Project origin, https://<ref>.supabase.co. |
|
INPUT_ANON_KEY |
Anon public key. Masked in GitHub Actions logs. | |
INPUT_TABLE |
Table to read with select=<select>&limit=1. |
|
INPUT_SELECT |
* |
Columns for the table read. |
INPUT_RPC |
Function to call with POST /rest/v1/rpc/<name>. |
|
INPUT_RPC_BODY |
{} |
JSON body for the rpc call. |
INPUT_RETRIES |
3 |
Retries per request after the first attempt. |
INPUT_TIMEOUT |
20 |
Per-request timeout, seconds. |
INPUT_WARN_AFTER_DAYS |
5 |
Warn when the last successful run is older than this. |
INPUT_FAIL_ON_PAUSED |
true |
Exit 1 on HTTP 540. false only warns. |
INPUT_GITHUB_TOKEN |
Reads previous runs, the cron and the last push date for the warnings. Leave empty to skip them. |
If you set neither a table nor an rpc, the script still pings the REST root and succeeds, but prints a warning, because the root endpoint alone may not count as database activity.
A function instead of a table, if you would rather touch no table at all:
create or replace function keepalive_ping() returns text
language sql stable as $$ select 'ok ' || now()::text $$;
grant execute on function keepalive_ping() to anon;
and set INPUT_RPC: keepalive_ping instead of INPUT_TABLE.
Without GitHub: cron on any machine
GitHub schedules are best effort and stop after 60 quiet days. A machine you control has neither problem. examples/cron.sh wraps the same script for crontab:
mkdir -p ~/supabase-keep-alive && cd ~/supabase-keep-alive
curl -fsSL -O https://git.ereboslab.com/caelum0x/supabase-keep-alive-action/raw/tag/v1/keepalive.sh
curl -fsSL -O https://git.ereboslab.com/caelum0x/supabase-keep-alive-action/raw/tag/v1/examples/cron.sh
chmod 700 cron.sh
printf 'SUPABASE_URL=https://YOUR-REF.supabase.co\nSUPABASE_ANON_KEY=YOUR-ANON-KEY\n' > .env
chmod 600 .env
./cron.sh # try it once
Then one line in crontab -e:
17 6 * * * $HOME/supabase-keep-alive/cron.sh >> $HOME/supabase-keep-alive/keepalive.log 2>&1
The smallest thing that works, with no script at all:
curl -s -o /dev/null -w '%{http_code}\n' --max-time 20 \
-H "apikey: $SUPABASE_ANON_KEY" -H "Authorization: Bearer $SUPABASE_ANON_KEY" \
"$SUPABASE_URL/rest/v1/keepalive?select=*&limit=1"
# 200 = awake, 540 = paused
(examples/curl-only.yml is that call as a GitHub Actions workflow.)
One-off check from a terminal
A small Node CLI (Node 18+, no dependencies) makes the same requests and exits 0 or 1:
npx --yes git+https://git.ereboslab.com/caelum0x/supabase-keep-alive-action.git \
--url https://YOUR-REF.supabase.co --key YOUR-ANON-KEY --table keepalive
GET /rest/v1/ -> HTTP 200 (212ms, attempt 1)
GET /rest/v1/keepalive?select=*&limit=1 -> HTTP 200 (87ms, attempt 1)
ok: project is awake.
Options are in cli/README.md.
Why Supabase pauses free projects
Supabase's pricing page states it plainly: "Free projects are paused after 1 week of inactivity" and the Free plan has a "Limit of 2 active projects" (pricing). The production checklist says the same thing with a little more nuance: "We may pause applications on the Free Plan that exhibit low activity in a 7-day period to save on server resources" (going into production).
What counts as activity, per the official FAQ: "Opening the project in the dashboard or sending real requests from your app both count as activity", and "You get an email about a week before a pause, and another once it happens" (Do Supabase projects pause when they're inactive?). Supabase does not publish the exact threshold, and community reports disagree on whether direct Postgres connections (connection string, pooler) count. Requests through the project's API that touch the database are the documented path, which is what this action makes.
Paid plans are never paused for inactivity: "Upgrade to Pro to guarantee that we won't pause your project for inactivity" (same production checklist).
How to tell if your project is paused
A paused project answers every API request with HTTP 540. From Supabase's status code reference: "The project the request was being made against has been paused. The project cannot process requests until it is un-paused by the owner" (HTTP status codes).
curl -s -o /dev/null -w '%{http_code}\n' \
-H "apikey: $SUPABASE_ANON_KEY" "https://YOUR-REF.supabase.co/rest/v1/"
# 200 = awake, 540 = paused
In a browser the symptom is usually a bare network error, because the paused gateway answers without CORS headers, so your app reports "Failed to fetch" or "Load failed" instead of 540.
How to restore a paused project
-
Open the project in the Supabase dashboard and click Restore project. It takes a few minutes. "A paused project keeps all of its data and settings" (FAQ above).
-
You need a free slot: the Free plan allows 2 active projects. Paused projects do not count towards that limit, so if two others are running, pause one first.
-
Do not wait too long. "When a project is paused, users have a 1-year window to restore the project on the platform from within Supabase Studio. [...] After the restore window, you can download your project's backup file, and Storage objects from the project dashboard" (upgrading docs). The dashboard shows a countdown on paused projects.
You may read elsewhere that paused projects are deleted after 90 days. As of 2026-11-12 the docs linked above say one year for one-click restore, with a downloadable backup after that. Check the current docs before relying on either number.
-
A restored project is paused again if the next 7 days are quiet. Add the workflow above the same day you restore.
Limits, honestly
- It works around the Free plan's intent. Supabase pauses idle projects "to save on server resources". A keep-alive makes a project look busier than it is. Supabase has not, to our knowledge, forbidden this, but their only documented guarantee is a paid plan.
- No guarantee. Supabase does not publish a precise activity threshold and may change how it measures it. One request a day through the REST API is the common, working practice; it is not a contract. Several people have reported pauses despite steady pings.
- GitHub schedules are best effort. Cron runs "can be delayed during periods of high loads", only run on the default branch, and are disabled after 60 days without a push to a public repo. A weekly cron plus one delayed run can miss the window, which is why the full script warns on weekly schedules and old last-success dates. Run it daily.
- It cannot unpause. Once a project is paused, only the dashboard can restore it; the script reports 540 and fails so you notice.
- pg_cron inside the database cannot do this job. When the project pauses, Postgres is not running, so nothing inside it can wake it.
- The anon key is public by design (it ships in your frontend), but it still belongs in a secret, not in the workflow file, so it is masked and not indexed.
If you would rather not babysit it
A keep-alive exists because a free project nobody touches for a week is turned off and has to be turned back on by hand. Scribase is a backend built around the opposite behaviour: each project is Postgres, Auth, Storage and Realtime, and an idle project scales to zero on its own and wakes on the next request. There is nothing to keep alive and nothing to restore.
- Existing supabase-js code works by swapping the URL and keys.
- The first project is free with no time limit and no card (0.5 GB database, 1 GB files).
- Paid projects start at $5 per project per month.
The script in this repository speaks plain PostgREST (/rest/v1/ with an apikey header), so it
runs unchanged against a Scribase project too; you just will not need it there. More on the pause
itself: Supabase project paused: why, and how to get it back.
Supabase's free plan is generous and this repository is for people who want to stay on it. The section above is for the ones who would rather stop thinking about it.
Compared with other approaches
- Vercel cron + Next.js route (for example
travisvn/supabase-pause-prevention): works well if you already deploy to Vercel. You need a deployed app and the Hobby plan limits cron jobs. - A Python or Node script run by Actions (for example
travisvn/supabase-inactive-fix): inserts and deletes rows in a table. Flexible, but you maintain a runtime and dependencies, and it writes to your database. - This repository: read-only queries, no runtime, retries, a job summary and the pre-pause
warnings. If you want write activity, point
INPUT_RPCat a function that does an insert.
How this was checked
Every path in this README was run before release 1.1.0 (2026-11-17): the workflow's run: block,
keepalive.sh, examples/cron.sh and the CLI, each against an HTTP endpoint answering the way
Supabase's REST API does for an awake project (200), a paused one (540), a wrong key (401), a
missing table (404), a server error that recovers (503, 503, 200) and an unreachable host. The
workflow files pass actionlint. Version 1.0.0 of the script also ran in GitHub Actions against
a live PostgREST project (table read and rpc call, both HTTP 200).
action.yml is a composite-action wrapper around keepalive.sh for a GitHub mirror of this
repository. GitHub Actions can only resolve uses: lines from github.com, so the instructions
above do not depend on it.
License
MIT. Not affiliated with Supabase. Issues and fixes are welcome at https://git.ereboslab.com/caelum0x/supabase-keep-alive-action.