Local Overlay Store: Upper Layer Components, SQLite Database, and Filesystem Layout Example

But combined with everything else as part of an overlay local store, it is valid. - **Upper layer directory**: > Specified with [`upper-layer`](#store-experimental-local-overlay-store-upper-layer) setting. This contains additional [store objects][store object] (or, strictly speaking, their [file system objects][file system object] that the local overlay store will extend the lower store with). - **Upper store directory**: > Specified with the [`real`](#store-experimental-local-overlay-store-real) setting. > This the same as the base local store setting, and can also be indirectly specified with the [`root`](#store-experimental-local-overlay-store-root) setting. This contains all the store objects from each of the two directories. The lower store directory and upper layer directory are combined via OverlayFS to create this directory. Nix doesn't do this itself, because it typically wouldn't have the permissions to do so, so it is the responsibility of the user to set this up first. Nix can, however, optionally check that the OverlayFS mount settings appear as expected, matching Nix's own settings. - **Upper SQLite database**: > Not directly specified. > The location of the database instead depends on the [`state`](#store-experimental-local-overlay-store-state) setting. > It is always `${state}/db`. This contains the metadata of all of the upper layer [store objects][store object] (everything beyond their file system objects), and also duplicate copies of some lower layer store object's metadata. The duplication is so the metadata for the [closure](@docroot@/glossary.md#gloss-closure) of upper layer [store objects][store object] can be found entirely within the upper layer. (This allows us to use the same SQL Schema as the [local store]'s SQLite database, as foreign keys in that schema enforce closure metadata to be self-contained in this way.) ### Example filesystem layout Here is a worked out example of usage, following the concepts in the previous section. Say we have the following paths: - `/mnt/example/merged-store/nix/store` - `/mnt/example/store-a/nix/store` - `/mnt/example/store-b` Then the following store URI can be used to access a local-overlay store at `/mnt/example/merged-store`: ``` local-overlay://?root=/mnt/example/merged-store&lower-store=/mnt/example/store-a&upper-layer=/mnt/example/store-b ``` The lower store directory is located at `/mnt/example/store-a/nix/store`, while the upper layer is at `/mnt/example/store-b`. Before accessing the overlay store you will need to ensure the OverlayFS mount is set up correctly: ```shell mount -t overlay overlay \ -o lowerdir="/mnt/example/store-a/nix/store" \ -o upperdir="/mnt/example/store-b" \ -o workdir="/mnt/example/workdir" \ "/mnt/example/merged-store/nix/store" ``` Note that OverlayFS requires `/mnt/example/workdir` to be on the same volume as the `upperdir`. By default, Nix will check that the mountpoint as been set up correctly and fail with an error if it has not. You can override this behaviour by passing [`check-mount=false`](#store-experimental-local-overlay-store-check-mount) if you need to. )"

The upper almost-store in a local overlay store includes an upper layer directory and an upper store directory created via OverlayFS (user-managed). Nix can optionally check the OverlayFS mount settings. The upper SQLite database contains metadata for upper layer store objects and duplicated metadata from the lower layer to ensure closure data is self-contained. An example demonstrates how to configure a local-overlay store with specific paths and the necessary OverlayFS mount command. Nix checks the mountpoint setup but this behavior can be disabled.