Test the connection
The auth-aware connection probe — what it checks, every result code, and the common fixes.
The connection test proves Backup can reach and authenticate to your database before any backup is scheduled. It runs automatically right after you save credentials, and on demand from the Test connection button on the datasource detail page.
The probe is auth-aware for both engines: it opens a real connection with your stored credentials using the official PostgreSQL / MongoDB client libraries and pings the server, with a 5-second timeout. A successful test reports the round-trip latency — "Connection OK (X ms)."
Run a test
- Open the datasource in Backup → Datasources.
- Click Test connection. The button shows a spinner while testing, then keeps a green check (last test passed) or a red cross (last test failed) as a reminder.
- On failure, the toast shows the specific reason.
The button is disabled until the datasource has credentials.
Result codes
The underlying API returns a structured result; these are all the codes and what to do about each:
| Code | Meaning | What to do |
|---|---|---|
| (success) | Connected, authenticated, pinged. Latency shown in ms. | Attach a policy and move on. |
auth_failed | Reached the database, but it rejected the credentials. | Check user/password (and for Postgres that pg_hba.conf allows this role from Backup's IP; for Mongo that authSource is right). |
timeout | Couldn't establish the connection within 5 seconds. | Almost always the firewall: allow 18.196.207.101 on the DB port. Also check host and port. |
network_unreachable | DNS didn't resolve, the host isn't routable, or the host is not public — for security, Backup only connects to publicly-routable addresses. | Check the hostname resolves publicly and the port is open. Private/internal targets (RFC1918, loopback/localhost, link-local incl. the cloud-metadata endpoint) are refused. |
invalid_uri | The stored connection string didn't parse. | Fix the URI format and re-save credentials. |
no_credentials | No credentials stored yet. | Save credentials first. |
unknown | Something else — the message carries the driver's error. | Read the message; if TLS-related, see below. |
(Two further codes — decrypt_failed and unsupported_engine —
indicate an internal problem rather than something on your side;
contact support if you ever see them.)
What the test does and doesn't do
It does:
- open a TCP connection to your host and port,
- negotiate TLS if your URI requires it,
- authenticate as the configured user and ping the server,
- report latency.
It doesn't:
- take a backup or run
pg_dump/mongodump, - check that the role can actually read every table you want backed up,
- connect to anything that isn't publicly routable — private, loopback, and link-local addresses (including cloud-metadata endpoints) are resolved and refused before any connection is attempted.
So a green test plus insufficient grants can still mean a failed first backup — the job's error summary will name the permission problem. The test catches the common failures (network, auth, DNS), not all of them.
Every attempt — manual or automatic — is recorded in the
audit log as datasource.verify_attempted, with
the outcome but never the connection string.
Common fixes
auth_failedagainst Postgres —pg_hba.confneeds a rule likehost all norcube_backup 18.196.207.101/32 scram-sha-256.timeoutfrom AWS RDS — the security-group inbound rule needs18.196.207.101/32on the database port.- TLS errors on a self-signed certificate — Backup won't trust unknown CAs today. Use a publicly-trusted certificate on the database, or contact us.
- Mongo replica sets — make sure every host in the URI is
reachable from the allowlisted IP, or use a
mongodb+srvURI that resolves to reachable hosts.