## DESCRIPTION

v.out.postgis exports an existing GRASS vector map layer to PostGIS feature table.

By default GRASS 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`
- `TOPOSCHEMA_NAME=<schema name>` - name of PostGIS Topology schema (relevant only for -l flag), default: `topo_<input>`
- `SRID=<value>` - spatial reference identifier, default: not defined

Note that options defined by v.external.out are ignored by v.out.postgis.

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

## NOTES

Currently only 2D vector features (points, lines, boundaries and centroids) are supported.

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 as column "geom". Default 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 possible. The feature type is determined for output feature table from the first read vector feature when accessing data sequentially. Vector features of other types are during export skipped.

v.out.postgis also allows to export 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 it's name as `topo_<input>`. Name of 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 dsn="PG:dbname=grass"

GRASS areas are converted into polygons, isles into holes. We can check the number or created polygons by simple SQL query bellow.

    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 v.out.ogr module, eg.

    v.out.ogr input=urbanarea dsn="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 olayer 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 dsn="PG:dbname=grass" olayer=grassout.bridges

### Export data with creation options

Example bellow demonstrates how to define name for geometry column and disable building spatial index.

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

### Link exported data

Exported data can be linked as vector map created in the current mapset by specifying olink 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 GRASS vector map as a link to the PostGIS feature table.

    v.out.postgis input=busstopsall@PERMANENT dsn="PG:dbname=grass" olink=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 to ignore attributes when exporting vector features by specifing -t flag. Command bellow exports vector features without attributes. The feature will contain only two columns, the fid and geometry column.

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

### Export topological data

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

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

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

## TODO

- Multi-feature export
- Allow mixed features (points, lines) - use GeometryCollection

## REQUIREMENTS

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

## REFERENCES

- 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 wiki page.

## AUTHOR

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

Last changed: $Date$