database.h

Go to the documentation of this file.

/*
    This file is part of darktable,
    Copyright (C) 2010-2011 Henrik Andersson.
    Copyright (C) 2010 johannes hanika.
    Copyright (C) 2011-2012 Edouard Gomez.
    Copyright (C) 2012 Richard Wonka.
    Copyright (C) 2013-2017 Tobias Ellinghaus.
    Copyright (C) 2019 Edgardo Hoszowski.
    Copyright (C) 2020 Hubert Kowalski.
    Copyright (C) 2020, 2022 Pascal Obry.
    Copyright (C) 2022 Martin Bařinka.
    Copyright (C) 2025 Alynx Zhou.
    Copyright (C) 2025-2026 Aurélien PIERRE.
    Copyright (C) 2025 Guillaume Stutin.
    
    darktable is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
    
    darktable is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
    
    You should have received a copy of the GNU General Public License
    along with darktable.  If not, see <http://www.gnu.org/licenses/>.
*/
 
#ifndef DT_DATABASE_DATABASE_H
#define DT_DATABASE_DATABASE_H
 
/* DT_DEBUG_TRACE_WRAPPER, used by the transaction macros at the bottom of this file. It
 * used to arrive the other way round -- common/debug.h included this header, so anything
 * that reached here through it already had the wrapper. */
#include "common/debug.h"
 
#include <glib.h>
#include <sqlite3.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ---------------------------------------------------------------------------------------
 *  Lifecycle
 *
 *  There is exactly one connection, and the module owns it. `dt_database_t` used to be an
 *  opaque struct the caller held and passed back into all 20 functions below -- but every
 *  caller filled that argument with `dt_database_get_global()`, the module's own accessor,
 *  so it was never a parameter anybody chose. It is gone, along with the accessor and the
 *  entry on `darktable_t`.
 * ------------------------------------------------------------------------------------- */
 
typedef struct dt_database_params_t
{
  const char *alternative;
  const char *library;
  gboolean load_data;
  gboolean has_gui;
  gboolean verbose;
} dt_database_params_t;
 
typedef enum dt_database_open_result_t
{
  DT_DATABASE_OPEN_FAILED = 0,
  DT_DATABASE_OPEN_OK,
  DT_DATABASE_OPEN_LOCKED
} dt_database_open_result_t;
 
dt_database_open_result_t dt_database_open(const dt_database_params_t *params);
 
void dt_database_close(void);
 
gboolean dt_database_is_open(void);
 
const gchar *dt_database_get_path(void);
 
sqlite3 *dt_database_get_sqlite3_global(void);
 
const char *dt_database_get_last_error(void);
 
/* ---------------------------------------------------------------------------------------
 *  Maintenance and snapshot policy
 *
 *  User preferences, read from conf by the orchestrator and told to the module -- the same
 *  arrangement as `dt_mipmap_cache_settings_t`. They used to be read with `dt_conf_*` from
 *  five places inside the maintenance and snapshot paths, which put `common/conf.h` in the
 *  SQL layer and made "when does this take effect" a question you answered by reading
 *  call sites.
 * ------------------------------------------------------------------------------------- */
 
typedef struct dt_database_settings_t
{
  char *maintenance_check;
  int maintenance_freepage_ratio;
  char *create_snapshot;
  int keep_snapshots;
} dt_database_settings_t;
 
void dt_database_set_settings(const dt_database_settings_t *settings);
 
void dt_database_get_settings(dt_database_settings_t *settings);
 
void dt_database_settings_free(dt_database_settings_t *settings);
 
typedef void (*dt_database_renamed_handler_t)(const char *new_library_name);
void dt_database_set_renamed_handler(dt_database_renamed_handler_t handler);
 
/* Why the database would not open, handed to whoever can report it.
 *
 * Reporting used to live here as dt_database_show_error(), a stack of modal dialogs inside
 * a SQL file. The backend now only says what went wrong; the dialogs, and the decision to
 * retry or delete lock files, are gui/common/database_gui.c's business. */
typedef struct dt_database_error_t
{
  gboolean lock_acquired; 
  int other_pid;          
  char *message;          
  char *dbfilename;       
} dt_database_error_t;
 
void dt_database_take_error(dt_database_error_t *error);
 
void dt_database_error_free(dt_database_error_t *error);
 
/* Questions the module must ask before it can continue.
 *
 * These are NOT the dt_database_error_t path above. That one records what went wrong for
 * whoever can report it afterwards; these happen mid-operation and the answer decides
 * whether init aborts, restores from a snapshot, starts over, or spends a minute
 * vacuuming -- there is no "afterwards" to report to. So the backend states the question
 * and takes back a value, and every trace of how it is put to the user lives in
 * gui/common/database_gui.c.
 *
 * The module passes FACTS, never prose. Composing a sentence -- and translating it, and
 * escaping it into markup -- is the handler's business, because only the handler knows
 * what it will be rendered into.
 */
typedef enum dt_database_prompt_t
{
  DT_DATABASE_PROMPT_READONLY = 0,
  DT_DATABASE_PROMPT_CORRUPTED,
  DT_DATABASE_PROMPT_UPGRADE,
  DT_DATABASE_PROMPT_MAINTENANCE
} dt_database_prompt_t;
 
typedef enum dt_database_response_t
{
  DT_DATABASE_RESPONSE_CLOSE = 0,
  DT_DATABASE_RESPONSE_RESTORE,
  DT_DATABASE_RESPONSE_DELETE,
  DT_DATABASE_RESPONSE_PROCEED
} dt_database_response_t;
 
typedef struct dt_database_prompt_context_t
{
  dt_database_prompt_t prompt;
  const char *dbfilename;
  const char *quick_check;
  gboolean snapshot_available;
  guint64 reclaimable_bytes;
  gboolean at_close;
  gboolean ask_on_startup;
  gboolean ask_on_close;
} dt_database_prompt_context_t;
 
typedef dt_database_response_t (*dt_database_prompt_handler_t)(const dt_database_prompt_context_t *context);
 
void dt_database_set_prompt_handler(dt_database_prompt_handler_t handler);
 
int dt_database_delete_lock_files(const char *dbfilename);
void dt_database_optimize(void);
gboolean dt_database_maybe_maintenance(const gboolean closing_time);
void dt_database_perform_maintenance(void);
void dt_database_cleanup_busy_statements(void);
gboolean dt_database_snapshot(void);
gboolean dt_database_maybe_snapshot(void);
char **dt_database_snaps_to_remove(void);
gchar *dt_database_get_most_recent_snap(const char* db_filename);
 
 
/* Nested transactions.
 *
 * These took a `const dt_database_t *` that all 50 call sites filled with
 * dt_database_get_global(). They do not any more, and that accessor is gone with them. */
void dt_database_start_transaction_debug(void);
void dt_database_release_transaction_debug(void);
void dt_database_rollback_transaction(void);
void dt_database_begin_transaction_batch(void);
void dt_database_end_transaction_batch(void);
 
#define dt_database_start_transaction() DT_DEBUG_TRACE_WRAPPER_VOID(DT_DEBUG_SQL, dt_database_start_transaction_debug)
#define dt_database_release_transaction() DT_DEBUG_TRACE_WRAPPER_VOID(DT_DEBUG_SQL, dt_database_release_transaction_debug)
 
#ifdef __cplusplus
}
#endif
 
#endif // DT_DATABASE_DATABASE_H
 
// clang-format off
// modelines: These editor modelines have been set for all relevant files by tools/update_modelines.py
// vim: shiftwidth=2 expandtab tabstop=2 cindent
// kate: tab-indents: off; indent-width 2; replace-tabs on; indent-mode cstyle; remove-trailing-spaces modified;
// clang-format on