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.
zb api GET /v1/orgs/{org}/instances/<instance_id>/ca.pem > databasezy-ca.pemopenssl x509 -in databasezy-ca.pem -noout -subject -enddateYou 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.
Hostname mismatch
Section titled “Hostname mismatch”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.
Client certificate errors (mTLS)
Section titled “Client certificate errors (mTLS)”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.
Check what the gateway presents
Section titled “Check what the gateway presents”From a machine with OpenSSL 1.1.1 or later:
openssl s_client -connect <host>:5432 -starttls postgres -servername <host> -CAfile databasezy-ca.pem </dev/nullUse -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.
Still stuck?
Section titled “Still stuck?”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.