Import from PostGIS¶

Overview¶

Register spatial tables from a connected PostGIS database as datasets in an AcuGIS Cloud Library folder. You can start in the destination folder for a direct workflow or use Wizard to discover and preview tables before choosing the folder.

PostGIS datasets remain linked to their source tables. AcuGIS Cloud does not copy the table into file storage; reads and permitted edits operate on the source database.

Connect before importing

The PostGIS database must already be configured as a Database Service (pg_service.conf entry). If it is not listed during import, follow Connect to PostGIS first.

Before You Begin¶

Sign in to an active AcuGIS Cloud account.
Confirm that you can add datasets to the destination Library folder.
Have access to a configured PostGIS Database Service.
Confirm that the database role can connect and has USAGE on the required schema and SELECT on the spatial tables.
For editable datasets, confirm that the role has only the required write permissions.
Check that each source table has a geometry column and a correctly assigned spatial reference system.

Changes can affect source data

A registered dataset is a live reference to PostGIS. Edits made through AcuGIS Cloud can change the source table when the database role allows writing. Use a read-only role when users should only view data.

Step-by-Step¶

WebCLIAPI

Import from a Library folder¶

Use this workflow when you already know which folder should contain the registered dataset.

1. Open the destination folder¶

Open My Drive, navigate to the destination Library folder, and click Add Dataset. Select PostGIS Import.

Add Dataset menu in the Westlake Survey folder with PostGIS Import selected

Caption: Starting in a folder fixes the Library destination before you browse the database.

2. Browse a Database Service¶

The PostGIS Import page lists the configured Database Services and their connection details. Find the service that points to the required database, then click Browse.

PostGIS Import page listing configured Database Services with Browse selected

Caption: Browse connects through the selected service and discovers its schemas and spatial tables.

Confirm the database, not just the service name

Review the host, database, and user columns before continuing. Similar service names can point to different environments or provide different permissions.

3. Select a spatial table¶

Review the discovered Schema, Table, Geometry, SRID, and Type values. Locate the table you want to add, then click Register.

Spatial tables page showing schemas, geometry metadata, and Register selected for parks_parks

Caption: Register adds a reference to the selected table without copying its data.

The available actions have different purposes:

Preview — inspect the table before registering it.
Register — create a dataset reference in the current Library folder.
Edit Data — open the source table for editing when the connection has sufficient permissions.

Check geometry metadata

Confirm that the geometry type and SRID match the source data. An SRID of 0, an unexpected type, or missing metadata can prevent correct map placement or display.

4. Name and register the dataset¶

Enter the Vault dataset name that should appear in the Library. Use a clear, unique name, then click Register.

Register dataset dialog with parks_parks entered as the Vault dataset name

Caption: The Library name identifies the dataset in AcuGIS Cloud; it does not rename the source PostGIS table.

Registration is not a data copy

Registering creates a reference to the PostGIS table. Updates in the source database are reflected when the dataset is read again.

5. Verify the dataset¶

Open the registered dataset. Confirm that the features draw in the expected location, inspect several attributes, and verify that the page identifies the dataset as a PostGIS reference.

Registered parks_parks PostGIS dataset showing feature attributes and polygons on a map

Caption: Correct geometry, map location, and attributes confirm that the source table was registered successfully.

If editing is intended, test a safe change using a non-production feature or an approved test table, then confirm the result in PostGIS.

Import with Wizard¶

Use Wizard when you want to discover tables, preview selected data, and choose the Library folder at the end of the workflow.

1. Add a PostGIS source¶

Open Administration, select Wizard, click Add Source, and choose Import from Database. Select an available Database Service and click Discover Tables.

Import from Database dialog with the auroras_customers service selected and Discover Tables available

Caption: Wizard uses a configured Database Service to discover the spatial tables that its database role can access.

2. Select tables to preview¶

Search or filter the discovered tables as needed. Select one or more tables, then click Preview Selected.

Discovered PostGIS tables with parks_parks selected and Preview Selected highlighted

Caption: Geometry type, feature count, and EPSG information help identify the correct table before previewing it.

Select only what you need

Previewing a small set of tables makes the ingest session easier to review. Use the search and geometry-type filter when a database contains many spatial tables.

3. Review the preview and source details¶

Inspect the feature locations on the map. In Details, confirm the connection, database, service name, host, and selected table.

Wizard Add Data workspace previewing parks_parks with its PostGIS source details

Caption: Preview the geometry and verify the source details before adding the reference to a Library folder.

Investigate an incorrect preview

Do not import a table whose features appear in the wrong location or whose source details are unexpected. Return to table selection and verify its SRID, geometry metadata, and Database Service.

4. Choose the Library folder and import¶

Under What would you like to do?, select the destination Library folder, then click Import into Library.

Wizard destination controls with Westlake Survey selected and Import into Library highlighted

Caption: Wizard registers the selected PostGIS table in the chosen Library folder.

5. Verify the Library dataset¶

Open the destination folder and confirm that a dataset was created for each selected table. Click View to inspect its geometry and attributes.

Westlake Survey Library folder showing the imported parks_parks vector dataset

Caption: The registered PostGIS dataset is available from the selected Library folder.

For every selected table, verify the dataset name, feature location, attributes, and intended read or edit behavior.

PostGIS import from the CLI is not covered in this guide. Use one of the Web workflows above.

PostGIS import through the API is not covered in this guide. Use one of the Web workflows above.

Tips¶

Use dedicated database roles

Use a read-only role for display and analysis. Create a separate, narrowly scoped role for workflows that require editing so permissions are easy to audit and revoke.

Use stable dataset names

Choose a Library name that describes the data rather than its temporary environment or owner. The Library name can differ from the PostGIS table name and does not alter the source.

Index spatial and filter columns

Add an appropriate GiST or SP-GiST index to the geometry column and indexes to frequently filtered attributes. Indexes can substantially improve preview and map performance for large tables.

Verify every selected table

A Wizard session can include multiple tables with different geometry, CRS, or permission issues. Open and inspect each resulting dataset instead of treating one successful preview as verification of the entire session.

Coordinate schema changes

Renaming or dropping source columns, tables, schemas, or geometry fields can break registered datasets. Coordinate database migrations with dataset owners and test dependent maps after changes.

Common Problems¶

The Database Service is missing

The connection must be configured before import. Ask an administrator to create or restore the service, or follow Connect to PostGIS, then reopen the import workflow.

The Database Service is unavailable

Test the service connection and verify its host, port, database, credentials, SSL mode, firewall rules, and PostgreSQL pg_hba.conf access. A connection that works from a desktop may still be unreachable from AcuGIS Cloud.

No spatial tables are discovered

Confirm that the database role has USAGE on the schema and SELECT on the tables. Check that the tables have valid geometry columns registered in PostGIS metadata. Ordinary non-spatial tables are not included in this workflow.

The expected schema or table is missing

The selected service may point to the wrong database or use a role with limited access. Verify the service details, exact schema and table names, and the role's permissions.

Preview is empty or times out

Confirm that the table contains non-null geometries and that its geometry metadata is valid. For a large table, add a spatial index and review slow database queries, locks, network latency, and server resource usage.

Features appear in the wrong location

Compare the table's assigned SRID with the coordinates actually stored in its geometry column. Correct invalid source metadata or transform the data in PostGIS; do not assign a different CRS only to make the preview appear plausible.

Registration reports a name conflict

Choose a unique Vault dataset name or a different destination folder. Verify the existing dataset before renaming, replacing, or archiving anything.

The dataset opens but editing fails

Display requires read access, while editing also requires the relevant INSERT, UPDATE, or DELETE privileges and access to sequences, triggers, and related tables. Confirm that the table has a reliable feature identifier and grant only the missing permissions.

Source changes do not appear as expected

Reload the dataset and confirm that it still references the intended service, schema, and table. Database transactions may not be committed, and dependent maps or browser sessions may need to be refreshed.

A source table was changed accidentally

Stop further editing, notify the database owner, and use the database's backup, audit, or point-in-time recovery process as appropriate. Replace the connection with a read-only role before restoring user access.