v.out.postgis.1grass man page

v.out.postgis — Exports a vector map layer to PostGIS feature table.


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


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]


Do not export attribute table
Export PostGIS topology instead of simple features
Force 2D output even if input is 3D
Useful if input is 3D but all z coordinates are identical
Allow output files to overwrite existing files
Print usage summary
Verbose module output
Quiet module output
Force launching GUI dialog


input=name [required]
Name of input vector map
Input feature type
Options: point, line, boundary, centroid, area, face, kernel, auto
Default: auto
Layer number or name
Default: 1
output=string [required]
Name for output PostGIS datasource
Starts with ’PG’ prefix, eg. ’PG:dbname=grass’
Name for output PostGIS layer
If not specified, input name is used
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.
Creation options
’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


v.out.postgis exports an existing GRASS vector map layer to PostGIS feature table. Features without category are skipped.

By default GRASS GIS topological features are converted into simple features (see OGC Simple Feature Access specification for details). Flag -l allows to export vector features as topological elements stored in PostGIS Topology schema. Note that topological export requires PostGIS version 2 or later.

Additional creation options can be defined by 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 -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 defails, 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), the options are case-insensitive. Note that options defined by v.external.out are ignored by v.out.postgis.

v.out.postgis optionally also creates a new vector map in the current mapset if output_link is defined.


By default v.out.postgis exports vector data as simple features, ie. boundaries and centroids (forming topological areas) become polygons, isles become holes. Geometry of simple feature elements is stored in PostGIS feature table in the column named "geom". Name of the geometry column can be changed by options=GEOMETRY_NAME=<column>. Note that for exporting vector features as simple features can be alternatively used PostgreSQL driver from OGR library through v.out.ogr module.

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 output feature table from the first vector feature accessing data sequentially (type=auto). Vector features of other types are during export skipped. User can choose preferable feature type by type parameter. Only single type is currently allowed (see Todo section for details).

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 input vector map is 3D. If -2 flag is given then the output is always 2D (z-coordinate is silently ignored for 3D input vector maps).

Multigeometries are not currently supported. Features with the same category are exported as multiple singe features.

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

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 given topological schema. By default v.out.postgis defines its name as topo_<input>. Alternatively, the name for topology schema can be defined by options=TOPOSCHEMA_NAME=<name>.


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 or created polygons by 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"

Note: same procedure can be done by 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 PostGIS database using OGR library, namely using PostgreSQL driver. Contrary to the v.out.ogr module, v.out.postgis is using directly PostGIS data provider which is part of GRASS vector engine. Beside that, v.out.postgis is optimized for PostGIS export including topological access to the data.

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.

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"

Export data without attributes

v.out.postgis allows ignoring attributes when exporting vector features by specifying -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.


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


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


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

See Also

v.out.ogr, v.external, v.external.out, v.in.ogr

See also PostGIS and PostGIS Topology wiki page from GRASS User Wiki.


Martin Landa, Czech Technical University in Prague, Czech Republic (development supported by Fondazione Edmund Mach and Comune di Trento, Italy)

Last changed: $Date: 2015-11-24 09:08:30 +0100 (Tue, 24 Nov 2015) $

Main index | Vector index | Topics index | Keywords index | Full index

© 2003-2016 GRASS Development Team, GRASS GIS 7.0.4 Reference Manual


GRASS 7.0.4 Grass User's Manual