Managing Databases

Photosphere maintains a list of configured databases in ~/.config/photosphere/databases.json. 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.

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.

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.

View a Database Entry

psi dbs view my-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 my-photos

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

Remove a Database Entry

psi dbs remove my-photos
psi dbs remove 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. If the --db value doesn't match any entry in databases.json, it is treated as a raw path and existing manual config flows apply.

Storage Location

The database list is stored at:

~/.config/photosphere/databases.json

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)