OS Manuals

raster2pgsql(1)

raster2pgsql - raster to postgis loader

raster2pgsql(1) PostGIS raster2pgsql(1)

raster2pgsql - raster to postgis loader

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

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.

The commandline options are:

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

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.
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.
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.
Pad right-most and bottom-most tiles so all tiles have the same width and height.
Register the raster as an out-of-db filesystem raster. Input raster paths must be absolute.
Drop the table, recreate it, and populate it with the raster data.
Append raster data into the existing table. The target table must have the same schema.
Create a new table and populate it. This is the default mode.
Prepare mode. Only emit SQL to create the table.
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 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 the target table.
Load raster data into the target table.
Specify the name of the raster column.
Add a column containing the source raster filename.
Specify the filename column name. This implies -F.
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.
Wrap PostgreSQL identifiers in quotes.
Alias for --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.
Run VACUUM ANALYZE on the raster table. This is most useful when appending to an existing table with -a.
Run VACUUM on the raster table.
Run ANALYZE on the raster table.
Set the standard raster constraints after the rasters are loaded. Some constraints may fail if one or more input rasters violate the constraint.
Set the standard raster constraints after the rasters are loaded.
Disable setting the max extent constraint. Only applies with -C.
Set spatially unique and coverage tile constraints for regular blocking. Only applies with -C.
Specify the tablespace for the new table.
Specify the tablespace for the new table's indexes. This applies to the primary key and the spatial index when -I is used.
NODATA value to use on bands without a NODATA value.
Keep empty tiles by skipping NODATA value checks for each raster band.
Control endianness of generated binary raster output. Use 0 for XDR and 1 for NDR. Only NDR is currently supported.
Specify the output WKB format version. Only version 0 is currently supported.
Execute each statement individually instead of wrapping the load in a transaction.
Use COPY statements instead of INSERT statements. If no row limit is provided, 50 rows are written per COPY.
Print the supported GDAL raster formats.
-?, --help
Display version and usage information.

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

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

shp2pgsql(1), pgsql2shp(1)

More information is available at http://postgis.net

postgis-14 3.7.0-r0 · enterprise-packages · ingested 2026-10-31