This driver implements support for access to spatial tables in the OGC GeoPackage format standard The GeoPackage standard uses a SQLite database file as a generic container, and the standard defines:
gpkg_contents, gpkg_spatial_ref_sys, gpkg_geometry_columns)This driver reads and writes SQLite files from the file system, so it must be run by a user with read/write access to the files it is working with.
Starting with GDAL 2.0, the driver also supports reading and writing the following non-linear geometry types :CIRCULARSTRING, COMPOUNDCURVE, CURVEPOLYGON, MULTICURVE and MULTISURFACE
Starting with GDAL 2.0, GeoPackage raster/tiles are supported. See GeoPackage raster documentation page
Starting with GDAL 2.2, the driver is able to create GeoPackage databases following the 1.0/1.0.1, 1.1 or 1.2 versions. For GDAL 2.2, it will automatically adjust to the minimum version required for the features of GeoPackage used. For GDAL 2.3 or later, it will default to 1.2. Explicit version choice can be done by specifying the VERSION dataset creation option.
The driver supports OGR attribute filters, and users are expected to provide filters in the SQLite dialect, as they will be executed directly against the database.
Starting with GDAL 2.0, SQL SELECT statements passed to ExecuteSQL() are also executed directly against the database. If Spatialite is used, a recent version (4.2.0) is needed and use of explicit cast operators AsGPB() is required to transform GeoPackage geometries to Spatialite geometries (the reverse conversion from Spatialite geometries is automatically done by the GPKG driver). It is also possible to use with any Spatialite version, but in a slower way, by specifying the "INDIRECT_SQLITE" dialect. In which case, GeoPackage geometries automatically appear as Spatialite geometries after translation by OGR.
Starting with GDAL 2.2, the "DROP TABLE layer_name" and "ALTER TABLE layer_name RENAME TO new_layer" statements can be used. They will update GeoPackage system tables.
When dropping a table, or removing records from tables, the space they occupied is not immediately released and kept in the pool of file pages that SQLite may reuse later. If you need to shrink the file to its minimum size, you need to issue an explicit "VACUUM" SQL request. Note that this will result in a full rewrite of the file.
Starting with GDAL 2.0, if it has been compiled against Spatialite 4.2 or later, it is also possible to use Spatialite SQL functions. Explicit transformation from GPKG geometry binary encoding to Spatialite geometry binary encoding must be done.
ogrinfo poly.gpkg -sql "SELECT ST_Buffer(CastAutomagic(geom),5) FROM poly"
Starting with Spatialite 4.3, CastAutomagic is no longer needed.
The driver implements transactions at the database level, per RFC 54
When creating a new GeoPackage file, the driver will attempt to force the database into a UTF-8 mode for text handling, satisfying the OGR strict UTF-8 capability. For pre-existing files, the driver will work with whatever it's given.
The following creation options (specific to vector, or common with raster) are available:
Other options are available for raster. See the GeoPackage raster documentation page
(GDAL >=2.0) GDAL uses the standardized
gpkg_metadata and
gpkg_metadata_reference tables to read and write metadata,
on the dataset and layer objects.
GDAL metadata, from the default metadata domain and possibly other metadata domains, is serialized in a single XML document, conformant with the format used in GDAL PAM (Persistent Auxiliary Metadata) .aux.xml files, and registered with md_scope=dataset and md_standard_uri=http://gdal.org in gpkg_metadata. For the dataset, this entry is referenced in gpkg_metadata_reference with a reference_scope=geopackage. For a layer, this entry is referenced in gpkg_metadata_reference with a reference_scope=table and table_name={name of the table}
Metadata not originating from GDAL can be read by the driver and will be exposed as metadata items with keys of the form GPKG_METADATA_ITEM_XXX and values the content of the metadata columns of the gpkg_metadata table. Update of such metadata is not currently supported through GDAL interfaces ( although it can be through direct SQL commands).
The specific DESCRIPTION and IDENTIFIER metadata item of the default metadata domain can be used in read/write to read from/update the corresponding columns of the gpkg_contents table.
The core GeoPackage specification of GeoPackage 1.0 and 1.1 did not support non-spatial tables. This was added in GeoPackage 1.2 as the "attributes" data type.
Starting with GDAL 2.0, the driver allows creating and reading non-spatial
tables with the Aspatial Support
(gdal_aspatial) extension.
Starting with GDAL 2.2, the driver will also, by default, list non spatial tables that are not registered through the gdal_aspatial extension, and support the GeoPackage 1.2 "attributes" data type as well. Starting with GDAL 2.2, non spatial tables are by default created following the GeoPackage 1.2 "attributes" data type (can be controlled with the ASPATIAL_VARIANT layer creation option)
Views can be created and recognized as valid spatial layers if a corresponding record is inserted into the gpkg_contents and gpkg_geometry_columns table.
Starting with GDAL 2.2, in the case of the columns in the SELECT clause of the view acts a integer primary key, then it can be recognized by OGR as the FID column of the view, provided it is renamed as OGC_FID. Selecting a feature id from a source table without renaming will not be sufficient, since due to joins this feature id could appear several times. Thus the user must explicitly acknowledge that the column is really a primary key.
For example:
CREATE VIEW my_view AS SELECT foo.fid AS OGC_FID, foo.geom, ... FROM foo JOIN another_table ON foo.some_id = another_table.other_id
INSERT INTO gpkg_contents (table_name, identifier, data_type, srs_id) VALUES ( 'my_view', 'my_view', 'features', 4326)
INSERT INTO gpkg_geometry_columns (table_name, column_name, geometry_type_name, srs_id, z, m) values ('my_view', 'my_geom', 'GEOMETRY', 4326, 0, 0)
This requires GDAL to be compiled with the SQLITE_HAS_COLUMN_METADATA option and SQLite3 with the SQLITE_ENABLE_COLUMN_METADATA option. Starting with GDAL 2.3, this can be easily verified if the SQLITE_HAS_COLUMN_METADATA=YES driver metadata item is declared (for example with "ogrinfo --format GPKG")
filename.gpkg must not already exist,
as it will be created. For adding new layers into existing geopackage run
ogr2ogr with -update.
% ogr2ogr -f GPKG filename.gpkg abc.shp
filename.gpkg must not already exist, as it will be created.
% ogr2ogr -f GPKG filename.gpkg ./path/to/dir
filename.gpkg must not already exist, as it will be created.
% ogr2ogr -f GPKG filename.gpkg PG:'dbname=mydatabase host=localhost'