How to Import an External PostGIS Table into Geobble

Geobble can create a managed Source from a spatial table stored in an external PostGIS database. Provide a PostgreSQL connection string, identify the schema, table and geometry column, choose how many rows to import, and select the Geobble Collection that should contain the resulting Source.

The current workflow imports the selected data into Geobble. It does not create a permanently live connection to the external table. Changes made later in the remote PostGIS table are therefore not automatically reflected in the imported Source.

Before you start

You need:

• access to an external PostgreSQL/PostGIS database;

• a connection string that Geobble can use to reach that database;

• the schema containing the spatial table;

• the table name;

• the name of its geometry column;

• permission to read the required table;

• an editable Geobble Collection for the resulting Source;

• sufficient Geobble credits for the import operation.

It is useful to verify the table in PostgreSQL or another GIS/database client before importing it.

In particular, make sure you know exactly which table and geometry column you intend to use.

Importing is different from a live database connection

The current PostGIS workflow copies data from the external table into a managed Geobble Source.

Conceptually:

External PostGIS
      │
      │ SELECT spatial rows
      ↓
PostGIS import
      ↓
Managed Geobble Source

After the import finishes, Geobble works with the managed Source it created.

It does not continuously query the external PostGIS table whenever the Source is viewed.

This distinction matters if the original database changes frequently. Updating the remote table does not, by itself, update the already imported Geobble Source.

If you instead have a GIS file that you want to upload, use How to Create a Source from a Supported GIS File.

1. Open the PostGIS import workflow

From the Sources area, open the workflow for creating a Source from PostGIS.

The page is labelled PostGIS source and describes the action as importing a spatial table into a managed Geobble Source.

2. Enter the Source title

Enter the name that the imported dataset should have inside Geobble.

For example:

Douala Road Network

or:

Cameroon Health Facilities

The title identifies the Geobble Source. It does not need to be identical to the PostgreSQL table name.

For example, a database table named:

cmr_health_facilities_2025_clean

could become:

Cameroon Health Facilities

inside Geobble.

Choose a title that describes the data rather than the implementation details of the database.

3. Choose the Source slug

The slug forms part of the Source's stable Geobble URL.

For example:

cameroon-health-facilities

The slug accepts lowercase letters, numbers and hyphens.

Geobble can also generate a slug from the Source title.

Use a durable identifier rather than a temporary database-oriented name such as:

test-import-4

if the Source is intended for continued use.

4. Add a description

Describe what is being imported and enough context for somebody encountering the resulting Source later.

For example:

Health-facility locations from the organisation's PostGIS database, imported for spatial accessibility and mapping workflows.

Where relevant, the eventual Source metadata should also document:

• where the original data came from;

• its reference date;

• geographic coverage;

• licence or redistribution restrictions;

• known limitations;

• relevant processing that occurred before import.

The connection itself does not provide this catalogue context automatically.

5. Choose the Collection

Select the Geobble Collection that should contain the imported Source.

You must be able to edit that Collection.

For example:

Transport Data
    ├── Roads
    ├── Bus Stops
    └── Railway Stations

If you are importing a road table, Transport Data may be an appropriate Collection.

Choose based on how the Source belongs within your catalogue rather than where it happens to live in the remote database.

Geobble will reject the operation if you cannot write to the selected Collection.

6. Enter the PostgreSQL connection string

The Connection String field identifies the remote database and supplies the credentials required to reach it.

The current workflow accepts connection strings using either:

postgres://

or:

postgresql://

A typical structure is:

postgresql://username:[email protected]:5432/geodata?sslmode=require

The connection string must include at least:

• the database host;

• the database name.

In most practical configurations it will also contain a username, password and port.

The form masks the connection string while you enter it.

Use dedicated database credentials where possible

The credentials need sufficient permission to read the table being imported.

As a database-security practice, prefer a dedicated account with only the access required for the import rather than supplying an administrative PostgreSQL account.

For example, if Geobble only needs to read:

public.health_facilities

a database user with appropriate CONNECT, schema access and SELECT permissions is preferable to a superuser.

Do not use production administrator credentials merely because they are convenient.

TLS is required

Geobble requires the PostGIS connection to use TLS.

The supported sslmode values are:

require
verify-ca
verify-full

For example:

?sslmode=require

A connection specifying an unsupported non-TLS mode will be rejected.

Where your database infrastructure supports proper certificate verification, stronger verification modes can provide additional assurance beyond basic encrypted transport.

The database must be reachable from Geobble

The PostGIS database is external to Geobble, so Geobble must be able to reach the database host when the import runs.

A database that is accessible only from:

• localhost;

• a private development machine;

• an internal network with no external route;

• a private database endpoint unavailable to Geobble;

cannot be imported simply by providing its connection string.

If your database uses network restrictions or a firewall, make sure its connectivity configuration permits the intended external connection before starting the import.

Do not remove broader database security controls unnecessarily just to make an import succeed.

7. Enter the schema

In Schema, enter the PostgreSQL schema containing the table.

The default value in the Geobble form is:

public

If your table is instead:

transport.roads

enter:

transport

as the schema.

Schema names must use a valid PostgreSQL-style identifier in the current form.

8. Enter the table name

In Table, enter the exact table containing the geographic data.

For:

transport.roads

the table is:

roads

Do not enter the combined schema-qualified name into the Table field.

Use:

Schema: transport
Table:  roads

rather than:

Table: transport.roads

The two fields are supplied separately.

9. Identify the geometry column

In Geometry, enter the name of the PostGIS geometry column.

The current default is:

geom

but your database may use another name such as:

geometry
shape
the_geom

Use the actual geometry column from the remote table.

If you are uncertain, inspect the table schema before importing.

Geobble currently imports only rows where the selected geometry column is not null.

For example, if the table contains:

• id: 1 · name: Hospital A · geom: POINT(...)

• id: 2 · name: Hospital B · geom: NULL

• id: 3 · name: Hospital C · geom: POINT(...)

the row for Hospital B is not included in the spatial import because its selected geometry value is null.

That can cause the imported feature count to be lower than the total row count of the remote table.

10. Choose the row limit

The Rows field limits how many records Geobble imports from the table.

The current default is:

50,000

and the current maximum is:

100,000

The accepted range is therefore:

1–100,000 rows

If the table contains fewer rows than the selected limit, all eligible rows up to the available count can be imported.

If the table contains more rows than the selected limit, the imported Source contains only the first rows returned by the import query up to that limit.

This is important: the row limit is not a geographic or analytical sampling strategy.

If you need a specific subset of a very large database table, prepare an appropriately scoped table or view rather than assuming an arbitrary row limit produces a representative sample.

11. Review the configuration

Before selecting Import PostGIS Source, verify:

• the Source title;

• the Source slug;

• the description;

• the destination Collection;

• the database host and database name;

• the credentials;

• the TLS mode;

• the schema;

• the table;

• the geometry column;

• the row limit.

A small typo can point the operation at the wrong table or make the import fail.

Also check that the selected Source slug does not already belong to another Source in the same Geobble account.

12. Start the import

Select:

Import PostGIS Source

Geobble validates the request and queues the import.

The interface then takes you to the newly created Source.

Conceptually:

PostGIS configuration
        ↓
Import queued
        ↓
PENDING
        ↓
PROCESSING
        ↓
READY

The import is performed asynchronously after the Source has been created.

You do not need to keep the form open while processing continues.

Credits are reserved when the import starts

A PostGIS import requires Geobble processing work.

The current workflow reserves the credits required for:

• ingestion;

• creation of the processed geographic representation;

• generation of the Source's supporting map/data artefacts.

If the billing account does not have enough credits, Geobble rejects the import rather than queueing work that cannot be paid for.

If the PostGIS import subsequently fails during processing, the current processing workflow releases the reserved ingestion credits rather than charging the completed import cost.

What Geobble imports

The current PostGIS importer reads approximately:

SELECT *
FROM schema.table
WHERE geometry_column IS NOT NULL
LIMIT row_limit

You do not enter this SQL yourself.

Its practical implications are important:

• all selected table columns are candidates for import;

• rows with a null selected geometry are excluded;

• the configured row limit is applied;

• no arbitrary SQL query is entered through this workflow.

Geobble then creates a managed Source from the imported rows.

What happens to the geometry?

During processing, Geobble prepares the imported spatial data for use in its managed geospatial environment.

The resulting Source receives Geobble's managed geometry representation and supporting metadata.

This means the imported Source should be treated as a derived managed copy of the selected PostGIS table rather than as a database proxy.

After processing, Geobble records information such as the resulting feature count, fields, geometry type and geographic extent for the Source.

What happens to the original PostGIS table?

The import workflow reads from the remote table.

It creates a separate managed Source in Geobble.

The intended relationship is:

External table
      │
      └── read/import ──→ Geobble Source

rather than:

External table ←→ continuously synchronised Source

Editing the Geobble Source therefore should not be understood as editing the original database table.

Likewise, changing the external table later does not automatically update the already imported Source.

13. Wait for the Source to become ready

While the import runs, the Source progresses through its processing state.

When successful, it reaches READY and Geobble sends a Source-ready notification.

If the import cannot complete, the Source moves to ERROR and the failure is recorded.

See How to Monitor Source Processing Status for the general Source-status workflow.

14. Inspect the imported Source

Once the Source reaches READY, check the result before using it.

Verify at least:

• the expected geographic area;

• feature count;

• geometry type;

• important fields;

• geographic extent;

• whether the row limit truncated the expected dataset;

• whether features with null geometry were intentionally excluded.

If the external table contained 80,000 valid spatial rows but you imported with:

Rows: 50,000

a ready Source containing roughly 50,000 features is not evidence of a processing failure.

It reflects the limit you requested.

A successful connection does not guarantee a correct Source

There are several distinct stages:

Can Geobble reach the database?
        ↓
Can the credentials read the table?
        ↓
Does the requested schema/table exist?
        ↓
Does the geometry column exist?
        ↓
Can the spatial data be processed?
        ↓
Is the resulting dataset appropriate for your intended use?

Passing one stage does not guarantee the next.

For example, database credentials may be correct while the geometry column name is wrong.

Or the import may complete successfully while the chosen table represents outdated or incomplete data.

Always review the resulting Source.

Common causes of failure

A PostGIS import can fail when:

• the connection string is malformed;

• the host or database name is missing;

• the database cannot be reached from Geobble;

• TLS requirements are not satisfied;

• credentials are incorrect;

• the database user cannot read the table;

• the schema name is wrong;

• the table name is wrong;

• the geometry column is wrong;

• the spatial table cannot be processed as expected.

If the Source reaches ERROR, inspect the available failure information before trying again.

Avoid repeatedly retrying unchanged credentials or configuration.

The broader troubleshooting process is covered in Why a Source Failed to Process.

Should you import from PostGIS or upload a file?

Use PostGIS import when:

• the authoritative working dataset currently lives in PostgreSQL/PostGIS;

• you can provide secure database access;

• importing a managed copy into Geobble fits your workflow.

Use file upload when:

• you already have the dataset as a supported geospatial file;

• direct database access is unnecessary or undesirable;

• you want to transfer a prepared export instead.

Neither approach is universally better.

The important question is what the source of the data actually is and how you intend to maintain it.

Security checklist

Before providing database access:

• Use an appropriate database account for the import.

• Prefer least-privilege, read-oriented credentials.

• Confirm the account can access only the data it needs.

• Use TLS.

• Do not paste credentials into descriptions, article text, Source metadata or other public fields.

• Review whether organisational policy permits external database access.

• Rotate credentials if you believe they have been exposed.

The PostGIS connection string belongs only in the dedicated connection field.

Import checklist

Before import:

• I selected the correct Collection.

• The Source title and description are meaningful.

• The slug is suitable.

• The connection string points to the correct database.

• TLS is configured.

• The database is reachable.

• The schema is correct.

• The table is correct.

• The geometry column is correct.

• The row limit is appropriate.

After import:

• The Source reaches READY.

• The feature count makes sense.

• The geographic extent is correct.

• The expected attributes are present.

• I understand whether the row limit excluded records.

• I have recorded appropriate provenance, date, licence and limitation information.