Skip to main content

How Atlan connects to PostgreSQL

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.

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.

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​