raster2pgsql(1) PostGIS raster2pgsql(1)

# [NAME](#NAME)

raster2pgsql - raster to postgis loader

# [SYNTAX](#SYNTAX)

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

# [DESCRIPTION](#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](#OPTIONS)

The commandline options are:

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

[**-s**, **--srid** \[<*FROM\_SRID*>:\]<*SRID*>](#s)

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*>](#b)

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*>](#t)

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**](#P)

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

[**-R**, **--register**](#R)

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

[**-d**](#d)

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

[**-a**](#a)

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

[**-c**](#c)

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

[**-p**](#p)

Prepare mode. Only emit SQL to create the table.

[**--if-not-exists**](#if)

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)

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)

Create the target table.

[**--load-data**](#load)

Load raster data into the target table.

[**-f**, **--raster-column** <*column*>](#f)

Specify the name of the raster column.

[**-F**, **--filename**](#F)

Add a column containing the source raster filename.

[**-n**, **--filename-column** <*column*>](#n)

Specify the filename column name. This implies -F.

[**-l**, **--overview-factor** <*overview\_factor*>](#l)

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**](#q)

Wrap PostgreSQL identifiers in quotes.

[**-I**](#I)

Alias for --create-index.

[**--create-index**](#create~2)

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**](#M)

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

[**--vacuum**](#vacuum)

Run VACUUM on the raster table.

[**--analyze**](#analyze)

Run ANALYZE on the raster table.

[**-C**](#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**](#add)

Set the standard raster constraints after the rasters are loaded.

[**-x**, **--no-extent**](#x)

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

[**-r**, **--regular-blocking**](#r)

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

[**-T**, **--tablespace** <*tablespace*>](#T)

Specify the tablespace for the new table.

[**-X**, **--index-tablespace** <*tablespace*>](#X)

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*>](#N)

NODATA value to use on bands without a NODATA value.

[**-k**, **--skip-nodata-check**](#k)

Keep empty tiles by skipping NODATA value checks for each raster band.

[**-E**, **--endian** <*endian*>](#E)

Control endianness of generated binary raster output. Use 0 for XDR and 1 for NDR. Only NDR is currently supported.

[**-V**, **--wkb-version** <*version*>](#V)

Specify the output WKB format version. Only version 0 is currently supported.

[**-e**, **--no-transaction**](#e)

Execute each statement individually instead of wrapping the load in a transaction.

[**-Y**, **--copy** \[<*max\_rows\_per\_copy*>\]](#Y)

Use COPY statements instead of INSERT statements. If no row limit is provided, 50 rows are written per COPY.

[**-G**, **--gdal-formats**](#G)

Print the supported GDAL raster formats.

**-?**, **--help**

Display version and usage information.

# [EXAMPLES](#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](#AUTHORS)

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

# [SEE ALSO](#SEE_ALSO)

[shp2pgsql(1)](/man/enterprise-packages/postgis-17/shp2pgsql.1), [pgsql2shp(1)](/man/enterprise-packages/postgis-17/pgsql2shp.1)

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

---

Document: raster2pgsql(1) from postgis-17 3.7.0-r0 (Chainguard OS)
Source: https://gitea.osgeo.org/postgis/postgis.git