## How database connectivity works

URL: https://docs.atlan.com/apps/connectors/database/postgresql/concepts/how-database-connectivity-works

> A plain-language explanation of the journey a connection makes from Atlan to your PostgreSQL database - the three gates it must pass, the three paths it can take, and SSL in one minute.

A plain-language explanation of the journey a connection makes from Atlan to your PostgreSQL database, the gates it must pass, and the three paths it can take. No prior cloud or networking knowledge assumed.

:::info Looking for the architecture view?

[How Atlan connects to PostgreSQL](https://docs.atlan.com/llms/connectors/postgresql/how-atlan-connects-to-postgresql/llms.txt) covers the same connection from the security and data-protection angle - what Atlan reads, how credentials are stored, and the self-deployed runtime architecture. This page covers the network journey and why connections fail.

:::

## Three gates every connection passes

Think of your database as a room inside a building inside a gated campus. A connection from Atlan has to get past three separate checkpoints, owned by different people:

1. **The network firewall** (campus gate) - your cloud security group, on-prem firewall, or load balancer. It only checks *where the connection comes from* (an IP address) and *which door it knocks on* (a port, normally `5432`). Owned by your cloud/network team.
2. **`pg_hba.conf`** (building reception) - PostgreSQL's own access-control list. It checks the source address *again*, plus the username, the database name, and **whether the connection is encrypted with SSL**. A `hostssl` rule means "SSL or nothing." Owned by your database admin (on RDS/Aurora, partly managed by AWS).
3. **Authentication** (the room key) - the password, or on AWS RDS/Aurora optionally an IAM token. Owned by your database admin.

:::caution Why this matters

Failures at gate 1 look like **timeouts**. Failures at gates 2 and 3 both look like **authentication errors** - even when the real problem is a missing SSL setting or an IP that reception doesn't recognize. The error `FATAL: pg_hba.conf rejects connection ... SSL off` is gate 2 rejecting an unencrypted connection; no password would ever have fixed it. The [troubleshooting page](https://docs.atlan.com/llms/connectors/postgresql/troubleshooting-postgresql-connectivity/llms.txt) is organized around exactly this confusion.

:::

## Three traffic paths

![The three traffic paths between your Atlan tenant and your network - the public path from Atlan's egress NAT IPs, the private path over PrivateLink, and the self-deployed agent calling out to Atlan with nothing inbound. On your side every connection passes the three gates: firewall/security group, pg_hba.conf with the SSL check, then password or IAM token](https://docs.atlan.com/img/apps/connectors/database/postgresql/how-tos/postgresql-connectivity-traffic-paths.png)

Paths 1 and 2 are "Direct extraction" - the gates apply in full. Path 3 reverses the direction: the agent inside your network initiates everything.

1. **Internet path.** Atlan's workflows leave through fixed egress (NAT) IP addresses and arrive at your database's public endpoint. You allowlist those IPs at gates 1 and 2. Traffic is TLS-encrypted in transit.
2. **PrivateLink path.** You expose the database through an *endpoint service* (a socket) inside AWS; Atlan creates a *VPC endpoint* (a plug) in its own network that connects to it. Traffic never touches the internet. The plug gets its own DNS name - and **that name, not your database's hostname, goes into the Atlan connection form**. Using the wrong one is a recurring source of mysterious timeouts.
3. **Agent path.** A container you run inside your network does the extraction locally and pushes results to Atlan over outbound HTTPS. No inbound rule, no public endpoint, no private link required.

## SSL in one minute

SSL (also called TLS) encrypts the conversation between Atlan and PostgreSQL. The client asks for it - or doesn't - via a setting called `sslmode`:

| sslmode | Meaning | When to use |
|---|---|---|
| `disable` | Never encrypt | Only for isolated test setups |
| `prefer` | Try plain first, fall back to SSL | Avoid - servers that *require* SSL reject the first plain attempt outright, producing the classic `SSL off` rejection |
| `require` | Always encrypt (no certificate check) | The sensible default for RDS/Aurora and any server with a `hostssl` rule |
| `verify-ca` / `verify-full` | Encrypt and verify the server's certificate | When you have the CA bundle and your policy demands it |

:::danger The most common failure

Server requires SSL (a `hostssl` rule or `rds.force_ssl=1`) + connection arrives without SSL = `FATAL: pg_hba.conf rejects connection for host "...", user "...", database "...", SSL off`, often bundled with `FATAL: PAM authentication failed`. It looks like a password problem. It isn't. Set the connection's SSL mode to `require` and it disappears. Full walkthrough in [troubleshooting](https://docs.atlan.com/llms/connectors/postgresql/troubleshooting-postgresql-connectivity/llms.txt).

:::

## Glossary

For definitions of every term the guides use - `pg_hba.conf`, `hostssl`, `sslmode`, security group, egress/NAT IP, CIDR range, endpoint service, VPC endpoint / VPCE DNS name, NLB, RDS proxy, IAM database authentication, `pg_stat_statements`, preflight checks, self-deployed agent - see the [Network connectivity glossary](https://docs.atlan.com/llms/governance/administration/network-connectivity-glossary/llms.txt).

## See also

- [Choose how Atlan connects to PostgreSQL](https://docs.atlan.com/llms/connectors/postgresql/choose-how-atlan-connects-to-postgresql/llms.txt): Pick the right method before configuring anything
- [Connect over the internet with IP allowlisting](https://docs.atlan.com/llms/connectors/postgresql/connect-over-the-internet-with-ip-allowlisting/llms.txt): Apply this knowledge on the fastest path

---