raster2pgsql(1)

NAME

raster2pgsql - raster to postgis loader

SYNTAX

raster2pgsql [options] raster [raster ...] [[schema.]table]

DESCRIPTION

The raster2pgsql data loader converts raster files supported by GDAL into SQL suitable for insertion into a PostGIS raster table. Multiple raster files may be passed on the command line, and shell wildcards can be used to select input files.

OPTIONS

The commandline options are:

Long options that take values also accept the --option=value spelling.

-s, --srid [<FROM_SRID>:]<SRID>
    Set the SRID field. If FROM_SRID is given, the input raster is treated as that source SRID before being transformed to SRID. If no SRID is provided, or if SRID is 0, raster metadata is used when possible.

-b, --band <band>
    Index, starting from 1, of the band to extract from the raster. Separate multiple band indexes with commas. Ranges can be written with a dash. If this option is omitted, all bands are extracted.

-t, --tile-size <tile_size>
    Cut each raster into tiles inserted one per table row. The tile size is written as WIDTHxHEIGHT. Use "auto" to let the loader choose a tile size from the first raster and apply it to all rasters.

-P, --pad
    Pad right-most and bottom-most tiles so all tiles have the same width and height.

-R, --register
    Register the raster as an out-of-db filesystem raster. Input raster paths must be absolute.

-d  Drop the table, recreate it, and populate it with the raster data.

-a  Append raster data into the existing table. The target table must have the same schema.

-c  Create a new table and populate it. This is the default mode.

-p  Prepare mode. Only emit SQL to create the table.

--if-not-exists
    Use IF NOT EXISTS for table creation in -c and -p modes. When -I or --create-index is also specified, use IF NOT EXISTS for index creation too. This option cannot be used with -d. Append mode requires an explicit creation action.

--drop-table
    Drop the target table before other actions. With no mode specified, the default create/load actions still apply. In append mode this requires --create-table when data is loaded.

--create-table
    Create the target table.

--load-data
    Load raster data into the target table.

-f, --raster-column <column>
    Specify the name of the raster column.

-F, --filename
    Add a column containing the source raster filename.

-n, --filename-column <column>
    Specify the filename column name. This implies -F.

-l, --overview-factor <overview_factor>
    Create overview tables for the raster. Separate multiple factors with commas. Overview table names follow the pattern o_<overview factor>_<table>. Created overviews are stored in the database and are not affected by -R. If a source raster already has an overview with matching dimensions, that overview is reused.

-q, --quote
    Wrap PostgreSQL identifiers in quotes.

-I  Alias for --create-index.

--create-index
    Create a GiST spatial index on the raster column at the end of this raster2pgsql run. With repeated -a append runs, create the index on the final run or after loading; add --if-not-exists to make reruns tolerate an existing index.

-M  Run VACUUM ANALYZE on the raster table. This is most useful when appending to an existing table with -a.

--vacuum
    Run VACUUM on the raster table.

--analyze
    Run ANALYZE on the raster table.

-C  Set the standard raster constraints after the rasters are loaded. Some constraints may fail if one or more input rasters violate the constraint.

--add-constraints
    Set the standard raster constraints after the rasters are loaded.

-x, --no-extent
    Disable setting the max extent constraint. Only applies with -C.

-r, --regular-blocking
    Set spatially unique and coverage tile constraints for regular blocking. Only applies with -C.

-T, --tablespace <tablespace>
    Specify the tablespace for the new table.

-X, --index-tablespace <tablespace>
    Specify the tablespace for the new table's indexes. This applies to the primary key and the spatial index when -I is used.

-N, --nodata <nodata>
    NODATA value to use on bands without a NODATA value.

-k, --skip-nodata-check
    Keep empty tiles by skipping NODATA value checks for each raster band.

-E, --endian <endian>
    Control endianness of generated binary raster output. Use 0 for XDR and 1 for NDR. Only NDR is currently supported.

-V, --wkb-version <version>
    Specify the output WKB format version. Only version 0 is currently supported.

-e, --no-transaction
    Execute each statement individually instead of wrapping the load in a transaction.

-Y, --copy [<max_rows_per_copy>]
    Use COPY statements instead of INSERT statements. If no row limit is provided, 50 rows are written per COPY.

-G, --gdal-formats
    Print the supported GDAL raster formats.

-?, --help
    Display version and usage information.

EXAMPLES

Load one projected population raster using COPY statements, automatic tiling, and post-load VACUUM ANALYZE: # psql -c "drop table if exists ghs_globe_population_raster;"
# raster2pgsql -M -Y -s 54009 data/mid/ghs/GHS_POP.tif -t auto ghs_globe_population_raster | psql -q

Create an empty raster table first, then append many rasters in parallel. This pattern is useful when loading large raster collections: # psql -c "drop table if exists hrsl_population_raster;"
# raster2pgsql -p -Y -s 4326 data/in/hrsl/*.tif -t auto hrsl_population_raster | psql -q
# find data/in/hrsl -name "*.tif" -type f | parallel --eta 'GDAL_CACHEMAX=10000 GDAL_NUM_THREADS=4 raster2pgsql -a -Y -s 4326 {} -t auto hrsl_population_raster | psql -q'
# psql -c "create index hrsl_population_raster_rast_idx on hrsl_population_raster using gist (ST_ConvexHull(rast));"
# psql -c "vacuum analyze hrsl_population_raster;"

Create and append a tiled raster set from pre-cut tiles. The first tile creates the table definition; the remaining tiles append into it: # ls data/mid/night_lights/*.tif | head -1 | parallel 'raster2pgsql -p -Y -s 4326 {} -t auto night_lights_raster | psql -q'
# ls data/mid/night_lights/*.tif | parallel --eta 'GDAL_CACHEMAX=10000 GDAL_NUM_THREADS=4 raster2pgsql -a -Y -s 4326 {} -t auto night_lights_raster | psql -q'

List the raster formats supported by the GDAL library used by raster2pgsql: # raster2pgsql -G

AUTHORS

Originally written by WKTRaster/PostGIS Raster contributors. Improved and maintained by the PostGIS project.

SEE ALSO

shp2pgsql(1), pgsql2shp(1) More information is available at http://postgis.net