Class GeoPackageConnection

A wrapper around a better-sqlite3 database connection tailored for working with OGC GeoPackage files.

Instances are created through the static factory methods (open, openReadonly, openBuffer, create, and createInMemory) rather than by calling the constructor directly.

Example

// Open an existing GeoPackage for reading and writing
const conn = GeoPackageConnection.open('/path/to/my.gpkg');

// Query a table
const rows = conn.all('SELECT * FROM gpkg_contents');

// Clean up
conn.close();

Properties

`Readonly`filePath

filePath: string | null

The file-system path that was used to open or create the database, or null when the database was created in-memory or from a buffer.

Accessors

isOpen

get isOpen(): boolean
Indicates whether the underlying database connection is currently open.

Returns boolean
true if the connection is open, false if it has been closed.
Example
```
console.log(conn.isOpen); // true
conn.close();
console.log(conn.isOpen); // false
```
- Defined in src/db/connection.ts:642

raw

get raw(): Database
Provides direct access to the underlying better-sqlite3 DatabaseType | Database instance.

Use this escape hatch when you need functionality that is not exposed by the GeoPackageConnection wrapper.

Returns Database
The raw better-sqlite3 database handle.
Example
```
const rawDb = conn.raw;
rawDb.pragma('cache_size = -64000');
```
- Defined in src/db/connection.ts:661

Methods

all

all<T = Record<string, unknown>>(sql: string, ...params: unknown[]): T[]
Executes a SQL query and returns all matching rows as an array.
Type Parameters
- T = Record<string, unknown>
  The expected shape of each row object. Defaults to Record<string, unknown>.
Parameters
- sql: string
  The SQL statement to execute (may contain ? placeholders).
- ...params: unknown[]
  Bind parameters that correspond to the placeholders in sql.
Returns T[]
An array of rows typed as T[]. Returns an empty array when no rows match.
Example
```
const rows = conn.all<{ table_name: string }>(
  'SELECT table_name FROM gpkg_contents',
);
```
- Defined in src/db/connection.ts:210

close

close(): void
Closes the database connection if it is currently open.

Calling this on an already-closed connection is a no-op.

Returns void
Example
```
conn.close();
console.log(conn.isOpen); // false
```
- Defined in src/db/connection.ts:603

columnExists

columnExists(tableName: string, columnName: string): boolean
Checks whether a specific column exists in the given table.
Parameters
- tableName: string
  The name of the table to inspect.
- columnName: string
  The column name to look for.
Returns boolean
true if the column exists in the table, false otherwise.
Example
```
if (conn.columnExists('my_layer', 'geom')) {
  // column is present
}
```
- Defined in src/db/connection.ts:366

count

count(tableName: string, where?: string, ...params: unknown[]): number
Returns the number of rows in a table, optionally filtered by a WHERE clause.
Parameters
- tableName: string
  The name of the table to count rows in.
- Optionalwhere: string
  An optional SQL WHERE clause without the WHERE keyword (e.g. "name = ?").
- ...params: unknown[]
  Bind parameters for the WHERE clause.
Returns number
The row count, or 0 if the table is empty / no rows match.
Example
```
// Total rows
const total = conn.count('gpkg_contents');

// Filtered rows
const features = conn.count('gpkg_contents', 'data_type = ?', 'features');
```
- Defined in src/db/connection.ts:323

dropTable

dropTable(tableName: string): void
Drops a table from the database if it exists.

This executes DROP TABLE IF EXISTS so it will not throw when the table is absent.
Parameters
- tableName: string
  The name of the table to drop.
Returns void
Example
```
conn.dropTable('temp_features');
```
- Defined in src/db/connection.ts:420

enableForeignKeys

enableForeignKeys(): void
Enables SQLite foreign-key constraint enforcement on this connection.

This is called automatically by all writable factory methods (open, openBuffer, create, createInMemory).

Returns void
Example
```
conn.enableForeignKeys();
```
- Defined in src/db/connection.ts:509

enableWAL

enableWAL(): void
Switches the database journal mode to WAL (Write-Ahead Logging).

WAL mode can improve concurrency and write performance. It is not enabled by default because the GeoPackage specification does not require it.

Returns void
Example
```
conn.enableWAL();
```
- Defined in src/db/connection.ts:525

exec

exec(sql: string): void
Executes one or more SQL statements that do not return data.

Unlike run, this method accepts multiple semicolon-separated statements and does not support bind parameters.
Parameters
- sql: string
  One or more SQL statements to execute.
Returns void
Throws
If any statement is invalid or fails.
Example
```
conn.exec(`
  CREATE TABLE foo (id INTEGER PRIMARY KEY);
  CREATE TABLE bar (id INTEGER PRIMARY KEY);
`);
```
- Defined in src/db/connection.ts:277

export

export(): Buffer
Serialises the entire database to a Buffer.

This is especially useful for in-memory databases created with createInMemory or openBuffer when you need to persist or transmit the resulting GeoPackage.

Returns Buffer
A Buffer containing the full SQLite database image.
Example
```
const conn = GeoPackageConnection.createInMemory();
// ... populate ...
const buf = conn.export();
writeFileSync('out.gpkg', buf);
```
- Defined in src/db/connection.ts:626

get

get<T = Record<string, unknown>>(
sql: string,
...params: unknown[],
): T | undefined
Executes a SQL query and returns the first matching row, or undefined if the result set is empty.
Type Parameters
- T = Record<string, unknown>
  The expected shape of the returned row object. Defaults to Record<string, unknown>.
Parameters
- sql: string
  The SQL statement to execute (may contain ? placeholders).
- ...params: unknown[]
  Bind parameters that correspond to the placeholders in sql.
Returns T | undefined
The first row as T, or undefined when no rows match.
Example
```
interface ContentRow { table_name: string; data_type: string }
const row = conn.get<ContentRow>(
  'SELECT * FROM gpkg_contents WHERE table_name = ?',
  'my_layer',
);
```
- Defined in src/db/connection.ts:188

getApplicationId

getApplicationId(): number
Reads the current SQLite application_id pragma value.

Returns number
The 32-bit application ID stored in the database header.
Example
```
const id = conn.getApplicationId();
console.log(id === 0x47504B47); // true for a valid GeoPackage
```
- Defined in src/db/connection.ts:455

getUserVersion

getUserVersion(): number
Reads the current SQLite user_version pragma value.

For a GeoPackage this typically encodes the specification version (e.g. 10200 for version 1.2.0).

Returns number
The user version integer stored in the database header.
Example
```
const ver = conn.getUserVersion();
console.log(ver); // e.g. 10200
```
- Defined in src/db/connection.ts:492

iterate

iterate<T = Record<string, unknown>>(
sql: string,
...params: unknown[],
): IterableIterator<T>
Executes a SQL query and returns a lazy IterableIterator over the result rows. This is more memory-efficient than all for large result sets.
Type Parameters
- T = Record<string, unknown>
  The expected shape of each row object. Defaults to Record<string, unknown>.
Parameters
- sql: string
  The SQL statement to execute (may contain ? placeholders).
- ...params: unknown[]
  Bind parameters that correspond to the placeholders in sql.
Returns IterableIterator<T>
An iterable iterator yielding rows typed as T.
Example
```
for (const row of conn.iterate<{ id: number }>('SELECT id FROM big_table')) {
  process.stdout.write(`${row.id}\n`);
}
```
- Defined in src/db/connection.ts:256

maxOfColumn

maxOfColumn(tableName: string, columnName: string): number | null
Returns the maximum value of a numeric column in the given table.
Parameters
- tableName: string
  The name of the table to query.
- columnName: string
  The name of the column whose maximum value is desired.
Returns number | null
The maximum value, or null if the table is empty or all values are NULL.
Example
```
const maxLat = conn.maxOfColumn('my_layer', 'max_y');
```
- Defined in src/db/connection.ts:402

minOfColumn

minOfColumn(tableName: string, columnName: string): number | null
Returns the minimum value of a numeric column in the given table.
Parameters
- tableName: string
  The name of the table to query.
- columnName: string
  The name of the column whose minimum value is desired.
Returns number | null
The minimum value, or null if the table is empty or all values are NULL.
Example
```
const minLat = conn.minOfColumn('my_layer', 'min_y');
```
- Defined in src/db/connection.ts:384

prepare

prepare(sql: string): Statement
Prepares a SQL statement for repeated execution.

The returned Statement can be executed multiple times with different parameters, which is more efficient than calling run or get in a loop.
Parameters
- sql: string
  The SQL statement to prepare (may contain ? placeholders).
Returns Statement
A compiled better-sqlite3 Statement.
Example
```
const stmt = conn.prepare('INSERT INTO my_table (name) VALUES (?)');
stmt.run('Alice');
stmt.run('Bob');
```
- Defined in src/db/connection.ts:298

registerFunction

registerFunction(
    name: string,
    fn: (...args: unknown[]) => unknown,
    options?: { deterministic?: boolean; varargs?: boolean },
): void
Registers a custom scalar SQL function on this database connection.
Parameters
- name: string
  The name of the SQL function (used in queries).
- fn: (...args: unknown[]) => unknown
  The JavaScript implementation of the function. Receives SQL values as arguments and must return a SQL-compatible value.
- Optionaloptions: { deterministic?: boolean; varargs?: boolean }
  Optional configuration for the function.
  - Optionaldeterministic?: boolean
    When true (the default), SQLite may cache return values for identical inputs.
  - Optionalvarargs?: boolean
    When true, the function accepts a variable number of arguments. Defaults to false.
Returns void
Example
```
conn.registerFunction('double', (x: unknown) => (x as number) * 2);
const row = conn.get<{ val: number }>('SELECT double(21) as val');
console.log(row?.val); // 42
```
- Defined in src/db/connection.ts:552

run

run(sql: string, ...params: unknown[]): RunResult
Executes a SQL statement that modifies data (INSERT, UPDATE, DELETE) and returns information about the changes made.
Parameters
- sql: string
  The SQL statement to execute (may contain ? placeholders).
- ...params: unknown[]
  Bind parameters that correspond to the placeholders in sql.
Returns RunResult
A RunResult containing changes (number of rows affected) and lastInsertRowid.
Example
```
const result = conn.run(
  'INSERT INTO my_table (name) VALUES (?)',
  'hello',
);
console.log(result.changes); // 1
```
- Defined in src/db/connection.ts:233

setApplicationId

setApplicationId(id?: number): void
Sets the SQLite application_id pragma.

By default this writes the GeoPackage magic number (0x47504B47, i.e. the ASCII string GPKG).
Parameters
- id: number = APPLICATION_ID
  The application ID to write. Defaults to APPLICATION_ID (0x47504B47).
Returns void
Example
```
conn.setApplicationId(); // sets the standard GPKG application ID
```
- Defined in src/db/connection.ts:440

setUserVersion

setUserVersion(version?: number): void
Sets the SQLite user_version pragma.

By default this writes the GeoPackage specification version number (10200, representing version 1.2.0).
Parameters
- version: number = USER_VERSION
  The user version to write. Defaults to USER_VERSION (10200).
Returns void
Example
```
conn.setUserVersion(); // sets user_version to 10200
```
- Defined in src/db/connection.ts:474

tableExists

tableExists(tableName: string): boolean
Checks whether a table with the given name exists in the database.
Parameters
- tableName: string
  The name of the table to look for.
Returns boolean
true if the table exists, false otherwise.
Example
```
if (conn.tableExists('gpkg_extensions')) {
  // handle extensions
}
```
- Defined in src/db/connection.ts:344

transaction

transaction<T>(fn: () => T): T
Wraps the given function in a SQLite transaction.

All statements executed inside fn are committed atomically. If fn throws, the transaction is rolled back.
Type Parameters
- T
  The return type of the wrapped function.
Parameters
- fn: () => T
  A synchronous function containing the operations to run inside the transaction.
Returns T
The value returned by fn.
Throws
Re-throws any error raised inside fn after rolling back.
Example
```
conn.transaction(() => {
  conn.run('INSERT INTO my_table (name) VALUES (?)', 'Alice');
  conn.run('INSERT INTO my_table (name) VALUES (?)', 'Bob');
});
```
- Defined in src/db/connection.ts:587

`Static`create

create(path: string): GeoPackageConnection
Creates a new GeoPackage file at the given path.

If a file already exists at path it will be opened (and potentially overwritten depending on subsequent operations). Foreign-key enforcement is enabled automatically.
Parameters
- path: string
  Absolute or relative path where the .gpkg file should be created.
Returns GeoPackageConnection
A new GeoPackageConnection instance.
Throws
If the path is not writable.
Example
```
const conn = GeoPackageConnection.create('./output/new.gpkg');
conn.setApplicationId();
conn.setUserVersion();
```
- Defined in src/db/connection.ts:135

`Static`createInMemory

createInMemory(): GeoPackageConnection
Creates a new GeoPackage database entirely in memory.

The database can later be serialised to a Buffer with export. Foreign-key enforcement is enabled automatically. The resulting connection's filePath will be null.

Returns GeoPackageConnection
A new in-memory GeoPackageConnection instance.
Example
```
const conn = GeoPackageConnection.createInMemory();
conn.setApplicationId();
// ... populate tables ...
const buffer = conn.export();
```
- Defined in src/db/connection.ts:159

`Static`open

open(path: string): GeoPackageConnection
Opens an existing GeoPackage file for reading and writing.

Foreign-key enforcement is enabled automatically.
Parameters
- path: string
  Absolute or relative path to the .gpkg file.
Returns GeoPackageConnection
A new GeoPackageConnection instance.
Throws
If the file does not exist or cannot be opened.
Example
```
const conn = GeoPackageConnection.open('./data/countries.gpkg');
```
- Defined in src/db/connection.ts:60

`Static`openBuffer

openBuffer(buffer: Buffer): GeoPackageConnection
Opens a GeoPackage from an in-memory Buffer.

This is useful when a GeoPackage has been fetched over the network or read from a non-file source. Foreign-key enforcement is enabled automatically.

The resulting connection's filePath will be null.
Parameters
- buffer: Buffer
  A Buffer containing the raw bytes of a GeoPackage (SQLite) database.
Returns GeoPackageConnection
A new GeoPackageConnection instance backed by the buffer.
Throws
If the buffer does not contain a valid SQLite database.
Example
```
import { readFileSync } from 'node:fs';
const buf = readFileSync('./data/countries.gpkg');
const conn = GeoPackageConnection.openBuffer(buf);
```
- Defined in src/db/connection.ts:109

`Static`openReadonly

openReadonly(path: string): GeoPackageConnection
Opens an existing GeoPackage file in read-only mode.

Foreign-key enforcement is not enabled because the database cannot be modified.
Parameters
- path: string
  Absolute or relative path to the .gpkg file.
Returns GeoPackageConnection
A new read-only GeoPackageConnection instance.
Throws
If the file does not exist or cannot be opened.
Example
```
const conn = GeoPackageConnection.openReadonly('./data/countries.gpkg');
const rows = conn.all('SELECT * FROM gpkg_contents');
```
- Defined in src/db/connection.ts:83

Class GeoPackageConnection

Example

Index

Properties

Accessors

Methods

Properties

ReadonlyfilePath

Accessors

isOpen

Returns boolean

Example

raw

Returns Database

Example

Methods

all

Type Parameters

Parameters

Returns T[]

Example

close

Returns void

Example

columnExists

Parameters

Returns boolean

Example

count

Parameters

Returns number

Example

dropTable

Parameters

Returns void

Example

enableForeignKeys

Returns void

Example

enableWAL

Returns void

Example

exec

Parameters

Returns void

Throws

Example

export

Returns Buffer

Example

get

Type Parameters

Parameters

Returns T | undefined

Example

getApplicationId

Returns number

Example

getUserVersion

Returns number

Example

iterate

Type Parameters

Parameters

Returns IterableIterator<T>

Example

maxOfColumn

Parameters

Returns number | null

Example

minOfColumn

Parameters

Returns number | null

Example

prepare

Parameters

Returns Statement

Example

registerFunction

Parameters

`Readonly`filePath

`Optional`deterministic?: boolean

`Optional`varargs?: boolean

`Static`create

`Static`createInMemory

`Static`open

`Static`openBuffer

`Static`openReadonly