Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 2 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.
Expand Down
8 changes: 5 additions & 3 deletions docs/02-connecting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Loading