v.out.postgis(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

v.out.postgis 💅✨

okay bestie, gather round, because this is the GRASS GIS User's Manual page for v.out.postgis(1) and it's genuinely iconic. it exports a vector map layer to a PostGIS feature table. that's the whole vibe. let's get into it 🫶

🌸 NAME 🌸

v.out.postgis — Exports a vector map layer to PostGIS feature table. no cap, that's literally the job.

🎀 KEYWORDS 🎀

vector, export, output, PostGIS, simple features, topology, 3D

✨ SYNOPSIS ✨

v.out.postgis
v.out.postgis --help
v.out.postgis [-tl2] input=name  [type=string[,string,...]]
[layer=string]  output=string  [output_layer=name]   [output_link=name]
[options=key=value[,key=value,...]]   [--overwrite]  [--help]
[--verbose]  [--quiet]  [--ui]

💖 FLAGS 💖

  • -t — Do not export attribute table. just the geometry, nothing else, periodt.
  • -l — Export PostGIS topology instead of simple features. topological queen behavior 👑
  • -2 — Force 2D output even if input is 3D. lowkey useful if your input is 3D but literally all the z coordinates are identical, so the 3D is just for show 🙈
  • --overwrite — Allow output files to overwrite existing files. the "i said what i said" flag 💀
  • --help — Print usage summary
  • --verbose — Verbose module output. it will tell you EVERYTHING, and honestly? we love a chatty icon
  • --quiet — Quiet module output
  • --ui — Force launching GUI dialog

🦋 PARAMETERS 🦋

  • input=name [required] — Name of input vector map. required, bestie, don't forget it.
  • type=string[,string,...] — Input feature type
    • Options: point, line, boundary, centroid, area, face, kernel, auto
    • Default: auto
  • layer=string — Layer number or name
    • Default: 1
  • output=string [required] — Name for output PostGIS datasource
    • Starts with 'PG' prefix, eg. 'PG:dbname=grass'
  • output_layer=name — Name for output PostGIS layer
    • If not specified, input name is used
  • output_link=name — Name for output vector map defined as a link to the PostGIS feature table
    • If not specified, the vector link is not created. The link can be also manually created by 'v.external' module.
  • options=key=value[,key=value,...] — Creation options
    • Examples:
      • 'FID=cat': define feature id column 'cat'
      • 'GEOMETRY_NAME=wkb_geometry': define geometry column 'wkb_geometry'
      • 'SPATIAL_INDEX=NO': do not create spatial index on geometry column

🌈 DESCRIPTION 🌈

so v.out.postgis exports an existing GRASS vector map layer to a PostGIS feature table. heads up tho: features without category are skipped. bye bestie 🫶

By default GRASS GIS topological features are converted into simple features (peep the OGC Simple Feature Access specification for the details, iykyk). the -l flag lets you export vector features as topological elements stored in a PostGIS Topology schema instead. and note — topological export requires PostGIS version 2 or later. no version 1 situations, sorry 💀

Additional creation options can be defined by the options parameter:

  • FID=<column> - name of column which will be used as primary key (feature id), default: fid
  • GEOMETRY_NAME=<column> name of column which will be used for storing geometry data in feature table, default: geom
  • SPATIAL_INDEX=YES|NO - enable/disable creating spatial index on geometry column, default: YES
  • PRIMARY_KEY=YES|NO - enable/disable adding primary key on FID column, default: YES
  • SRID=<value> - spatial reference identifier, default: not defined

PostGIS Topology related options (relevant only for the -l flag):

  • TOPOSCHEMA_NAME=<schema name> - name of PostGIS Topology schema, default: topo_<input>
  • TOPOGEOM_NAME=<column> - name of column which will be used for storing topogeometry data in feature table, default: topo
  • TOPO_TOLERANCE=<value> - tolerance for PostGIS Topology schema, see CreateTopology function for details, default: 0
  • TOPO_GEO_ONLY=YES|NO - store in PostGIS Topology schema only data relevant to Topo-Geo data model, default: NO

Creation options are comma-separated pairs (key=value), and the options are case-insensitive. lowkey important: options defined by v.external.out are ignored by v.out.postgis. not me being petty about it, it's just the rules 🙈

v.out.postgis optionally also creates a new vector map in the current mapset if output_link is defined. cute, right? ✨

💜 NOTES 💜

By default v.out.postgis exports vector data as simple features, ie. boundaries and centroids (forming topological areas) become polygons, isles become holes. the geometry of simple feature elements is stored in the PostGIS feature table in the column named "geom". you can change the geometry column name with options=GEOMETRY_NAME=<column>. ngl, if you wanna export vector features as simple features you could alternatively use the PostgreSQL driver from the OGR library through the v.out.ogr module. options, bestie, we love options.

Also note that it's allowed to store in the feature table only features of the same type, ie. mixing of points and lines is not currently possible. the feature type is determined for the output feature table from the first vector feature accessing data sequentially (type=auto). vector features of other types are during export skipped. you can pick your preferable feature type with the type parameter. only single type is currently allowed (check the TODO section for the tea ☕).

v.out.postgis currently supports only three basic output simple feature types: Points, Linestrings and Polygons. also 3D features of the same type are supported, eg. 3D points are exported as PointZ simple feature. Faces are exported as 3D polygons. 3D features are written to the output automatically if the input vector map is 3D. if the -2 flag is given then the output is always 2D (and the z-coordinate is silently ignored for 3D input vector maps 👀).

Multigeometries are not currently supported. Features with the same category are exported as multiple single features. it's giving "one at a time, bestie."

v.out.postgis also allows exporting vector features as topological elements in a PostGIS Topology schema. the PostGIS Topology extension uses three tables to store basic topological elements which form topological objects like areas or isles in GRASS terminology. Nodes (0-dimensional topological elements) are stored in the "node" table, edges (1-dimensional elements) in the "edge" table and faces (2-dimensional elements) in the "face" table. the range, honestly 🔥

  • GRASS nodes are stored in node table
  • GRASS points are stored in node table as regular nodes
  • GRASS centroids are stored in node table as regular nodes ("containing_face" refers to related area)
  • GRASS lines are stored in edge table
  • GRASS boundaries are stored in edge table
  • GRASS areas are stored in face table

Tables node, edge and face are stored in the given topological schema. by default v.out.postgis defines its name as topo_<input>. alternatively, the name for the topology schema can be defined by options=TOPOSCHEMA_NAME=<name>.

🍓 EXAMPLES 🍓

Export Simple Features

Export vector map "urbanarea" as feature table "urbanarea" located in database "grass", schema "public". note that this database schema is automatically used when not defined by the user.

v.out.postgis input=urbanarea output="PG:dbname=grass"

GRASS areas are converted into polygons, isles into holes. we can check the number of created polygons by a simple SQL query below.

db.select driver=pg database=grass \
 sql="SELECT ST_GeometryType(geom) as geom_type, count(*) from urbanarea group by geom_type"
geom_type|count
ST_Polygon|657

Note: same procedure can be done by the v.out.ogr module, eg.

v.out.ogr input=urbanarea output="PG:dbname=grass" format=PostgreSQL

In this case GRASS vector data are exported to a PostGIS database using the OGR library, namely using the PostgreSQL driver. Contrary to the v.out.ogr module, v.out.postgis is using directly the PostGIS data provider which is part of the GRASS vector engine. Besides that, v.out.postgis is optimized for PostGIS export including topological access to the data. it's just built different 💅

Export data into specific database schema

Database schema for storing exported data can be defined by output_layer as <schema_name>.<table_name>. if the specified schema doesn't exist in the database, then it's automatically created. so considerate ✨

Export vector map "bridges" as feature table in database schema "grassout".

v.out.postgis input=bridges output="PG:dbname=grass" output_layer=grassout.bridges

Export data with creation options

Example below demonstrates how to define name for geometry column and disable building spatial index. Spatial reference system is defined by srid identifier which corresponds in this case with EPSG 3358 (North Carolina dataset).

v.out.postgis input=roadsmajor output="PG:dbname=grass" options="GEOMETRY_NAME=wkb_geometry,SPATIAL_INDEX=NO,SRID=3358"

Exported data can be linked as vector map created in the current mapset by specifying the output_link parameter. in the example below vector map "busstopsall" from PERMANENT mapset is exported into "grass" PostGIS database. v.out.postgis after successful export also creates in the current mapset a GRASS vector map as a link to the PostGIS feature table.

v.out.postgis input=busstopsall@PERMANENT output="PG:dbname=grass" output_link=busstopsall_pg

Created link can be checked by v.info:

 v.info busstopsall_pg
...
 |----------------------------------------------------------------------------|
 | Map format:      PostGIS (PostgreSQL)                                      |
 | DB table:        public.busstopsall                                        |
 | DB name:         grass                                                     |
 | Geometry column: geom                                                      |
 | Feature type:    point                                                     |
 | Topology:        pseudo (simple features)                                  |
 |----------------------------------------------------------------------------|
...

Export data without attributes

v.out.postgis allows ignoring attributes when exporting vector features by specifying the -t flag. Command below exports vector features without attributes. The feature will contain only two columns, the fid and geometry column.

v.out.postgis -t input=railroads output="PG:dbname=grass"

Export topological data

By default v.out.postgis exports data as simple features. Flag -l allows exporting data as topological elements instead of simple features. Export topological elements is stored in PostGIS Topology schema.

v.out.postgis -l input=busroutesall output="PG:dbname=grass"

For more info about PostGIS Topology implementation in GRASS see the wiki page.

🧚 TODO 🧚

like, things we're manifesting for the future:

  • Multi-feature export
  • Allow mixed features (points, lines)
  • Support other simple feature types like GeometryCollection and others
  • Implement missing options from v.out.ogr: -a, -s, -c, -p, -n
  • Add options: cats, where

manifesting it into existence, fr fr 🌈

⭐ REQUIREMENTS ⭐

  • PostGIS 2.x or later for topological export (flag -l)

👑 REFERENCES 👑

  • OGC Simple Feature Access specification
  • PostGIS Topology documentation
  • GRASS-PostGIS data provider

to be continued, bestie… 💖

💖 SEE ALSO 💖

okay bestie, if you wanna go deeper (and you should), go peek at these:

  • v.out.ogr — the OGR classic, the og export vibe
  • v.external — link up to external data like it's nothing
  • v.external.out — write out to external formats, main character energy
  • v.in.ogr — and yeah, the import one too, bc the cycle never ends 🔁

also!! there's the PostGIS and PostGIS Topology wiki page over on the GRASS User Wiki — literally go read it, iykyk 🦋

👑 AUTHOR 👑

this whole thing was brought to you by Martin Landa, Czech Technical University in Prague, Czech Republic ✨

and the development was supported by Fondazione Edmund Mach</> and Comune di Trento, Italy — shoutout, no cap 🫶

🌈 SOURCE CODE 🌈

it's right there for you bestie:

  • Available at: v.out.postgis source code (history)

Accessed: Saturday Jan 17 05:41:28 2026 ⭐

and the whole navigation situation, so you never get lost:

  • Main index
  • Vector index
  • Topics index
  • Keywords index
  • Graphical index
  • Full index
© 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual — yeah they've been at this since 2003, iconic behavior fr fr 💅

so that's the whole page babes, GRASS 8.4.2 and this little v.out.postgis(1) manual, all wrapped up 🎀 go export something gorgeous, you've got this 💖

📦 where this page comes from