{% extends "admin/dbs/wiki/_layout.html" %}

{% block wiki %}
<h1>Scheduled backups</h1>
<p>Open <a href="{% url 'admin:dbs_backupschedule_changelist' %}">Schedule</a>, tick
<em>enabled</em>, and choose how often (<code>30m</code>, <code>6h</code>, <code>1d</code>)
and how many backups to keep in <code>DBS_BACKUP_DIR</code>. Backups stay on this server;
the <a href="{% url 'admin:dbs_wiki' 'manager' %}">DBS manager</a> takes the off-site copies
by connecting to this server and pulling them.</p>
<p>The schedule runs inside your web workers. Each worker starts a small background thread
on the first request it serves, and the thread checks once a minute whether a backup is
due. A lease in the database lets exactly one of them take each backup, and only one backup
or restore runs at a time. The lease lasts two minutes and is renewed while the backup runs,
so a long backup is never started twice. If a worker dies mid-backup, its audit row is marked
interrupted and the next tick takes the backup again; if that one dies too, the schedule
waits for the next interval.</p>
<h2>Choosing where it runs</h2>
<ul>
  <li><code>DBS_SCHEDULER = "thread"</code> (default): inside the web workers.</li>
  <li><code>DBS_SCHEDULER = "command"</code>: run <code>python manage.py dbs schedule</code>
      under systemd. It follows the same panel setting. Use it behind uWSGI without
      <code>--enable-threads</code>, or when several hosts each keep their own
      <code>DBS_BACKUP_DIR</code>.</li>
  <li><code>DBS_SCHEDULER = "off"</code>: no scheduled backups from this project.</li>
</ul>
<p><a href="{% url 'admin:dbs_health' %}">Health</a> shows when the scheduler last checked in
and whether the last backup is on time.</p>
<h2>What is kept</h2>
<p>The server keeps at most five backups in <code>DBS_BACKUP_DIR</code>; the schedule keeps
between one and five. After each backup, retention removes the oldest of this project's
backups beyond that number, and only those:</p>
<ul>
  <li>It only touches files named for this project and database:
      <code>backup-YYYYMMDD-HHMMSSZ.dbs</code> for the <code>default</code> database and
      <code>backup-ALIAS-YYYYMMDD-HHMMSSZ.dbs</code> for any other, with
      <code>DBS_BACKUP_PREFIX</code> in place of <code>backup</code>. Two backups taken in the
      same second get <code>-2</code>, <code>-3</code> and so on.</li>
  <li>Backups are ordered by the time recorded when they were taken, then the time written
      inside the file, and only then the name.</li>
  <li>A file whose name carries a time in the future, a link, or a file that is not a DBS
      backup is never counted and never removed.</li>
  <li>A backup that failed verification never takes one of the places, and the newest backup
      that passed verification is always kept.</li>
</ul>
<p>Unfinished temporary files older than an hour are cleared from the folder.</p>
<h2>A fixed plan from the command line</h2>
<p>Flags still run their own plan, ignoring the panel:</p>
<pre><code>python manage.py dbs schedule --interval 6h --output-dir /var/backups --keep 5</code></pre>
<p><code>SIGTERM</code> stops the loop at once, and <code>--once</code> runs a single cycle
from cron. <code>DBS_SCHEDULE_INTERVAL</code> and <code>DBS_SCHEDULE_KEEP</code> seed the
panel's first schedule and supply the defaults for these flags.</p>
{% endblock %}