Rillence
Login
Shell (psql+)

Troubleshooting

Most psql+ issues are ordinary PostgreSQL connection or permission problems wearing a familiar face. Work through the cases below before assuming something is wrong with the shell.

Connection refused

psql+: error: connection to server at "db.internal" (10.0.0.5), port 5432 failed: Connection refused

The server isn't reachable at that address. Check, in order:

  • The host and port are correct and the server is actually listening there.
  • A firewall, bastion, or VPN isn't blocking the route.
  • The PostgreSQL server is configured to accept TCP connections (listen_addresses).

Authentication failed

psql+: error: connection failed: FATAL:  password authentication failed for user "app"

Verify the username and password, the target database name, and that the user is permitted to log in. If you pass a connection string, make sure your shell did not split it on ? or & — quote the whole URL.

SSL required

psql+: error: connection failed: FATAL:  no encryption: server requires SSL connection

The server only accepts encrypted connections. Add sslmode to your connection string:

postgres://app@db.internal:5432/orders?sslmode=require

Use verify-full if you also want certificate verification. The reverse error (server does not support SSL) means you requested SSL from a server that has it disabled — drop the sslmode parameter or set it to prefer.

Autocomplete isn't suggesting columns

Schema-aware completion reads the system catalog. If only keywords complete and no columns or tables appear:

  • Confirm your search_path includes the schema you expect. The prompt shows the active search_path; unqualified names resolve against it.
  • Confirm your role has permission to read the catalog and USAGE on the schema. A locked-down read-only role may not see objects it cannot access.
  • Qualify the name (schema.table) to check whether the object resolves at all.

AI isn't responding

If ?? does nothing or reports it is unavailable, AI is either disabled or missing a key. AI is opt-in:

  • Confirm enabled = true under [ai] (or RILLENCE_AI_ENABLED=true).
  • Confirm the variable named by api_key_env is exported and holds a valid key.

See Configuration for the full setup. Remember that all other features work with AI off.

Output is too wide to read

Wide rows wrap and become unreadable in a narrow terminal. Switch to expanded output, which prints one column per line:

\x

Run the query again. Toggle \x once more to return to normal table output.