Configuration

Graft repository mode is configured through the project-local .graft/config.toml.

project/
  app.db
  .graft/
    config.toml

Repository Config

The config stores repository format settings, object format, named remotes, and branch upstreams.

Example:

[core]
repository_format_version = 2
default_branch = "main"

[extensions]
object_format = "blake3"

[remotes.origin]
type = "fs"
root = "/srv/graft/app"

[branches.main]
remote = "origin"
merge = "refs/heads/main"

Applications should normally update config through pragmas or CLI commands instead of editing it by hand:

graft remote add origin fs:///srv/graft/app
graft branch --set-upstream-to origin/main main

Merge Policy

The optional [merge] section configures row-level merge behavior for SQLite files. It can declare application semantic keys, generated columns, schema resolvers, and safe SQLite internal resolvers.

[merge]
default_semantic_keys = ["_id"]

[merge.semantic_keys]
app_objects = ["id"]

[merge.internal_resolvers]
sqlite_sequence = "sequence_max"
index_btree = "reindex"

[merge.schema_resolvers]
add_column = "alter_table_add_column"

See Merge Policy for the full resolver list, logical status values, conflict reasons, and validation policy.

Repository Storage

Repository-mode SQLite data is stored under:

.graft/store/

This makes project data isolated. Two directories can both contain app.db without sharing storage, refs, branches, remotes, or index state.

Loader Defaults

The dynamic SQLite extension can still have process-level defaults for tests and diagnostics. Those defaults are not repository state.

In normal repository mode:

• do not rely on environment variables for project identity
• do not use user-wide config for refs or remotes
• do keep project state under .graft/

Remote URIs

Common URI shapes:

memory
fs:///absolute/path
s3://bucket/prefix
s3_compatible://bucket/prefix
s3_compatible://bucket/prefix?endpoint=https://account.r2.cloudflarestorage.com

Use memory for tests, fs:// for a local or mounted directory, and s3:// or s3_compatible:// for object storage. S3-compatible services such as Cloudflare R2 and MinIO usually need an explicit endpoint query parameter.

The exact remote type is stored in .graft/config.toml after parsing. For example:

[remotes.origin]
type = "s3_compatible"
bucket = "my-graft-bucket"
prefix = "prod/app"
endpoint = "https://account.r2.cloudflarestorage.com"

S3 credentials are not stored in .graft/config.toml or in the remote URI. Configure them in the process environment, or with the standard AWS config and credentials files understood by the S3 client:

export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="auto"

Use AWS_REGION=auto for Cloudflare R2. Graft’s remote URI parser currently accepts endpoint as the only S3 query parameter, so do not put region, access keys, or secret keys in the URI.