> 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 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. ## 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. 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. 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` | If you run a development build instead of the installed app, the folder is `@nimbalyst/electron` in the same location (for example `~/Library/Application Support/@nimbalyst/electron`). 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 4 hours** 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 4 hours. A laptop that slept overnight still gets a fresh snapshot on wake. * **Three rolling slots.** A new backup becomes `current`, the old `current` becomes `previous`, and the old `previous` becomes `oldest`. * **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. 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 slots. `previous` is one backup window older, `oldest` is two. ```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 three 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.