db.backup
=========

.. py:module:: db.backup

.. autoapi-nested-parse::

   SQLite backup/export/restore helpers for the webapp database.

   These utilities provide safe, deterministic file-level operations for the
   webapp SQLite database. They intentionally avoid HTTP concerns and focus on
   filesystem + SQLite behavior only.



Classes
-------

.. autoapisummary::

   db.backup.BackupResult
   db.backup.RestoreResult


Functions
---------

.. autoapisummary::

   db.backup.backup_database
   db.backup.export_database
   db.backup.restore_database


Module Contents
---------------

.. py:class:: BackupResult

   Summary metadata returned after a backup or export.


   .. py:attribute:: path
      :type:  pathlib.Path


   .. py:attribute:: bytes_written
      :type:  int


   .. py:attribute:: sha256
      :type:  str


   .. py:attribute:: created_at
      :type:  str


.. py:class:: RestoreResult

   Summary metadata returned after a restore/import operation.


   .. py:attribute:: restored_path
      :type:  pathlib.Path


   .. py:attribute:: bytes_written
      :type:  int


   .. py:attribute:: sha256
      :type:  str


   .. py:attribute:: created_at
      :type:  str


   .. py:attribute:: backup_path
      :type:  pathlib.Path | None
      :value: None



.. py:function:: backup_database(db_path, *, output_path = None, overwrite = False)

   Create a point-in-time backup of the webapp database.

   :param db_path: Source SQLite database to back up.
   :param output_path: Optional destination file. When omitted, a timestamped
                       sibling file is created next to ``db_path``.
   :param overwrite: When ``True``, allow replacing an existing file.

   :returns: ``BackupResult`` with the path and content hash of the backup.


.. py:function:: export_database(db_path, *, output_path, overwrite = False)

   Export the database to a file path.

   This is a convenience wrapper over :func:`backup_database` that keeps the
   naming explicit for API users.


.. py:function:: restore_database(db_path, *, import_path, overwrite = False, create_backup = True, backup_path = None)

   Restore the webapp database from an existing SQLite file.

   :param db_path: Destination database path used by the webapp.
   :param import_path: Existing SQLite file to restore from.
   :param overwrite: When ``True``, allow replacing an existing destination DB.
   :param create_backup: When ``True`` and the destination exists, create a
                         timestamped backup first.
   :param backup_path: Optional explicit backup path used when ``create_backup``
                       is enabled.

   :returns: ``RestoreResult`` with the restored DB path and optional backup path.