Managing Databases

Photosphere maintains a list of configured databases in ~/.config/photosphere/databases.toml. Each entry stores a name, path, and optional references to shared secrets (S3 credentials, encryption keys, geocoding API keys). When you open a database that has linked secrets, credentials are resolved automatically.

Desktop App

Open the database management page from the left sidebar by clicking Manage Databases.

Database List

The page displays a table of all configured databases with their name and path. From here you can add, edit, or remove entries.

Adding a Database

There are two ways to add a database:

• Create Database: initialises a new empty database on disk and registers it. You choose a directory (local filesystem or S3), and optionally link secrets for encryption and cloud storage.
• Add Existing Database: registers an existing database that was created elsewhere (e.g. via the CLI or on another machine). You provide the path and Photosphere reads the database metadata.

When adding or creating a database you can link shared secrets:

• S3 credentials: required for databases stored on S3-compatible storage. Select an existing secret or create one inline.
• Encryption key: required for encrypted databases. Select an existing key or create one inline.
• Geocoding API key: optional; enables automatic reverse-geocoding of photo GPS coordinates.

Editing a Database

Click the edit icon next to a database entry to change its name, description, path, or linked secrets. Changes take effect immediately.

Removing a Database

Click the delete icon to remove a database entry from the list. This does not delete the database files on disk, it only removes the entry from the configured list.

Replicating a Database

Click the replicate icon next to a database entry to copy it to a new location. The dialog asks for a destination path and a replication mode:

• Partial (default), copies only metadata and merkle trees. Original photos and videos are fetched on demand from the source when you view them. Choose this when you want a small, browsable replica of a remote database.
• Full: copies every original, display, and thumbnail file. Choose this when you want a complete, standalone copy that does not depend on the source remaining reachable.

You can optionally link a destination encryption key (to create an encrypted replica) and, when the destination is an S3 path, destination S3 credentials. Both are picked from your existing shared secrets, to use a new key, create it on the Manage Secrets page first.

Replication runs in the background; the dialog shows progress and a success notification when done. The destination is automatically added as a new entry on this page, with its origin set to the source path so future syncs know where to pull from.

To replicate to an existing encrypted database, register that destination on this page first so the replica can inherit its credentials. Cancellation mid-replication is not supported in v1; the dialog can be dismissed once the run finishes.

The CLI equivalent is psi replicate, see Command-Reference for the full flag list.

Opening a Database

The database picker (shown on launch or when switching databases) lists your configured databases and recent databases. Click Manage in the picker to go to the full database management page. The desktop app also remembers the last-opened database and reopens it automatically on the next launch.

CLI

The psi dbs command group provides the same management capabilities from the command line.

List Databases

psi dbs list

Displays a table of all configured databases with their name and path.

Add a Database

psi dbs add

Interactive prompts walk you through entering a name, path, and optionally linking secrets (S3 credentials, encryption key, geocoding API key). You can select an existing shared secret or create a new one inline.

Database names must be unique. If you try to add a database with a name that is already in use, the command will error and no entry will be added.

View a Database Entry

psi dbs view                        # select from list
psi dbs view --name my-photos
psi dbs view --path /data/photos

Shows all fields of the entry: name, description, path, and any linked secret IDs. The name lookup is case-insensitive.

Edit a Database Entry

psi dbs edit                        # select from list
psi dbs edit --name my-photos
psi dbs edit --name my-photos --yes --new-name renamed
psi dbs edit --name my-photos --yes --path /new/path

Re-prompts for each field with the current values pre-populated.

Remove a Database Entry

psi dbs remove                      # select from list
psi dbs remove --name my-photos
psi dbs remove --path /data/photos
psi dbs remove --name my-photos --yes   # skip confirmation

Removes the entry from the list. Does not delete files on disk.

Using a Database by Name

Once a database is registered, you can use its name instead of its path with any command:

psi summary --db my-photos
psi add --db my-photos ~/new-pics
psi verify --db my-photos

If the entry has linked secrets, they are resolved automatically, no need for --key or S3 configuration flags. Credentials are fetched lazily: S3 credentials are only loaded when an S3 path is actually accessed, encryption keys only when an encrypted database is opened, and geocoding keys only when geocoding is needed. If the --db value doesn't match any entry in databases.toml, it is treated as a raw path and existing manual config flows apply.

If the name is not found, the CLI displays fuzzy-matched suggestions, e.g. Did you mean: my-photo, my-photos-old?, to help correct typos.

Sharing

You can share a database configuration (including linked secrets) to another device over the LAN. This is useful for setting up a new device with the same databases and credentials without manually copying secrets.

• Desktop: Click Share on a database entry to send it, or Receive Database to receive one from another device.
• CLI: Use psi dbs send and psi dbs receive.

See Sharing-Credentials for full details on how LAN sharing works and its security architecture.

Storage Location

The database list is stored at:

~/.config/photosphere/databases.toml

This file is shared between the desktop app and the CLI. Changes made in one are visible in the other.

Related Pages

• Managing-Secrets, managing the secrets that databases link to
• Getting-Started-Desktop, desktop app quick start guide
• Getting-Started-CLI, CLI quick start guide
• Command-Reference, full CLI command reference (dbs section)