Connecting to a PostgreSQL + PostGIS database

intermediate

If your organization already runs PostGIS, you can point a portal map directly at it and skip the import step entirely. Layers read their data on demand by bounding box; rows stay in your database.

When this is the right tool

Use a live PostGIS connection when:

The source data already lives in PostGIS and you don't want to duplicate it into the portal.
The data changes frequently and you want every viewer to see the latest version without an export step.
The tables are very large (millions of rows) and you want the database's GiST index to do the spatial work.

Skip it when:

The data is small and infrequent (just upload a CSV / GeoPackage).
The data is sensitive and you don't want the portal-api to hold connection credentials (use a read-only role with a narrow permission grant).

Setup

Pick PostgreSQL + PostGIS (live) from the New Item page.
Give the connection a name and short description.
Fill in the connection details: - Host — DNS name or IP of your database. - Port — defaults to 5432. - Database — the database name. - Role / username — recommend creating a dedicated read- only role with SELECT-only permissions on the tables you want to expose. A regular login role works too; the portal never issues writes from this connection in Phase 1. - Password — stored encrypted on the server side. The browser never sees it after this form. - Default schema — the schema where the picker looks for tables by default. Other schemas stay reachable from the detail page.
Click Test connection. On success you see the PostGIS version. Fix any errors (firewall, wrong host, wrong password) before continuing.
Click Save connection. The portal probes the schema for geometry tables and registers each one as an available layer.

Adding a layer to a map

Once a connection is registered, you can drop any of its tables onto a map from the Add Layer dialog. Choose your saved connection, pick the table, and the layer appears with the correct geometry type. Every viewport move issues a bounding-box SELECT against the database; only intersecting rows come back.

What gets cached vs read live

Nothing is cached. Every viewport move issues a fresh query. The upside is that an analyst updating a table sees changes on the map within seconds. The downside is that the database needs a GiST index on the geometry column for any reasonable table size; without it the query is a sequential scan and the map will lag.

Permissions and security

The PostGIS connection item itself follows the standard portal sharing model: only viewers with read access to the connection can see layers backed by it.
The password is encrypted at rest using the portal's credential encryption key, the same way an ArcGIS service token is stored.
Every query carries a statement_timeout (10 seconds by default) so a runaway query cannot tie up the database.
The portal-api enforces a hard cap of 5000 features per request so a wide bounding box over a dense table can't fill the browser.
Recommend a dedicated PostgreSQL role with SELECT-only permissions on the registered tables. Do not give it superuser or write privileges.

Limitations in Phase 1

The geometry column must be SRID 4326 (WGS84). Server-side reprojection for other SRIDs ships in Phase 1.5.
Per-table WHERE clauses can be set via the API but the layer panel doesn't expose them yet. The visual WHERE clause builder is planned for Phase 1.5.
Single-instance pool. Cross-replica fanout (so two portal-api instances share connection pools) ships if the user count warrants it.