2. Base classes

Foundation: Base Classes

These classes provide the foundation for database interactions in the package. While Models and Repositories offer convenient high-level APIs, the base classes give you direct access to queries, records, and table operations when you need more control.

Query

The Query class allows you to build and execute database queries. It provides methods like Run() for non-SELECT queries, All() and Get() for fetching results, Count() for counting records, and DoesTableExist() for checking table existence.

Example Usage:

import { Query } from '@kirbkis/database-handler-core';

const query = new Query({
  tableName: 'users',
  query: 'SELECT * FROM users WHERE age > @age',
  parameters: { age: 18 },
  adapterName: 'myDatabase',
});

const results = await query.All();
console.log(results);

Note:

The query string should use @paramName placeholders for parameters. Other formats (:param, ?, $1) are not supported at this level — parameter conversion is handled by the adapter.

Parameters:

Parameter	Type	Description	Optional?
tableName	string	The name of the database table to query	No
query	string	The SQL query string with @paramName placeholders	Yes
parameters	object	Key-value pairs for query parameters	Yes
adapterName	string	The name of the database adapter to use	Yes

Methods:

Method	Description
Run()	Execute a non-SELECT query (INSERT, UPDATE, DELETE)
All()	Execute a SELECT query and return all matching rows as Record[]
Get()	Execute a SELECT query and return the first matching row as Record
Count()	Execute a COUNT query and return the result as a number
DoesTableExist()	Check if the table exists in the database
TableColumnInformation(tableName)	Get raw column metadata for a table

---

Record

The Record class represents a single row in a database table. It provides methods to manipulate the record, such as Insert(), Delete(), and Update().

While the actual data is stored in the .values property, the Record class implements custom inspection methods so that console.log(record) displays the data directly rather than the wrapper object. Records also support JSON serialization and can be converted to strings for logging.

Example Usage:

import { Record } from '@kirbkis/database-handler-core';

const record = new Record({
  table: 'users',
  values: { name: 'John Doe', age: 30 },
  adapter: 'myDatabase',
});

await record.Insert();
console.log('Record inserted with ID:', record.values.id);

res.json(record); // Returns the record data as JSON

Parameters:

Parameter	Type	Description	Optional?
table	string	The name of the database table	No
values	object	Key-value pairs representing the record's data	No
adapter	string	The name of the database adapter to use	Yes

Methods:

Method	Description
Insert()	Insert this record into the database; updates values with the inserted row
Update(newValues, whereParameters)	Update this record in the database with new values
Delete(primaryKey?)	Delete this record (performs a soft delete if deleted_at column exists)
toJSON()	Returns the raw values object (used by JSON.stringify)
toString()	Returns a pretty-printed JSON string of the values

---

Table

The Table class provides a high-level interface for common database table operations. It abstracts away SQL syntax by offering methods like FetchRecords() for fetching multiple rows, FetchSingleRecord() for fetching a single row, CreateRecord() for adding data, and FetchJoined() for combining tables. You can also retrieve table metadata, count records, check table existence, inspect generated SQL, and drop tables.

Example Usage:

import { Table } from '@kirbkis/database-handler-core';

const usersTable = new Table({
  name: 'users',
  adapter: 'myDatabase',
});

const allUsers = await usersTable.FetchRecords({
  base: { from: 'users' },
});
console.log(allUsers);

Note:

For more information check the Table class documentation.

Parameters:

Parameter	Type	Description	Optional?
name	string	The name of the database table	No
adapter	string	The name of the database adapter to use	Yes

Methods:

Method	Description
FetchRecords(queryLayers)	Fetch multiple records using structured QueryLayers
FetchSingleRecord(queryLayers)	Fetch a single record (wraps FetchRecords with limit: 1)
RecordsCount()	Get the total count of records in the table
CreateRecord(values)	Insert a new record into the table
FetchJoined(queryLayers)	Perform JOIN operations; nested results split by table
exists()	Check if the table exists in the database
toSql(queryLayers)	Return the SQL string for a query without executing it
Drop()	Drop the table from the database
TableColumnInformation(tableName?)	Get raw column metadata
ReadableTableColumnInformation()	Get human-readable column metadata