Class GeoPackage

The primary class for interacting with a GeoPackage database.

A GeoPackage instance wraps an underlying SQLite database connection and provides high-level methods for reading and writing feature (vector), tile (raster), and attribute data according to the OGC GeoPackage specification.

Instances are typically created via the static factory methods in the GeoPackageManager rather than by calling the constructor directly.

Example

import { GeoPackageManager } from 'geopackage-ts';

// Open an existing GeoPackage
const geoPackage = GeoPackageManager.open('/path/to/data.gpkg');

// List feature tables and query features
const tables = geoPackage.getFeatureTables();
const dao = geoPackage.getFeatureDao(tables[0]);

// Clean up
geoPackage.close();

Constructors

constructor

new GeoPackage(
    name: string,
    path: string | null,
    connection: GeoPackageConnection,
): GeoPackage
Creates a new GeoPackage instance.
Parameters
- name: string
  The logical name of the GeoPackage (e.g. file name without extension).
- path: string | null
  The file-system path to the .gpkg file, or null for in-memory databases.
- connection: GeoPackageConnection
  An already-initialised GeoPackageConnection to the SQLite database.
Returns GeoPackage
- Defined in src/geopackage.ts:82

Properties

`Readonly`name

name: string

The logical name of this GeoPackage, typically derived from the file name (without the .gpkg extension).

`Readonly`path

path: string | null

The file-system path of the GeoPackage, or null when the database resides in memory or was opened from a buffer.

Methods

close

close(): void
Closes the underlying database connection and releases all associated resources.

After calling this method the GeoPackage instance should no longer be used. Any subsequent calls to methods that access the database will fail.

Returns void
Example
```
geoPackage.close();
```
- Defined in src/geopackage.ts:672

createAttributeTable

createAttributeTable(tableName: string, additionalColumns?: UserColumn[]): void
Creates a new attribute (non-spatial) table in the GeoPackage.

This method performs the following steps:
1. Creates the table with an auto-incrementing id primary key column and any additional user-specified columns.
2. Inserts a row into gpkg_contents to register the table with data_type = 'attributes'.
Attribute tables have no geometry column and no SRS association. Their bounding box fields in gpkg_contents are set to null.
Parameters
- tableName: string
  The name for the new attribute table.
- additionalColumns: UserColumn[] = []
  Optional array of extra UserColumn definitions to include beyond the id column. Column indices are automatically reassigned starting at 1. Defaults to [].
Returns void
Example
```
import { GeoPackageDataType } from 'geopackage-ts';

geoPackage.createAttributeTable('metadata', [
  {
    index: 0,
    name: 'key',
    dataType: GeoPackageDataType.TEXT,
    notNull: true,
    defaultValue: null,
    primaryKey: false,
    autoincrement: false,
    unique: true,
  },
  {
    index: 1,
    name: 'value',
    dataType: GeoPackageDataType.TEXT,
    notNull: false,
    defaultValue: null,
    primaryKey: false,
    autoincrement: false,
    unique: false,
  },
]);
```
- Defined in src/geopackage.ts:557

createFeatureTable

createFeatureTable(
    tableName: string,
    geometryColumnName: string,
    geometryType: string,
    srsId: number,
    additionalColumns?: UserColumn[],
    bbox?: BoundingBox,
): FeatureTable
Creates a new feature (vector) table in the GeoPackage.

This method performs the following steps:
1. Ensures the gpkg_geometry_columns metadata table exists.
2. Creates the user-defined feature table with an auto-incrementing id primary key column, a geometry BLOB column, and any additional user-specified columns.
3. Inserts a row into gpkg_contents to register the table.
4. Inserts a row into gpkg_geometry_columns to describe the geometry column.
Parameters
- tableName: string
  The name for the new feature table.
- geometryColumnName: string
  The name of the column that will store geometry BLOBs (e.g. 'geom' or 'geometry').
- geometryType: string
  The OGC geometry type name (e.g. 'POINT', 'LINESTRING', 'POLYGON', 'GEOMETRY').
- srsId: number
  The Spatial Reference System identifier (must already exist in gpkg_spatial_ref_sys). Common values: 4326 (WGS 84), 3857 (Web Mercator).
- additionalColumns: UserColumn[] = []
  Optional array of extra UserColumn definitions to include in the table beyond the id and geometry columns. Column indices are automatically reassigned starting at 2. Defaults to [].
- Optionalbbox: BoundingBox
  Optional bounding box for the contents metadata. When omitted, the bounding box fields in gpkg_contents are set to null.
Returns FeatureTable
The FeatureTable definition describing the newly created table.
Example
```
import { GeoPackageDataType } from 'geopackage-ts';

const featureTable = geoPackage.createFeatureTable(
  'buildings',
  'geom',
  'POLYGON',
  4326,
  [
    {
      index: 0,
      name: 'name',
      dataType: GeoPackageDataType.TEXT,
      notNull: false,
      defaultValue: null,
      primaryKey: false,
      autoincrement: false,
      unique: false,
    },
  ],
  { minX: -180, minY: -90, maxX: 180, maxY: 90 },
);
```
- Defined in src/geopackage.ts:283

createTileTable

createTileTable(
    tableName: string,
    srsId: number,
    bbox: BoundingBox,
    tileMatrices?: TileMatrix[],
): void
Creates a new tile (raster) table in the GeoPackage.

This method performs the following steps:
1. Ensures the gpkg_tile_matrix_set and gpkg_tile_matrix metadata tables exist.
2. Creates the standard tile table with columns id, zoom_level, tile_column, tile_row, and tile_data.
3. Inserts a row into gpkg_contents to register the table.
4. Inserts a row into gpkg_tile_matrix_set with the bounding box and SRS.
5. Inserts rows into gpkg_tile_matrix for each provided tile matrix definition.
Parameters
- tableName: string
  The name for the new tile table.
- srsId: number
  The Spatial Reference System identifier for the tile data. Common values: 3857 (Web Mercator), 4326 (WGS 84).
- bbox: BoundingBox
  The bounding box of the tile data, expressed in coordinates of the specified SRS.
- tileMatrices: TileMatrix[] = []
  Optional array of TileMatrix definitions describing the zoom levels, tile grid dimensions, and pixel sizes. The table_name field of each entry is automatically set to the provided tableName. Defaults to [].
Returns void
Example
```
geoPackage.createTileTable('imagery', 3857, {
  minX: -20037508.342789244,
  minY: -20037508.342789244,
  maxX: 20037508.342789244,
  maxY: 20037508.342789244,
}, [
  {
    table_name: '',
    zoom_level: 0,
    matrix_width: 1,
    matrix_height: 1,
    tile_width: 256,
    tile_height: 256,
    pixel_x_size: 156543.03392804097,
    pixel_y_size: 156543.03392804097,
  },
]);
```
- Defined in src/geopackage.ts:448

export

export(): Buffer
Serialises the entire GeoPackage database to an in-memory buffer.

This is useful for saving an in-memory GeoPackage to disk, sending it over the network, or creating a snapshot of the current database state.

Returns Buffer
A Buffer containing the complete SQLite database file.
Example
```
import { writeFileSync } from 'node:fs';

const buffer = geoPackage.export();
writeFileSync('/path/to/output.gpkg', buffer);
```
- Defined in src/geopackage.ts:692

getAllContents

getAllContents(): Contents[]
Retrieves all rows from the gpkg_contents table.

Returns Contents[]
An array of all Contents records registered in the GeoPackage.
- Defined in src/geopackage.ts:160

getAllSrs

getAllSrs(): SpatialReferenceSystem[]
Retrieves all Spatial Reference System definitions from the GeoPackage.

Returns SpatialReferenceSystem[]
An array of all SpatialReferenceSystem records in gpkg_spatial_ref_sys.
- Defined in src/geopackage.ts:202

getAttributeDao

getAttributeDao(tableName: string): AttributeDao
Creates an AttributeDao for querying and manipulating rows in an existing attribute (non-spatial) table.
Parameters
- tableName: string
  The name of the attribute table. Must already exist in the GeoPackage.
Returns AttributeDao
An AttributeDao bound to the specified table.
Example
```
const attrDao = geoPackage.getAttributeDao('metadata');
for (const row of attrDao.queryForAll()) {
  console.log(row);
}
```
- Defined in src/geopackage.ts:508

getAttributeTables

getAttributeTables(): string[]
Returns the names of all attribute (non-spatial) tables registered in the GeoPackage.

Returns string[]
An array of table names whose data_type is 'attributes' in gpkg_contents.
Example
```
const attributeTableNames = geoPackage.getAttributeTables();
// e.g. ['metadata', 'statistics']
```
- Defined in src/geopackage.ts:131

getContents

getContents(tableName: string): Contents | undefined
Retrieves the gpkg_contents metadata row for a specific table.
Parameters
- tableName: string
  The name of the table to look up in gpkg_contents.
Returns Contents | undefined
The Contents record for the table, or undefined if no entry exists.
Example
```
const contents = geoPackage.getContents('buildings');
if (contents) {
  console.log(contents.data_type); // 'features'
}
```
- Defined in src/geopackage.ts:151

getContentsByType

getContentsByType(dataType: ContentsDataType): Contents[]
Retrieves gpkg_contents rows filtered by data type.
Parameters
- dataType: ContentsDataType
  The content data type to filter by ('features', 'tiles', or 'attributes').
Returns Contents[]
An array of Contents records matching the specified data type.
Example
```
const featureContents = geoPackage.getContentsByType('features');
```
- Defined in src/geopackage.ts:175

getDatabase

getDatabase(): GeoPackageConnection
Returns the underlying GeoPackageConnection for advanced or low-level database operations.

Use this when you need to execute raw SQL or access connection features not exposed through the high-level GeoPackage API.

Returns GeoPackageConnection
The GeoPackageConnection instance backing this GeoPackage.
Example
```
const db = geoPackage.getDatabase();
const rows = db.all('SELECT * FROM gpkg_contents');
```
- Defined in src/geopackage.ts:657

getFeatureDao

getFeatureDao(tableName: string): FeatureDao
Creates a FeatureDao for querying and manipulating rows in an existing feature table.
Parameters
- tableName: string
  The name of the feature table. Must already exist and have a corresponding entry in gpkg_geometry_columns.
Returns FeatureDao
A FeatureDao bound to the specified table.
Throws
GeoPackageError If no geometry column metadata is found for the table.
Example
```
const dao = geoPackage.getFeatureDao('buildings');
for (const feature of dao.queryForGeoJSON()) {
  console.log(feature.properties);
}
```
- Defined in src/geopackage.ts:225

getFeatureTables

getFeatureTables(): string[]
Returns the names of all feature (vector) tables registered in the GeoPackage.

Returns string[]
An array of table names whose data_type is 'features' in gpkg_contents.
Example
```
const featureTableNames = geoPackage.getFeatureTables();
// e.g. ['buildings', 'roads']
```
- Defined in src/geopackage.ts:101

getSrs

getSrs(srsId: number): SpatialReferenceSystem | undefined
Retrieves a Spatial Reference System definition by its identifier.
Parameters
- srsId: number
  The srs_id value as defined in gpkg_spatial_ref_sys.
Returns SpatialReferenceSystem | undefined
The matching SpatialReferenceSystem record, or undefined if not found.
Example
```
const wgs84 = geoPackage.getSrs(4326);
console.log(wgs84?.srs_name); // 'WGS 84 geodetic'
```
- Defined in src/geopackage.ts:193

getTileDao

getTileDao(tableName: string): TileDao
Creates a TileDao for querying and manipulating tiles in an existing tile table.
Parameters
- tableName: string
  The name of the tile table. Must already exist and have a corresponding entry in gpkg_tile_matrix_set.
Returns TileDao
A TileDao bound to the specified table.
Throws
GeoPackageError If no tile matrix set metadata is found for the table.
Example
```
const tileDao = geoPackage.getTileDao('satellite_imagery');
const tile = tileDao.queryForTile(0, 0, 0);
```
- Defined in src/geopackage.ts:399

getTileTables

getTileTables(): string[]
Returns the names of all tile (raster) tables registered in the GeoPackage.

Returns string[]
An array of table names whose data_type is 'tiles' in gpkg_contents.
Example
```
const tileTableNames = geoPackage.getTileTables();
// e.g. ['satellite_imagery', 'elevation']
```
- Defined in src/geopackage.ts:116

indexFeatureTable

indexFeatureTable(tableName: string): void
Creates an RTree spatial index on the geometry column of a feature table.

Building a spatial index significantly improves the performance of bounding-box queries (e.g. FeatureDao.queryWithBoundingBox). The index is registered as a GeoPackage extension following the RTree Spatial Index specification.
Parameters
- tableName: string
  The name of the feature table to index. Must have a corresponding entry in gpkg_geometry_columns.
Returns void
Throws
GeoPackageError If no geometry column metadata is found for the table.
Example
```
geoPackage.indexFeatureTable('buildings');
console.log(geoPackage.isFeatureTableIndexed('buildings')); // true
```
- Defined in src/geopackage.ts:612

isFeatureTableIndexed

isFeatureTableIndexed(tableName: string): boolean
Checks whether an RTree spatial index exists for a feature table.
Parameters
- tableName: string
  The name of the feature table to check.
Returns boolean
true if an RTree spatial index is present for the table's geometry column, false otherwise (including when the table has no geometry column metadata).
Example
```
if (!geoPackage.isFeatureTableIndexed('buildings')) {
  geoPackage.indexFeatureTable('buildings');
}
```
- Defined in src/geopackage.ts:634

queryForGeoJSONFeatures

queryForGeoJSONFeatures(
tableName: string,
): IterableIterator<Feature<Geometry, GeoJsonProperties>>
Queries a feature table and returns all rows as GeoJSON Feature objects.

This is a convenience method that internally creates a FeatureDao and delegates to FeatureDao.queryForGeoJSON.
Parameters
- tableName: string
  The name of the feature table to query.
Returns IterableIterator<Feature<Geometry, GeoJsonProperties>>
An iterable iterator of GeoJSON GeoJSON.Feature objects.
Throws
GeoPackageError If no geometry column metadata is found for the table.
Example
```
for (const feature of geoPackage.queryForGeoJSONFeatures('buildings')) {
  console.log(feature.geometry.type, feature.properties);
}
```
- Defined in src/geopackage.ts:377

Class GeoPackage

Example

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns GeoPackage

Properties

Readonlyname

Readonlypath

Methods

close

Returns void

Example

createAttributeTable

Parameters

Returns void

Example

createFeatureTable

Parameters

Returns FeatureTable

Example

createTileTable

Parameters

Returns void

Example

export

Returns Buffer

Example

getAllContents

Returns Contents[]

getAllSrs

Returns SpatialReferenceSystem[]

getAttributeDao

Parameters

Returns AttributeDao

Example

getAttributeTables

Returns string[]

Example

getContents

Parameters

Returns Contents | undefined

Example

getContentsByType

Parameters

Returns Contents[]

Example

getDatabase

Returns GeoPackageConnection

Example

getFeatureDao

Parameters

Returns FeatureDao

Throws

Example

getFeatureTables

Returns string[]

Example

getSrs

Parameters

Returns SpatialReferenceSystem | undefined

Example

getTileDao

Parameters

Returns TileDao

Throws

Example

getTileTables

Returns string[]

Example

indexFeatureTable

Parameters

Returns void

Throws

Example

isFeatureTableIndexed

`Readonly`name

`Readonly`path