## How Atlan connects to PostgreSQL

URL: https://docs.atlan.com/apps/connectors/database/postgresql/concepts/how-atlan-connects-to-postgresql

> Understand how Atlan securely connects to your PostgreSQL database to extract metadata, with support for multiple authentication methods and deployment modes

Atlan connects to your PostgreSQL database to extract technical metadata while maintaining network security and compliance. You can choose between Direct connectivity for databases available from the internet or Self-deployed runtime for databases that must remain behind your firewall.

## Connect via direct network connection

Atlan's PostgreSQL workflow establishes a direct network connection to your database from the Atlan SaaS tenant. This approach works when your PostgreSQL database can accept connections from the internet.

```mermaid
sequenceDiagram
 participant User as User
 participant Atlan as Atlan SaaS Tenant
 participant PG as PostgreSQL

 User->>Atlan: Provide connection details
 Atlan->>PG: Establish connection
 Atlan->>PG: Execute read-only queries for metadata
 PG-->>Atlan: Return metadata structure
 Atlan->>Atlan: Catalog results in Atlan Cloud
 User->>Atlan: View assets in Atlan
```

Key characteristics of Direct connectivity:

- Atlan connects to your PostgreSQL database from the Atlan SaaS tenant over port 5432 (default PostgreSQL port)
- You provide connection details (hostname, port, credentials) when creating a crawler workflow
- Atlan supports Basic, IAM User, and IAM Role authentication methods
- Atlan executes read-only SQL queries to discover your database structure
- Your PostgreSQL database accepts inbound network connections from Atlan's IP addresses
- All credentials are stored encrypted in Atlan Cloud

## Connect via self-deployed runtime

A runtime service deployed within your network acts as a secure bridge between Atlan Cloud and your PostgreSQL database. This approach works when your PostgreSQL database must remain fully isolated behind your firewall.

```mermaid
sequenceDiagram
 participant User as User
 participant Atlan as Atlan SaaS Tenant
 participant Runtime as Self-Deployed Runtime
 participant SecretStore as Secret Store
 participant PG as PostgreSQL

 User->>Atlan: Configure crawler workflow
 Runtime->>Atlan: Poll for job execution request 
(via outbound HTTPS)
 Runtime->>SecretStore: Request credentials
 SecretStore->>Runtime: Return credentials
 Runtime->>PG: Establish connection
 Runtime->>PG: Execute read-only queries
 PG->>Runtime: Return metadata structure
 Runtime->>Atlan: Send metadata results
 Atlan->>Atlan: Catalog results in Atlan Cloud
 User->>Atlan: View assets in Atlan
```

Key characteristics of Self-deployed runtime:

- A runtime service sits within your network perimeter, deployed on Docker Compose or Kubernetes
- The runtime maintains an outbound HTTPS connection to Atlan Cloud (port 443) and a local network connection to PostgreSQL (port 5432)
- When you create a crawler workflow, Atlan Cloud sends metadata extraction requests to the runtime
- The runtime translates requests into SQL queries, executes them on PostgreSQL, and returns results to Atlan Cloud
- Your PostgreSQL database never exposes ports to the internet—all connections are initiated from within your network

## How it protects your data

PostgreSQL databases contain critical business data and operational information. Atlan's connection architecture protects your environment through multiple security layers.

### Metadata extraction, not data replication

Atlan extracts only structural metadata—databases, schemas, tables, views, columns, and their relationships. The actual business data in your tables remains in your PostgreSQL database.

For example, if you have a `customers` table with customer records, Atlan discovers:
- The table structure (table name, database, schema)
- Column definitions (column names, data types, nullability)
- Relationships (foreign keys, if configured)

Atlan never queries or stores the customer records themselves.

### Read-only operations

All database queries are read-only SELECT statements. The connector can't:
- Modify data (INSERT, UPDATE, DELETE)
- Create or drop database objects
- Change any configuration
- Execute stored procedures or functions
- Grant or revoke permissions

The PostgreSQL user permissions you grant control exactly what the connector can access.

### Credential encryption

PostgreSQL connection credentials are encrypted at rest and in transit:

**Direct connectivity:**
- Credentials are encrypted before storage in Atlan Cloud
- Encryption keys are managed by Atlan's key management system
- Credentials are decrypted only when establishing connections

**Self-deployed runtime:**
- Basic authentication credentials never leave your network perimeter
- The runtime retrieves credentials from your enterprise-managed secret vaults only when needed

### Network isolation with Self-deployed runtime

Your PostgreSQL database gains complete network isolation from the internet:
- The database only accepts connections from the runtime within your local network
- The runtime itself only makes outbound HTTPS connections to Atlan Cloud
- No inbound connections to your network are required
- Your network team can control runtime connectivity through firewall rules

## See also

* [Set up PostgreSQL](https://docs.atlan.com/llms/connectors/postgresql/set-up-postgresql/llms.txt): Configure authentication and permissions
* [Crawl PostgreSQL](https://docs.atlan.com/llms/connectors/postgresql/crawl-postgresql/llms.txt): Configure and run extraction (including Agent deployment)
* [Self-Deployed Runtime architecture](https://docs.atlan.com/llms/platform/self-deployed-runtime/architecture/llms.txt): Core components and data flow
* [Self-Deployed Runtime security](https://docs.atlan.com/llms/platform/self-deployed-runtime/security/llms.txt): Security architecture, authentication, and encryption

---