RASTER2PGSQL(1)

💖 NAME 💖

raster2pgsql — bestie, it loads GDAL supported raster formats into a PostGIS raster table. That's the whole job description and she slays it. 💅

✨ DESCRIPTION ✨

okay so raster2pgsql is a raster loader executable, right? She takes GDAL supported raster formats and turns them into sql that's ready to be loaded into a PostGIS raster table. And not to flex but she can also load folders of raster files and create overviews of rasters. main character behavior honestly. 👑

Since raster2pgsql is compiled as part of PostGIS most often (unless you compile your own GDAL library, look at you go 🧚), the raster types supported by the executable will be the same as those compiled in the GDAL dependency library. Wanna see the list of raster types your particular raster2pgsql supports? Use the -G switch, bestie. 📋 Those should be the same as those provided by your PostGIS install documented here ST_GDALDrivers if you are using the same gdal library for both. iykyk. 🌸

🛠️ SYNOPTIS 🛠️

(yes she's spelled like that, don't perceive it 🙈)

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

Multiple rasters can also be specified using wildcards (*,?). Go off, wildcards. 🦋

👑 OPTIONS 👑

• -s <srid> — Set the raster's SRID. Defaults to 0. If SRID not provided or is 0, raster's metadata will be checked to determine an appropriate SRID. she'll figure it out herself, trust. 🔍
• -b <band> — Index (1-based) of band to extract from raster. For more than one band index, separate with comma (,). Ranges can be defined by separating with dash (-). If unspecified, all bands of raster will be extracted. all of them. every single one. no crumbs left. 🍓
• -t <tile size> — Cut raster into tiles to be inserted one per table row. <tile size> is expressed as WIDTHxHEIGHT. <tile size> can also be "auto" to allow the loader to compute an appropriate tile size using the first raster and applied to all rasters. let her cook. 🔥
• -P — Pad right-most and bottom-most tiles to guarantee that all tiles have the same width and height. symmetry queen. ✨
• -R — Register the raster as an out-of-db (filesystem) raster. Provided raster should have absolute path to the file.
• (-d|a|c|p) — These are mutually exclusive options. pick ONE bestie, you cannot have all four, that's not how this works 💀
  • -d — Drops the table, then recreates it and populates it with current raster data. out with the old, in with the new. 🗑️
  • -a — Appends raster into current table, must be exactly the same table schema. exactly. do not play with her. 😭
  • -c — Creates a new table and populates it, this is the default if you do not specify any options. the no-notes default. 🎀
  • -p — Prepare mode, only creates the table. structure only, no data, we're just setting the vibe. 🏗️
• -f <column> — Specify the name of the raster column.
• -F — Add a column with the filename of the raster. so you never lose track of who's who 🫶
• -n <column> — Specify the name of the filename column. Implies -F.
• -l <overview factor> — Create overview of the raster. For more than one factor, separate with comma (,). Overview table name follows the pattern o_<overview factor>_<table>. Created overview is stored in the database and is not affected by -R. she lives in the db now, she does not care about your filesystem drama. 💅
• -q — Wrap PostgreSQL identifiers in quotes.
• -I — Create a GIST spatial index on the raster column. The ANALYZE command will automatically be issued for the created index. she does the extra step for you, unprovoked. iconic. ⭐
• -M — Run VACUUM ANALYZE on the table of the raster column. Most useful when appending raster to existing table with -a. glow-up for your table. 🌈
• -C — Set the standard set of constraints on the raster column after the rasters are loaded. Some constraints may fail if one or more rasters violate the constraint. ⚠️ no cap, this one can genuinely bounce if your data is messy.
• -x — Disable setting the max extent constraint. Only applied if -C flag is also used.
• -r — Set the constraints (spatially unique and coverage tile) for regular blocking. Only applied if -C flag is also used.
• -T <tablespace> — Specify the tablespace for the new table.

Note that indices (including the primary key) will still use the default tablespace unless the -X flag is also used. don't get got by this one, it's sneaky 🙈

• -X <tablespace> — Specify the tablespace for the table's new index.

This applies to the primary key and the spatial index if the -I flag is used.

• -N <nodata> — NODATA value to use on bands without a NODATA value. giving the void a little name tag 🏷️
• -k — Skip NODATA value checks for each raster band. living dangerously, we love that for you 💀
• -E <endian> — Control endianness of generated binary output of raster. Use 0 for XDR and 1 for NDR (default). Only NDR is supported at this time. so yeah, 1 or nothing, bestie. 🤷
• -V <version> — Specify version of output WKB format. Default is 0. Only 0 is supported at this time. one version, one vibe. 🎀
• -e — Execute each statement individually, do not use a transaction. every statement on its own little journey. 🦋
• -Y — Use COPY statements instead of INSERT statements.
• -G — Print the supported GDAL raster formats. the receipts, the whole roster. 📜
• -? — Display the help screen. when in doubt, ask her directly. 💜

quick vibe check, bestie: -d, -a, -c and -p are mutually exclusive, so choose exactly one or the universe will choose for you (it won't, it'll just be sad 😭). Also -x and -r only do anything if -C is also along for the ride, and -n quietly drags -F in with it. kthxbye. 🫶

and that's the whole page!! this is raster2pgsql, RELEASE: 2.1.2, from way back in April 2014 — shoutout to the PostGIS / GDAL girlies who wrote her, absolute legends, and to whoever owns the copyright and license on this thing, we appreciate you fr fr. 🌸✨💖