Skip to content

Help

TLS and certificate errors

Tested with:Databasezy API v1 · zb CLI 0.1

Every Databasezy connection uses TLS. There is no plaintext port. The gateway accepts TLS 1.2 and TLS 1.3, picks your instance from the hostname your client sends (SNI), and presents a certificate for the instance’s hostname. Most TLS errors come from a client that does not trust the certificate chain, connects with a different hostname, sends no hostname, or does not turn TLS on. The fixes are below.

SSL/TLS is required; use sslmode=require or verify-full

Section titled “SSL/TLS is required; use sslmode=require or verify-full”

Cause: a PostgreSQL client connected without TLS (for example sslmode=disable). The gateway refuses plaintext.

Fix: set sslmode=verify-full and pass the CA bundle (see below). MySQL clients get the equivalent error 3159, Connections using insecure transport are prohibited while --require_secure_transport=ON. Use --ssl-mode=REQUIRED. Use --ssl-mode=VERIFY_IDENTITY (or at least REQUIRED). For Valkey and Redis use a rediss:// URL; for HTTP engines use https://.

certificate verify failed or unable to get local issuer certificate

Section titled “certificate verify failed or unable to get local issuer certificate”

Cause: your client does not trust the chain the gateway presents. Many drivers use the operating system’s trust store and work with no extra settings. libpq-based clients (psql, psycopg, Ruby pg, PHP pgsql) and some MySQL drivers do not; they need the CA bundle passed explicitly.

Fix: download the CA bundle for the instance and point your client at it.

shell
zb api GET /v1/orgs/{org}/instances/<instance_id>/ca.pem > databasezy-ca.pem
openssl x509 -in databasezy-ca.pem -noout -subject -enddate

You can also download it from the instance’s Connect page. Then pass it to your client, for example sslrootcert=databasezy-ca.pem (PostgreSQL), --ssl-ca=databasezy-ca.pem (MySQL) or --tlsCAFile (MongoDB). If you pinned a certificate, pin the intermediate CA, never the leaf: leaf certificates rotate automatically. See mTLS and certificate pinning.

Errors look like server certificate for "..." does not match host name "..." or Hostname/IP does not match certificate's altnames.

Cause: the hostname in your connection string is not the one on the certificate. This happens when you connect by IP address, through your own DNS alias (CNAME) that is not set up as a custom domain, or with a typo.

Fix: use the exact hostname from the Connect page. To use your own hostname, add it as a custom domain under Network → Custom domain; Databasezy then issues a certificate for it. Custom domains are a paid add-on on Solo and above. See Connecting to Databasezy.

Connection closed during the handshake: missing SNI

Section titled “Connection closed during the handshake: missing SNI”

Cause: the gateway needs the hostname in the TLS handshake (SNI) to find your instance. Without it, the gateway closes the connection and your client reports a handshake failure or an unexpected EOF. Clients send no SNI when you connect to an IP address. libpq sends SNI from PostgreSQL 14 onward; older psql and libpq builds do not, and sslsni=0 turns it off.

Fix: connect by hostname, upgrade old clients (libpq 14 or later), and leave sslsni at its default of 1.

unsupported protocol, wrong version number or no protocols available

Section titled “unsupported protocol, wrong version number or no protocols available”

Cause: the client offers only TLS 1.0 or 1.1, or no cipher suite the gateway accepts. The gateway requires TLS 1.2 or later with modern AEAD cipher suites. Old OpenSSL builds, old Java runtimes and some embedded clients hit this. wrong version number can also mean the client is speaking plaintext to a TLS port, for example http:// to an HTTP engine.

Fix: upgrade the client, runtime or OpenSSL so it supports TLS 1.2 or 1.3. Use https:// for HTTP engines.

Cause: the instance requires client certificates (mTLS, available on Team, Enterprise and secure placement). A client without a certificate signed by the CA you uploaded fails during the handshake.

Fix: pass the client certificate and key, for example sslcert=client.pem&sslkey=client-key.pem for PostgreSQL. Check the certificate has not expired and was issued by the CA under Network → Client certificates (mTLS). See mTLS and certificate pinning.

From a machine with OpenSSL 1.1.1 or later:

shell
openssl s_client -connect <host>:5432 -starttls postgres -servername <host> -CAfile databasezy-ca.pem </dev/null

Use -starttls mysql on port 3306, and leave out -starttls for Valkey, MongoDB and HTTP engines. Verify return code: 0 (ok) means the chain and hostname are fine, so the problem is in your client’s settings. If the connection closes before any certificate is shown, check the IP allow-list.

Search the help center or ask the assistant in the portal Help panel. If that does not solve it, open a support ticket from the portal (Help → Open a ticket). Include the instance id, the region, the exact error text, your client or driver version and its TLS library (for example the OpenSSL version), and the time it happened in UTC. Never paste passwords, connection strings with passwords, API keys, private keys or patient data (PHI) into a ticket. See How to get help.