Troubleshooting PostgreSQL connectivity

TL;DR

Symptom-first troubleshooting for PostgreSQL connectivity - SSL and pg_hba rejections, timeouts, IAM authentication, wrong PrivateLink hostname, misleading error wrappers, and miner preflight failures.

Your AI can read this via Docs MCPInstall MCP →Connect

Resolve common PostgreSQL connectivity issues when integrating PostgreSQL with Atlan. Symptom-first, ordered by how often each issue actually occurs in support. Each entry includes the check you can run yourself before opening a ticket.

Quick index

You see	Most likely cause	Jump to
`FATAL: pg_hba.conf rejects connection ... SSL off` (often with `PAM authentication failed`)	Server requires SSL; connection sent none	SSL rejections
"SQL client authentication failed" / "Not able to authenticate your credentials" - but credentials are right	It's usually not auth: read the inner error	Misleading wrappers
`connection timeout expired`	Firewall, wrong hostname, stale IP, or unopened port	Timeouts
IAM auth fails as a password error; PrivateLink itself is healthy	`rds_iam` grant, `rds-db:connect`, or the AWS Region field	IAM authentication
Timeout right after a PrivateLink setup "completed"	RDS hostname in the Host field instead of the VPCE DNS name, or connection still pending acceptance	Wrong hostname
Worked for months, broke overnight, nothing changed on your side	Database restart changed its IP; egress/policy drift; or an Atlan-side change	Sudden breakage
Crawler fine, miner fails at preflight	`pg_stat_statements` missing or ungranted	Miner preflight

SSL rejections - "pg_hba.conf ... SSL off" family

Symptom. Test connection or preflight fails with errors like (hostnames anonymized):

(psycopg.OperationalError) connection failed:
FATAL: PAM authentication failed for user "atlan_user"
FATAL: pg_hba.conf rejects connection for host "10.x.x.x",
       user "atlan_user", database "analytics", SSL off
-- variant: "... no encryption"

Why. Two-layer rejection. The connection arrived without SSL; the server's pg_hba.conf has a hostssl (SSL-only) rule for this user/database, so it's rejected before authentication completes - which then also surfaces as a PAM/password failure. No credential change will ever fix it. This is the most common single PostgreSQL connectivity failure.

Fix.

Set the Atlan connection's SSL mode to require (or verify-ca/verify-full if you have the CA bundle). If you can't find the field, ask support to set the connection's sslmode.
Have your Postgres admin confirm a hostssl rule for the Atlan user and database exists before any broader PAM catch-all (self-managed), or review rds.force_ssl and the user's auth method (RDS/Aurora). See Firewalls, pg_hba.conf, and SSL.
If PAM/LDAP auth is intentional for this account, verify that stack accepts non-interactive logins; otherwise scram-sha-256 is cleaner for service users.

Misleading error wrappers - read the inner error

Symptom. The UI says SQL client authentication failed (e.g. ATLAN-CLIENT-401-02), Not able to authenticate your credentials, or a generic HEKA-500-00-009 - but your credentials are verified correct.

Why. These are generic wrappers around whatever went wrong underneath. In support history they have wrapped: TCP timeouts (firewall), pg_hba rejections (SSL), stale IPs, missing table grants, and Atlan-internal deployment issues. The word "authentication" in the wrapper is not evidence of an authentication problem.

Fix. Expand the workflow logs and find the innermost error line - the ones that matter look like psycopg.errors.ConnectionTimeout: connection timeout expired (→ Timeouts), FATAL: pg_hba.conf rejects ... (→ SSL rejections), or permission denied for table ... (grants, not connectivity). Then follow that section. If the log shows no inner error at all, paste the wrapper + workflow run link in a ticket - the cause has more than once been on Atlan's side (a connector service blip; a worker/workflow version mismatch), and support can confirm quickly.

Timeouts - connection timeout expired

Symptom. Preflight or test connection hangs, then fails with psycopg.errors.ConnectionTimeout: connection timeout expired (sometimes listing several hostaddr attempts).

Why. TCP never connected. This is gate 1 - nothing to do with users, passwords, or SSL. The usual causes, in observed order of frequency:

Atlan's egress IPs aren't allowlisted at your firewall - including the QA-tenant-has-different-IPs trap (each tenant has its own IPs).
The database's underlying IP changed (restart/failover) and something pinned to the old IP - NLB target group, peering rule, firewall entry.
PrivateLink: the Host field has your RDS hostname instead of the VPCE DNS name (→ next section), the endpoint is still pending acceptance, or a non-default port was never opened on Atlan's side.

Check yourself. From outside your network: nc -vz <host> <port>. An instant connect means the path is open (look elsewhere); a long hang confirms a network drop. Then compare the IP the hostname resolves to now (nslookup <host>) against what your firewall/NLB has configured.

IAM authentication failures (RDS/Aurora)

Symptom. The connection reaches the database (no timeout) but IAM Role/User auth fails with password- or PAM-style errors.

Check, in order:

IAM Database Authentication enabled on the cluster/instance?
GRANT rds_iam TO atlan_user; run on the database?
IAM role/user has rds-db:connect for this DB user and instance? Trust policy allows Atlan's principal (confirm the exact principal with support)?
AWS Region field set to the database's region? Cross-region tenants hit token-signing mismatches that present as password failures - see Special cases.
Using Azure? Service Principal auth is not supported - use Basic auth.

Wrong hostname after PrivateLink setup

Symptom. PrivateLink shows Available in AWS, connectivity "should" work, but Atlan times out. Meanwhile your own tools connect fine using the RDS hostname.

Why. Your tools are inside your network; the RDS hostname resolves for them. Atlan is not - it can only reach your database through the plug it built, whose name looks like vpce-...-....vpce-svc-....<region>.vpce.amazonaws.com.

Fix. Put the VPCE DNS name from your support ticket in the Host field, character for character, with the correct listener port. If you never received it, ask on the ticket. Also verify the endpoint connection shows Available, not Pending - nothing accepts itself. See Phase 4 of the PrivateLink guide.

It worked for months, then broke overnight

Did the database restart, fail over, or get maintained? Its IP likely changed. Check every place an IP is pinned: NLB target groups, peering configs, firewall rules. (Self-healing can take days if you wait for DNS caches; fix the pinned value instead.)
Did a firewall or network policy change on your side? Diff current rules against Atlan's egress IPs from your ticket. Remember QA vs prod tenants have different IPs.
Did the failure start when nothing changed anywhere? Atlan-side incidents (a connector service blip during a nightly cron; a worker version mismatch after an upgrade) have caused exactly this - both resolved by support without customer changes. If steps 1-2 are clean, open a ticket with the run link and say so.
Port-translated PrivateLink connections only failing? Mention that pattern explicitly - it has recurred after connector upgrades. See Special cases.

Miner preflight failures

Symptom. Crawler works; the miner fails at preflight with messages about pg_stat_statements or permission denied.

Fix (needs a DBA/superuser; on RDS/Cloud SQL, via the parameter group / flags plus a reboot):

-- 1. shared_preload_libraries must include pg_stat_statements
--    (server/parameter-group setting + restart)
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
GRANT pg_read_all_stats TO atlan_user;

The Atlan user itself does not need superuser - the extension just has to be installed by someone who has it.

Opening ticket that gets solved fast

Include these six things - they usually turn a multi-day exchange into one reply:

Your Atlan tenant URL and the failing workflow run link
Connectivity method (internet / PrivateLink / agent) and, for PrivateLink, the VPCE DNS name and listener port in use - flag any port translation
The innermost error text from the workflow logs (not just the wrapper)
Where PostgreSQL runs (RDS/Aurora/Azure/Cloud SQL/self-managed) and its SSL requirement (rds.force_ssl, hostssl rules)
Result of your own nc/psql reachability check
Whether it ever worked, and if so when it stopped - plus any restarts/failovers around that time

Frequently asked questions

Can Atlan crawl future tables created by any user?

PostgreSQL does not provide a single command to grant access to future tables created by any user on a global level.

You will have to alter the default privileges of every current and future user that creates tables. This is to ensure that the database role you created for integrating with Atlan has access to the tables created by those users by default. For example:

ALTER DEFAULT PRIVILEGES FOR USER <USER_CREATING_TABLES> IN SCHEMA <SCHEMA> GRANT SELECT, REFERENCES ON TABLES TO atlan_user_role;

However, altering the default privileges of every current and future user may not be sustainable or controlled from a single place. To automate the granting of permissions, you can:

Grant function

You can automate the granting of privileges to the database role you created for integrating with Atlan. Note that the function below is located in the public schema. You can use any schema you want to store this function:

Set custom conditions using PL/pgSQL to skip or allow only certain schemas or tables:

CREATE OR REPLACE FUNCTION public.grant_permissions_on_all_schemas()
RETURNS void AS $$
DECLARE
    schema_name text;
BEGIN
    FOR schema_name IN (SELECT nspname FROM pg_namespace WHERE nspname NOT LIKE 'pg_%' AND nspname != 'information_schema')
    LOOP
        EXECUTE format('GRANT USAGE ON SCHEMA %I TO atlan_user_role', schema_name);
        -- grant access to all tables, including views, materialized views
        EXECUTE format('GRANT SELECT, REFERENCES ON ALL TABLES IN SCHEMA %I TO atlan_user_role', schema_name);
    END LOOP;
END;
$$ LANGUAGE plpgsql;

Next, set up a periodic schedule and execute this function on a daily or hourly basis to ensure that the database role has access to all new schemas or tables:
```
select public.grant_permissions_on_all_schemas();
```

Event triggers

You can create an event trigger on any CREATE SCHEMA or CREATE TABLE command. This automation will ensure minimal lag, and you will not have to set up a schedule to run the above grant function.

Note that the event trigger only listens to new create event triggers. You will still need to run the grant function above to ensure that the database role has access to all current schemas or tables.

-- Function to grant permissions on a specific schema
CREATE OR REPLACE FUNCTION public.grant_permissions_on_schema()
RETURNS event_trigger AS $$
DECLARE
    obj record;
BEGIN
    FOR obj IN SELECT * FROM pg_event_trigger_ddl_commands() WHERE command_tag = 'CREATE SCHEMA'
    LOOP
        EXECUTE format('GRANT USAGE ON SCHEMA %I TO atlan_user_role', obj.object_identity);
        RAISE NOTICE 'Granted USAGE on schema % to atlan_user_role', obj.object_identity;
    END LOOP;
END;
$$ LANGUAGE plpgsql;

-- Event trigger for new schemas
CREATE EVENT TRIGGER grant_permissions_on_new_schema ON ddl_command_end
WHEN TAG IN ('CREATE SCHEMA')
EXECUTE FUNCTION public.grant_permissions_on_schema();

-- Function to grant permissions on a specific table
CREATE OR REPLACE FUNCTION public.grant_permissions_on_table()
RETURNS event_trigger AS $$
DECLARE
    obj record;
BEGIN
    FOR obj IN SELECT * FROM pg_event_trigger_ddl_commands() WHERE command_tag = 'CREATE TABLE'
                                                                or command_tag = 'CREATE VIEW'
                                                                or command_tag = 'CREATE TABLE AS'
                                                                or command_tag = 'CREATE MATERIALIZED VIEW'
    LOOP
        EXECUTE format('GRANT SELECT, REFERENCES ON TABLE %s TO atlan_user_role', obj.object_identity);
        RAISE NOTICE 'Granted SELECT, REFERENCES on table % to atlan_user_role', obj.object_identity;
    END LOOP;
END;
$$ LANGUAGE plpgsql;

-- Event trigger for new tables, views, mat views
CREATE EVENT TRIGGER grant_permissions_on_new_table ON ddl_command_end
WHEN TAG IN ('CREATE TABLE', 'CREATE VIEW', 'CREATE TABLE AS', 'CREATE MATERIALIZED VIEW')
EXECUTE FUNCTION public.grant_permissions_on_table();

What databases and schemas does Atlan access?

The connector queries only metadata catalog views—it doesn't read, write, or access data in your actual tables. The connector reads from the following sources during a crawl:

Source	Type	Purpose
`information_schema.schemata`	Standard SQL view	Fetch schema names
`information_schema.tables`	Standard SQL view	Fetch table and view metadata
`information_schema.columns`	Standard SQL view	Fetch column metadata (names, data types, nullability)
`pg_database`	System catalog (`pg_catalog`)	Identify the connected database name

Does Atlan connect to your actual database or only to system catalogs?

The connector connects to the target database you specify in your connection configuration. Once connected, it reads only from information_schema views and the pg_database system catalog—it doesn't access your user-created tables or data.

Quick index​

SSL rejections - "pg_hba.conf ... SSL off" family​

Misleading error wrappers - read the inner error​

Timeouts - connection timeout expired​

IAM authentication failures (RDS/Aurora)​

Wrong hostname after PrivateLink setup​

It worked for months, then broke overnight​

Miner preflight failures​

Opening ticket that gets solved fast​

Frequently asked questions​

Can Atlan crawl future tables created by any user?​

What databases and schemas does Atlan access?​

Does Atlan connect to your actual database or only to system catalogs?​