> For the complete documentation index, see [llms.txt](https://docs.nimbalyst.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nimbalyst.com/troubleshooting/database-backups-and-restore.md). # 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-` 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 ```bash # 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) ```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 ```bash # 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) ```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. ```bash # 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: ```bash rm -f sqlite-db/nimbalyst.sqlite.bad # SQLite rm -rf pglite-db.bad # PGLite ``` Windows (PowerShell): ```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 , see [Feedback, Discord, Support, Releases](/getting-started/feedback-discord-support-releases.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.nimbalyst.com/troubleshooting/database-backups-and-restore.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.