Create and open catalogs

A catalog is a single file that remembers your photos: where each one is, plus its ratings, labels, keywords, collections and edits. It does not hold the photos themselves. The first time you start DarkRay it creates a catalog named Main for you.

![Screenshot: the catalog band at the top of the left panel, with its menu open showing New Catalog…, Open Catalog…, Open Recent and Close]

Create a catalog

Choose File › New Catalog…, or open the menu on the catalog band at the top of the left panel and choose New Catalog….
Type a name. It can’t contain spaces or any of < > : " / \ | ? *.

DarkRay creates the file in your catalogs folder and switches to it. The folder is .darkray/catalogs in your home folder unless you change Default catalog location in File › Preferences… › General. That setting only decides where new catalogs go; catalogs you already have stay where they are.

Open a catalog

Choose File › Open Catalog… (Ctrl+O by default) and pick a .db file. If it is already open, DarkRay switches to it.

File › Open Recent lists the last ten catalogs you used, newest first. A catalog whose file has gone shows “(missing)” and can’t be picked. Clear Recent empties the list; open catalogs stay open.

Switch between catalogs

You can keep several catalogs open at once. The left panel shows one at a time: click the catalog band and pick another from its menu. A checkmark shows the one you are in. Switching saves the open photo’s edits and takes you to the other catalog’s grid.

Open catalogs are also where you can copy a collection to, and where Import can send photos.

Close a catalog

Choose File › Close Catalog, or Close “name” on the catalog band’s menu. DarkRay asks first. The last open catalog can’t be closed. A closed catalog stays on Open Recent.

If a catalog won’t open

When DarkRay starts and a catalog from last time has moved or can’t be read, it never replaces it with a new one. It leaves the catalog on Open Recent and asks what to do:

Button	Does
Locate…	Pick the catalog file at its new place and open it.
Remove	Take it off Open Recent. No file is touched.
Not Now	Leave it on Open Recent, marked missing.

If no catalog opens at all, DarkRay makes a new Main (or Main 2 and so on if Main is the one that failed).

If you open a catalog made by a newer version of DarkRay, or a database that isn’t a DarkRay catalog, DarkRay refuses it and changes nothing.

Technical details: what a catalog holds, and upgrades

A catalog is a SQLite database. It holds each photo’s path and fingerprint, camera data, rating, color label, keywords, collections, stacks, virtual copies and edit recipe. Thumbnails and previews are kept beside it in a .previews folder. DarkRay does not write ratings, keywords or edits into your photo files or into sidecar files, so the catalog file is the only place they live. Back it up. If you move your photos, see Folders and sync.

When a new version of DarkRay changes the catalog format, it copies the catalog first to a file named like Main.db.v13.bak beside it, then upgrades the original. An older version of DarkRay refuses an upgraded catalog.