{
  "slug": "sqlite-transaction-state",
  "term": "SQLite transaction state",
  "aliases": [
    "sqlite3_txn_state",
    "SQLITE_TXN_NONE",
    "SQLITE_TXN_READ",
    "SQLITE_TXN_WRITE"
  ],
  "definition": "SQLite transaction state reports whether a named database on a connection currently has no transaction, a read transaction or a write transaction.",
  "note": "sqlite3_txn_state(D, S) reports the state of schema S. With a NULL schema argument it returns the highest state across schemas: NONE (0), READ (1) or WRITE (2). An unknown schema name returns -1. The aggregate is not an inventory of individual databases. [api] [states]\n\nAutocommit is a different signal. BEGIN DEFERRED disables autocommit before the first database access establishes a read or write transaction. Thus disabled autocommit does not by itself prove that a read snapshot exists. [autocommit] [transactions]\n\nHesela's 84-run backup study observed this distinction on two builds. BEGIN alone left the main schema at NONE between steps; BEGIN plus SELECT retained READ after backup completion or cancellation. The study did not test attached-schema aggregation. [retention]\n\nDiagnostic implication: sample the actual backup source schema and track transaction ownership and lifetime separately. A state value is not a snapshot identifier, age, checkpoint-backlog measurement or permission to roll back unrelated pooled work.",
  "related": [
    "sqlite-online-backup",
    "sqlite-wal-end-mark",
    "checkpoint-starvation",
    "snapshot"
  ],
  "citations": [
    {
      "id": "api",
      "title": "SQLite C API: Determine the transaction state of a database",
      "url": "https://sqlite.org/c3ref/txn_state.html",
      "accessed": "2026-10-21"
    },
    {
      "id": "states",
      "title": "SQLite C API: Allowed return values from sqlite3_txn_state()",
      "url": "https://sqlite.org/c3ref/c_txn_none.html",
      "accessed": "2026-10-21"
    },
    {
      "id": "autocommit",
      "title": "SQLite C API: Test For Auto-Commit Mode",
      "url": "https://sqlite.org/c3ref/get_autocommit.html",
      "accessed": "2026-10-21"
    },
    {
      "id": "transactions",
      "title": "SQLite: DEFERRED, IMMEDIATE and EXCLUSIVE transactions",
      "url": "https://sqlite.org/lang_transaction.html#deferred_immediate_and_exclusive_transactions",
      "accessed": "2026-10-21"
    },
    {
      "id": "retention",
      "title": "Hesela: source-read ownership after backup cleanup, two-build experiment and limits",
      "url": "https://hesela.com/analyses/backup-verification-is-not-a-restore-test/#sqlite-backup-retention",
      "accessed": "2026-10-21"
    }
  ],
  "status": "shipping",
  "advantages": [],
  "limitations": [
    "A per-connection state sample does not identify which other connection is retaining WAL history."
  ],
  "supersedes": [],
  "supersededBy": [],
  "firstSeen": null,
  "lastSeen": null,
  "updated": "2026-10-21"
}