Database Backups and Restore

Where Nimbalyst stores its automatic database backups on macOS, Windows, and Linux, and how to restore one by hand for both the SQLite and PGLite backends.

Nimbalyst keeps rolling backups of its local database so a corrupted database does not cost you your session history. This page covers where those backups live, how often they are taken, and the exact restore steps for both database backends.

Try in-app recovery first

Before restoring anything by hand, open Settings > Application > Database. Database Settings can handle the common cases without the command line:

• Databases set aside on this computer lists any database copy Nimbalyst preserved rather than deleted, with when it was set aside and what it contains. You can review a copy, reveal it on disk, or restore it. Restore is always an explicit action you confirm; nothing is restored automatically.

• PGLite copies kept from a migration shows the pre-migration copy of your PGLite database after a SQLite migration, and Restore from preserved PGLite rolls back to it if the migration left you worse off.

• If automatic migration has been held back on this computer, the panel explains the recorded reason and lets you clear the block so a later launch can assess the migration again.

Recovery and rollback keep the original data intact across restarts, so trying an in-app restore does not burn your only copy. The manual steps below are for when the app cannot start at all, or when you need a specific rolling backup slot that the panel does not offer.

Which backend you are on

Nimbalyst ships two local database backends. Newer installs use SQLite. Installs that started before the SQLite migration stay on PGLite until you migrate.

Check in this order, inside the Nimbalyst application data folder (paths below). Nimbalyst itself resolves the backend the same way, so stop at the first line that matches:

1. database-backend.json exists. Open it and read the backend field. It says either sqlite or pglite, and it wins over everything else on disk.

2. No database-backend.json, but a pglite-db folder exists. You are on PGLite.

3. Neither. You are on SQLite.

You can also read the answer straight from the log: the first database line in logs/main.log inside the application data folder looks like [Database] Backend selector resolved to 'sqlite'.

Do not judge by the presence of a sqlite-db folder alone. If you migrated to SQLite and later rolled back from Settings → Database, that folder stays behind while database-backend.json says pglite, and restoring into it would do nothing.

You may also see a pglite-db.migrated-<timestamp> folder. That is the pre-migration copy of your old PGLite database, kept as a safety net. It is not the live database and it is not a backup slot, so ignore it when following the steps below. Database Settings manages these copies for you, including rollback and deletion, under PGLite copies kept from a migration.

Each backend has its own backup folder, so follow the section that matches yours.

Where the files live

The application data folder is:

Platform	Application data folder
macOS	~/Library/Application Support/Nimbalyst
Windows	%APPDATA%\Nimbalyst
Linux	~/.config/Nimbalyst

Development builds use an @nimbalyst/electron folder in the same platform-specific location.

Inside that folder:

What	SQLite	PGLite
Live database	sqlite-db/nimbalyst.sqlite (plus -wal and -shm siblings)	pglite-db/ (a folder)
Backups	sqlite-db.backups/	db-backups/
Backup slots	nimbalyst.backup-current.sqlite, nimbalyst.backup-previous.sqlite, nimbalyst.backup-oldest.sqlite	pglite-db.backup-current/, pglite-db.backup-previous/, pglite-db.backup-oldest/
Backup index	backup-metadata.json	backup-metadata.json

backup-metadata.json records the timestamp, size, and verification result for each slot, which is the quickest way to see how fresh your newest backup is.

How backups are taken

• Every 12 hours by default while Nimbalyst is running.

• On quit, as part of the shutdown sequence.

• At startup and on wake from sleep, if the last successful backup is older than the configured interval. A laptop that slept through a backup window still gets a fresh snapshot.

• Two rolling copies by default. A new backup becomes current and the old current becomes previous.

• Verified before it is kept. Nimbalyst opens each new backup and reads from it before promoting it into the rolling slots, and rejects a snapshot that has shrunk to less than half the size of the one it would replace.

Under Settings > Application > Database, you can keep one, two, or three copies and change the interval. Setting the interval to On quit only disables periodic backups. Cadence changes take effect after a restart. The oldest slot exists only when you keep three copies.

On PGLite, a database that fails to open at startup triggers an automatic restore from the newest valid backup. On SQLite, restore is a manual step, which is what the rest of this page walks through.

Restore a SQLite backup

Only follow this section if you confirmed SQLite is your active backend above.

Quit Nimbalyst completely first. Restoring while the app is running will not work, and can leave you with a half-written database.

macOS and Linux

# 1. Quit Nimbalyst completely (Cmd+Q on macOS)

# 2. Go to the application data folder
cd ~/Library/Application\ Support/Nimbalyst     # macOS
# cd ~/.config/Nimbalyst                        # Linux

# 3. Move the bad database aside, including its WAL and SHM siblings
mv sqlite-db/nimbalyst.sqlite sqlite-db/nimbalyst.sqlite.bad
rm -f sqlite-db/nimbalyst.sqlite-wal sqlite-db/nimbalyst.sqlite-shm

# 4. Copy the most recent backup into place
cp sqlite-db.backups/nimbalyst.backup-current.sqlite sqlite-db/nimbalyst.sqlite

# 5. Start Nimbalyst

Windows (PowerShell)

# 1. Quit Nimbalyst completely

# 2. Go to the application data folder
cd "$env:APPDATA\Nimbalyst"

# 3. Move the bad database aside, including its WAL and SHM siblings
Rename-Item sqlite-db\nimbalyst.sqlite nimbalyst.sqlite.bad
Remove-Item sqlite-db\nimbalyst.sqlite-wal, sqlite-db\nimbalyst.sqlite-shm -ErrorAction SilentlyContinue

# 4. Copy the most recent backup into place
Copy-Item sqlite-db.backups\nimbalyst.backup-current.sqlite sqlite-db\nimbalyst.sqlite

# 5. Start Nimbalyst

Deleting the -wal and -shm files matters. They belong to the database you just replaced, and leaving them behind can corrupt the restored copy.

Restore a PGLite backup

Only follow this section if you confirmed PGLite is your active backend above. If database-backend.json says sqlite, Nimbalyst never opens pglite-db and restoring it changes nothing. Use the SQLite steps instead.

Quit Nimbalyst completely first, the same as for SQLite.

PGLite stores its database as a folder rather than a single file, so every copy here is recursive.

macOS and Linux

# 1. Quit Nimbalyst completely (Cmd+Q on macOS)

# 2. Go to the application data folder
cd ~/Library/Application\ Support/Nimbalyst     # macOS
# cd ~/.config/Nimbalyst                        # Linux

# 3. Rename the corrupted database (keeps it around just in case)
mv pglite-db pglite-db.bad

# 4. Copy the most recent backup into place
cp -r db-backups/pglite-db.backup-current pglite-db

# 5. Start Nimbalyst

Windows (PowerShell)

# 1. Quit Nimbalyst completely

# 2. Go to the application data folder
cd "$env:APPDATA\Nimbalyst"

# 3. Rename the corrupted database
Rename-Item pglite-db pglite-db.bad

# 4. Copy the most recent backup into place
Copy-Item -Recurse db-backups\pglite-db.backup-current pglite-db

# 5. Start Nimbalyst

If the newest backup is also bad

Open backup-metadata.json in the backup folder before you pick. It lists each slot with its timestamp, sizeBytes, and verified flag, so you can see how much work each choice costs you rather than guessing.

Then work back through the available slots. previous is one backup window older. If you configured three copies, oldest is two windows older.

# SQLite
cp sqlite-db.backups/nimbalyst.backup-previous.sqlite sqlite-db/nimbalyst.sqlite
cp sqlite-db.backups/nimbalyst.backup-oldest.sqlite   sqlite-db/nimbalyst.sqlite

# PGLite
cp -r db-backups/pglite-db.backup-previous pglite-db
cp -r db-backups/pglite-db.backup-oldest   pglite-db

Repeat the same quit, clear, copy, launch sequence each time.

What a restore brings back

The database holds:

• AI session and conversation history

• Document edit history behind the History sidebar

• Session metadata, prompts, and drafts

• Local tracker data

The following live outside the database and are untouched by a database problem or a restore:

• Your document and project files on disk

• Application and workspace settings

• Anything already synced to a Nimbalyst team

Because a restore rewinds to the last snapshot, work done between that snapshot and the failure is not recovered. Files on disk are unaffected either way.

Cleaning up

Once you have confirmed the restore worked and your sessions are back, delete the copy you set aside.

macOS and Linux:

rm -f  sqlite-db/nimbalyst.sqlite.bad     # SQLite
rm -rf pglite-db.bad                      # PGLite

Windows (PowerShell):

Remove-Item sqlite-db\nimbalyst.sqlite.bad            # SQLite
Remove-Item -Recurse -Force pglite-db.bad             # PGLite

You may also see temp-backup-* entries in a backup folder after a crash. They are leftovers from an interrupted snapshot, Nimbalyst sweeps them on the next launch, and they are safe to delete.

Still stuck

If none of the available backups will open, send us the contents of backup-metadata.json and the main log from the logs folder in the same application data directory. Reach out on Discord or at [email protected], see Feedback, Discord, Support, Releases.