From 4c36bacf913a6f354429554acd206ae1c26bbe33 Mon Sep 17 00:00:00 2001 From: jasper blues Date: Sun, 8 Nov 2026 12:12:53 +1000 Subject: [PATCH] Move the README's SQLite section into Connecting, as the other two READMEs keep no store's section --- README.md | 18 ++---------------- docs/02-connecting.md | 8 +++++--- 2 files changed, 7 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 35452d8..7348d70 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,8 @@ pip install "drivine[postgres]" # Postgres 14 or later, through psycopg 3 pip install drivine # SQLite 3.45 or later, a graph in a file, through Python's own sqlite3 ``` -Python 3.11 or newer. +Python 3.11 or newer. A SQLite store and what a transaction gives there are in +[Connecting](docs/02-connecting.md#sqlite). ## Quick start @@ -68,21 +69,6 @@ asyncio.run(main()) Views that compose fragments and relationships, queries, transactions, schema and the sync API are in the [full quick start](https://drivine.org/py/quick-start/) and the pages after it. -## SQLite - -A graph in a file, with no server: `DATABASE_TYPE=SQLITE`, and `DATABASE_NAME` the file's path. The file holds -drivine4j's tables, so drivine4j and Drivine for TypeScript read and write it too. What a transaction gives there: - -- One writer at a time: a transaction takes the file's write lock as it begins, so even one that only reads waits for - the lock, for up to the busy timeout (30 seconds). One that holds it longer than 5 seconds is logged as a warning. -- Reads outside a transaction don't wait for a writer. -- Saves and deletes outside a transaction are run again when SQLite turns them away as contended. -- Each statement Drivine writes applies whole or not at all. -- A connection you open yourself, with `sqlite3.connect`, gets none of this. - -Cypher you write is compiled to SQLite's SQL (`pip install "drivine[sqlite]"`): see -[Cypher on a relational database](docs/03-cypher-on-a-relational-database.md). - ## Documentation - [drivine.org/py](https://drivine.org/py/): the full documentation. diff --git a/docs/02-connecting.md b/docs/02-connecting.md index 7648bd0..5f9f8ec 100644 --- a/docs/02-connecting.md +++ b/docs/02-connecting.md @@ -211,10 +211,12 @@ for up to its busy timeout, 30 seconds by default. transaction that only reads waits for the lock, for up to the busy timeout. One that holds it longer than 5 seconds is logged as a warning when it ends, committed, rolled back or released. - Reads outside a transaction don't wait for a writer: each reads the file as it last was. -- Saves and deletes outside a transaction are run again when SQLite turns them away as contended (`SQLITE_BUSY`). +- Saves, patches and deletes outside a transaction are run again when SQLite turns them away as contended + (`SQLITE_BUSY`). - Each statement Drivine writes applies whole or not at all. -- A connection you open yourself, with `sqlite3.connect`, has none of this: no log, no foreign keys, no busy timeout - and none of Drivine's functions. +- A connection you open yourself, with `sqlite3.connect`, has none of this: no foreign keys, no write lock taken as a + transaction begins, no warning, Python's wait of 5 seconds for a locked file rather than 30, and none of Drivine's + functions. It does write ahead to the log, as the file keeps that mode once Drivine has set it. Drivine reads `os.environ`, and doesn't load `.env` files itself: use python-dotenv, pydantic-settings, or your platform's way.