Protect Qdrant
Snapshots, Marks, Proof, Rewind and Pulse for Qdrant 1.13 and newer.
Rowsafe backs up Qdrant, the open-source vector database, to your bucket, encrypted on your server. You get Marks, a weekly Proof, Rewind with Undo, and Pulse with one-click fixes.
Qdrant keeps no change log, so restores go back to a snapshot, not to any second.
Before you start
- Qdrant 1.13 or newer, as a single server (cluster mode is refused).
- Debian or Ubuntu, or Docker next to the official image (below).
- The
qdrantprogram on the server, for Proof and Rewind copies. Backups work without it. - A bucket and a passphrase. See Adopt an existing database.
Turn on backups
Run this on the server, then approve it in your browser:
curl -fsSL https://rowsafe.sh | sudo sh -s -- --accountThe installer finds Qdrant. Nothing restarts and no setting changes.
A key for Rowsafe. Qdrant has no smaller role that can take snapshots, so the key needs every right. The installer uses ROWSAFE_QDRANT_API_KEY, else api_key from Qdrant's config, else asks. Better: give Qdrant's alternative key (service.alt_api_key), so you can change your apps' key freely. The key stays on the server.
The plan. Review it and say yes. Rowsafe checks the key and bucket, then takes the first snapshot.
With JSON Web Tokens on (service.jwt_rbac), the agent sends short-lived tokens, never its key. Without them, it sends the key only on the server or over TLS. The agent never reads Qdrant's files: it uses Qdrant's API.
What Rowsafe does
| How | |
|---|---|
| Backup | Qdrant's snapshot of each changed collection, encrypted, sent to your bucket (or Rowsafe Storage), then deleted from disk. Every 15 minutes (Qdrant 1.17+; older: every collection, hourly). |
| Kept | The newest 24 (Snapshots to keep), plus one an hour for a day and one a day for 7 days. |
| Marks | A snapshot taken on the spot. |
| Proof | Weekly: restore the newest backup into a temporary local Qdrant, check every collection is green with its points, a search answers and aliases are back. Then delete it. |
| Rewind | A copy of a snapshot or Mark in a temporary Qdrant, to look at. Apps can't connect to it. |
| Rewind the whole database | Puts the server back in place, no restart (below). Undo for 7 days. |
| Pulse | Memory, collections, requests, failures and Qdrant's own issues (below). |
| Security check | Keys, TLS, JSON Web Tokens, CORS, snapshots from any address, telemetry, cluster port, a look from the internet. |
| API keys | Read-only, read-write or admin keys, per collection. |
| Restart | Restart, after you confirm. |
| Updates | The newest checked release of your series, in one click. |
Only collection and field names reach Rowsafe. Never points, vectors or payloads.
Restores go back to a snapshot
A restore uses the newest snapshot at or before your moment, or a Mark. With snapshots every 15 minutes, you can lose up to 15 minutes of writes. If that snapshot was removed, a copy uses the nearest older one; a rewind in place stops and names it.
- Before a risky change, take a Mark.
- To lose less, pick every 5 minutes in Settings (or 30 or 60 for fewer).
- Pulse warns when the newest snapshot is too old: Take a snapshot now.
Rewind the whole database
Rewind the whole database puts every collection back as it was in a snapshot or Mark. Qdrant keeps running.
- Rowsafe unpacks the snapshot on your server.
- It saves the current state to your bucket, for Undo.
- It restores each collection, removes newer ones, and puts aliases back.
Stop your app's writes while it runs. Those writes aren't kept for Undo.
- Undo rewind works for 7 days, and also if the rewind stops part way.
rowsafe_keys(Rowsafe's API keys) is never rewound.- Single points can't be brought back. Rewind the whole database instead.
API keys
In Databases & users, Qdrant's users are API keys. The agent signs each one on your server (a JSON Web Token) and shows it once. Rowsafe can't read it. Needs service.jwt_rbac: true.
| Access | Reaches | Expires |
|---|---|---|
| Read-only | Every collection, or the ones you choose | Never, unless you choose (at most 365 days) |
| Read-write | The collections you choose | Never, unless you choose (at most 365 days) |
| Admin | Everything, including creating and deleting collections | Always: 30 days unless you choose, at most 90 |
- Removing a key, or making a new token, ends the old one at once.
- Admin keys can change Rowsafe's key list, so they always expire. Removing one ends it at once unless it was misused against that list; expiry always ends it. If the list changes, the agent restores it and Pulse offers Remove every admin key.
- To end every key, root makes Rowsafe's key new on the server.
- Collections are made by your apps. Removing one in the dashboard takes a Mark first. Keys limited to it go with it; others need a new token.
Qdrant's own keys (api_key, read_only_api_key) are root's. Rowsafe only shows whether they're set.
Pulse
Pulse reads metrics every minute and status every 5 minutes.
| Finding | Fix |
|---|---|
| Searches filter on a field without an index | Create index on the field (built in the background). |
| Qdrant uses 85% or more of the server's memory | Move a large collection's vectors to disk (up to three offered). A little slower on a cold cache. |
| A collection failed (red), or Qdrant started in recovery mode | Restart. |
| gRPC still serves the previous certificate | Restart (gRPC loads certificates only at start). |
| Snapshot files left on Qdrant's disk | Delete leftover snapshots. Your bucket isn't touched. |
| Someone changed Rowsafe's list of keys | Remove every admin key. |
| No snapshot for too long | Take a snapshot now. |
Each fix asks you to confirm. Index and disk fixes need no restart.
Security settings live in Qdrant's config file: only root changes them, with a restart. The security check shows the lines under Do it yourself. Who can connect limits Qdrant's ports, with root's firewall permission.
What Rowsafe may do
Rowsafe's key has every right in Qdrant. The agent uses it only for your backups or when someone asks. With JSON Web Tokens on, monitoring is read-only.
Root decides what Rowsafe may do on the server (permissions, sudo rowsafe-allow):
| Permission | Lets Rowsafe |
|---|---|
restart | restart Qdrant (Restart) |
updates | install the newest release of your Qdrant series |
firewall | limit who can reach Qdrant's ports |
Rewinding the whole database needs no root permission.
Updates
Update installs the newest release of your series (1.19.x), pinned by version and SHA-256, from Qdrant's GitHub, then restarts Qdrant. Only when a person clicks it, or in Rowsafe Cloud's maintenance window. Needs Qdrant at /usr/bin/qdrant, not Docker. Allow it.
Docker
Run ghcr.io/rowsafe/agent:qdrant1.19 next to the official qdrant/qdrant image. It's built on that image, so Proof uses Qdrant's own program. Pin a release with a tag like <version>-qdrant1.19.
services:
qdrant:
image: qdrant/qdrant:v1.19.2
env_file: qdrant.env # QDRANT__SERVICE__API_KEY, QDRANT__SERVICE__ALT_API_KEY (Rowsafe's)
environment:
QDRANT__SERVICE__JWT_RBAC: "true"
QDRANT__SERVICE__ENABLE_SNAPSHOT_URL_RECOVERY: "false"
volumes:
- qdrantdata:/qdrant/storage
rowsafe-agent:
image: ghcr.io/rowsafe/agent:qdrant1.19
hostname: db-1
environment:
ROWSAFE_QDRANT_URL: http://qdrant:6333
env_file: rowsafe-agent.env
volumes:
- rowsafe-state:/var/lib/rowsafeOver plain HTTP, JSON Web Tokens must be on (or use https:// with ROWSAFE_QDRANT_CA_FILE). Full example: compose.qdrant.example.yml. Then, once (qdrant login asks for Rowsafe's key):
docker compose exec rowsafe-agent rowsafe-agent qdrant login --port 6333
rowsafe adopt vectors --host db-1 --engine qdrant --port 6333
rowsafe apply vectorsThe agent never updates itself in Docker. Run docker compose pull rowsafe-agent && docker compose up -d rowsafe-agent, or update it from the dashboard and let Rowsafe restart the container.
On servers Rowsafe creates
Rowsafe Cloud and Create a server for me can install Qdrant 1.19:
- Official release, pinned and checked by SHA-256.
- Sandboxed, telemetry off, JSON Web Tokens on, no snapshots from URLs. Random keys stay root's.
- TLS with a key from Databases & users: REST on
6333, gRPC on6334. Port6335stays closed. - 2 GB of memory or more.
- Certificates renew by themselves. gRPC picks them up at the next restart (Pulse offers Restart).
- No standby, Clone or private connections from AWS.
from qdrant_client import QdrantClient
client = QdrantClient(
url="https://x7kq2mfa3pzd.cloud.rowsafe.sh:6333",
api_key="YOUR_KEY",
)Restore without Rowsafe
With your bucket settings and passphrase in the environment (as in agent.env):
rowsafe-agent qdrant download-backup --stanza vectors
rowsafe-agent qdrant download-backup --stanza vectors --label 20261003-140000F --to ./vectors.snapshotStart an empty Qdrant of the same or newer version from it: qdrant --storage-snapshot ./vectors.snapshot.
Limits
- No restore to any second: only to a snapshot (every 15 minutes by default) or a Mark.
- Snapshots are whole. Qdrant writes each to its disk first. Leave room for your largest collection (for all of them before 1.17).
- Marks go when they're older than the oldest kept snapshot.
- Single servers only: no cluster mode.
- No single points back: a copy is for looking. Rewind the whole database to go back.
- Rewinding the whole database needs disk room to unpack the snapshot.
- Proof and Rewind copies need the
qdrantprogram, same version or newer. - API keys need JSON Web Tokens on and a key on Qdrant.
- Rowsafe's key: if you gave your
api_key, changing it means running the installer again. The alternative key avoids that. - Security settings need a config change and a restart. Rowsafe shows how but can't do it.
- Updates stay in your series and need
/usr/bin/qdrant. In Docker, change the image. - Not available for Qdrant: Find the moment, safe copies, migration previews, clones, standby servers, Move in, connection pooling, Tuning, logs, file backups and a second copy.