Guide

Scheduled jobs

Scheduled jobs run SQL on a schedule inside your PostgreSQL database with pg_cron. Every PostgreSQL database on Layerbase Cloud has a Scheduled jobs tab on its page. From it, the database owner turns scheduling on or off, resumes it after a copy or restore, and creates and edits jobs, and anyone with access to the database sees its jobs and their run history. This page walks through the tab. Team members can create and change jobs with SQL, as described in Database lifecycle.

Requirements

Scheduled jobs need PostgreSQL 18.6, or the opt-in PostgreSQL 19.0 beta 3. When a database runs another version, the tab still opens and explains why, with Turn on scheduled jobs grayed out and a note that names the version it runs and what to do:

• An earlier PostgreSQL 18 release, such as 18.4: contact support and we will move it to 18.6 in place. Your data stays where it is and the connection string does not change. Restarting the database yourself does not change its version.
• PostgreSQL 15 to 17 cannot be moved in place. Create a new PostgreSQL 18 database and migrate into it, for example with Migrate to Layerbase.
• Another PostgreSQL 19 build: contact support to move it to 19 beta 3.

Two more notes send you to support rather than to a button. One says the database's PostgreSQL build predates scheduled jobs; the other is titled Server update required and says the database's server needs an update before scheduled jobs can be used or turned on. In both cases, contact support and we will update it.

The tab also explains itself in other states. Restore an archived or offloaded database, or start a stopped one, to see and manage its jobs. While a database is locked, its jobs cannot be read or changed until the lock is lifted (see Locked databases). pg_net is not supported, so jobs cannot make HTTP calls from the database.

Jobs run only while the database is awake

pg_cron runs inside the database, so a job runs only while its database is awake. A schedule never wakes a sleeping database, missed runs are not replayed after it wakes, and a running job does not count as activity that keeps the database awake. A Free database sleeps after 15 idle minutes. A database on the Solo or Pro plan sleeps after 6 idle hours unless it is pinned always-on (Settings > Availability > Always on, see the always-on pool). Databases on a dedicated server do not sleep. When a database can sleep, the tab says so: keep it always on if its jobs must run on time.

Opening the tab never wakes the database either. While it sleeps, the tab shows This database is asleep, usually says whether scheduled jobs are turned on, and offers a Wake database button. Waking is always a step you take yourself: the job list and run history load once the database is awake. The turn on, turn off and resume dialogs show the same wake step while the database sleeps.

Turn scheduled jobs on or off

Only the database owner can turn scheduled jobs on or off, or resume scheduling. Team members see the same buttons grayed out with the reason. Scheduling is opt-in for each database: starting or waking a database never turns it on.

1. Open the database's page and choose the Scheduled jobs tab.
2. Click Turn on scheduled jobs, or Turn off scheduled jobs when they are on.
3. If the database is asleep, the dialog shows a Wake the database first step. Click Wake database; nothing changes until you do.
4. Check I understand the database restarts and open connections drop, then confirm with Restart and turn on or Restart and turn off.

Each change restarts the database once. It is unavailable for a short time, and open connections drop and reconnect, so choose a suitable time. Turning scheduled jobs off keeps your jobs and their run history; nothing runs while they are off, and turning them back on brings back the same jobs. The SQL opt-in on the Database lifecycle page does the same by hand.

When a change cannot be completed

If a change fails partway through, Layerbase puts the database back the way it was and the dialog says so:

The message names the action you tried. In the rare case that putting the database back also fails, the message says the database may not start and that our team has been alerted; contact support. If a change takes longer than expected, the dialog shows Still working on it: refresh the tab in a minute to see where it landed before trying again. A change is also refused while another operation is running on the database or account; try again in a minute.

Resume after a copy, restore or import

Copying, branching, resetting or restoring a database, and importing a dump that contains jobs, leaves its scheduler paused, so the same jobs never run in two places at once. Job definitions are kept. The tab shows The scheduler is paused with a Resume scheduling button.

Before resuming, review the jobs. The resume dialog lists every active job, with its schedule, the database it runs in and its command, because each one starts running on its next schedule. Jobs imported from another database can still name that source database; retarget them first, as Copies, restores, and imports pause jobs describes. Resuming does not restart the database. If you see Resume saved. Jobs start running after the database next restarts, the resume is stored and takes effect on the next restart.

A branch can instead start with scheduled jobs turned off altogether, shown as Scheduling is off on this branch. Turn scheduled jobs on first (one restart), review the jobs, then resume scheduling.

Jobs and run history

With scheduled jobs on and the database awake, the tab lists every job with its name and id, schedule, command, target database, and whether it is Active or Paused. The count above the table names the database whose catalog holds the jobs.

Run history below the table shows runs newest first: status, job, start and end time, duration, and the return message. Pick a job in the filter, or click Runs on its row, to see only that job's history. Runs load in pages; click Load more for older ones. Long output is cut to its first 16,384 characters, with a note under it such as Truncated, 48 KB total giving the full size. Layerbase keeps completed runs for up to seven days or the latest 10,000, whichever is smaller.

Create and edit jobs

The database owner creates jobs with New job at the top of the tab. Team members see it grayed out with the reason. Scheduled jobs must be turned on first, and a sleeping database shows a Wake database step in the dialog before anything is saved.

1. Optionally start from a template. Each fills in the name, schedule and command, with fields for the parts that change: Refresh a materialized view (REFRESH MATERIALIZED VIEW CONCURRENTLY, which needs a unique index on the view), Delete rows older than N days, and VACUUM ANALYZE on one table or the whole database.
2. Name the job. Names are unique, so a name already in use is refused.
3. Pick a schedule preset or enter a five-field cron expression (in UTC) or an interval such as 10 seconds. The line under it says in words when the job runs. pg_cron checks the schedule when you save, and its message shows under the field if it refuses.
4. Write the SQL command. A command that deletes rows, including the Delete rows template, shows a warning and asks you to confirm that it permanently deletes rows on every run before it can be saved.
5. Leave the target database empty to run the job in the app database, or name any other database in the same cluster.

Each job's row has Edit, Pause or Resume, and Delete for the owner. Editing keeps the job's id and run history. Deleting names the job and asks you to confirm; its runs stay in the history, labeled as a deleted job, until they age out. If the tab cannot confirm a change, it says so and refreshes the job list rather than trying again, so check the list before repeating it.

Team members, and anyone who prefers SQL, can manage jobs with SELECT cron.schedule('job-name', '*/5 * * * *', $$ ... $$); and remove one with cron.unschedule. The pg_cron section of Database lifecycle covers the SQL, testing a schedule, and keeping jobs in your ORM migrations. Refresh the tab to see a job made with SQL.