# Embedded databases

Source: https://stratadb.org/docs/learn/embedded-databases

Strata runs inside your process. There is no server to start and no port to
open, and a database is a directory you point at.

[Introduction to StrataDB](/docs/learn/introduction) covers why that shape
matters. This page is what it means in practice: what the directory holds, who
may open it, and the three ways to open one.

## A database is a directory

Give Strata a path and it makes one:

```console
strata --db ./mydb kv put k v
```

Inside are the parts you would expect of a storage engine that keeps history: a
write-ahead log, snapshots, a manifest naming the current state and the branch
catalog, and a lock file recording who is using it.

You do not need to know any of that to use Strata, and you should not read those
files yourself. Rows are spread across the log, the snapshots and the tables
under MVCC, with branches and tombstones layered on top, so a file read gives
you something between incomplete and wrong. Every database says so in its own
`README.md`, written into the directory at creation, because a directory full of
opaque files is exactly the thing somebody eventually opens in an editor.

What you can do is treat the directory as a unit. Copy it, move it, archive it,
ship it. It is the database.

## One process owns it, others go through it

A durable database has a single writer. One process holds the lock, and it is
the only one touching the files.

That does not mean only one process can use the database. Host it and the others
reach it through the owner:

```console
strata --db ./mydb start
```

That blocks, holding the database open and serving a socket beside it. Other
processes then run ordinary commands against the same path and are brokered to
the owner without knowing it. `strata stop` releases it, and `strata ipc status`
reports who is currently attached.

## Three ways to open one

**Durable**, the normal case. A directory that persists:

```console
strata --db ./mydb kv get k
```

**Read-only**, when you want to be sure you cannot change anything:

```console
strata --db ./mydb --read-only kv put k v2
```

```
access_denied.executor.read_only_session: `kv_put` is a write command and
this session is read-only
```

Every write-classified command is rejected rather than attempted, so a read-only
session is a guarantee rather than an intention. Useful for handing a database to
something you have not audited, an analysis job or an agent.

**Cache**, when you want a database that never touches disk:

```console
strata --cache kv put k v
```

That database lives in the process and disappears with it. Nothing is written to
your working directory, and a second process sees nothing, because there is
nothing to see. It is the right mode for tests and for trying something out.

## What this costs you

The single-writer rule is the real constraint, and it is a deliberate one. Strata
is not a database many machines write to at once, and no amount of configuration
turns it into one. If that is what you need, you need a different kind of
database.

What you get in exchange is everything else on this page. No server to operate.
No connection pool, no network partition, no separate thing to deploy and
monitor. A database that is a directory, which is why it can be cloned from a
registry, forked in constant time, and thrown away when you are done with it.