49 lines
1.8 KiB
Markdown
49 lines
1.8 KiB
Markdown
# Bootstrap and Open Modes
|
|
|
|
When `open()` creates a brand-new database, it always writes a single bootstrap change record from the initial data object you passed to `Kanta(...)`. The simplest bootstrap is therefore the object itself — no extra code is required.
|
|
|
|
Bootstrap handlers are optional. Use them only when you need to modify the initial state at creation time, for example to seed defaults or perform expensive/external setup that should happen exactly once:
|
|
|
|
```python
|
|
kanta = Kanta("data.kantadb", Data())
|
|
|
|
@kanta.bootstrap(action="seed", user="system")
|
|
def seed_defaults(data) -> None:
|
|
data.users["admin"] = User(name="Admin")
|
|
|
|
await kanta.open()
|
|
```
|
|
|
|
You can also use `@kanta.bootstrap` with no arguments and async handlers:
|
|
|
|
```python
|
|
@kanta.bootstrap
|
|
async def bootstrap_async(data) -> None:
|
|
data.counter = 1
|
|
```
|
|
|
|
Whether or not handlers are registered, exactly one bootstrap change record is written when a new database is created. The record contains the initial object, or the state after all bootstrap handlers have run. When handlers are present:
|
|
|
|
- they run in registration order,
|
|
- bootstrap metadata (`action`, `user`, `mtime`) is taken from the last registration.
|
|
|
|
If any bootstrap handler raises, Kanta closes and removes the database file, then re-raises the error.
|
|
|
|
## Strict open mode
|
|
|
|
```python
|
|
await kanta.open(create=False)
|
|
```
|
|
|
|
With `create=False`, open fails if the database file does not exist or is empty.
|
|
|
|
## Read-only mode
|
|
|
|
Read-only mode opens an existing database without locking it or starting the background flush task. This is useful for readers that must not block the writer or modify the file:
|
|
|
|
```python
|
|
await kanta.open(readonly=True)
|
|
```
|
|
|
|
In read-only mode, records are replayed and migrations are applied in memory, but transactions and explicit flushes are rejected and the file is never created if missing.
|