Skip to main content
Version: 0.23.1

Introduction to the Platformatic DB Mapper

The Platformatic DB Mapper will inspect a database schema and return an object containing:

  • db — A database abstraction layer from @databases
  • sql — The SQL builder from @databases
  • entities — An object containing a key for each table found in the schema, with basic CRUD operations. See Entity Reference for details.

It exports a function that accepts an object with the following properties:

  • connectionString — The Database connection string
  • poolSize - Maximum number of connections in the connection pool. Defaults to 10.
  • log — A logger object (like Pino)
  • onDatabaseLoad — An async function that is called after the connection is established. It will receive db and sql as parameter.
  • ignore — Object used to ignore some tables from building entities. (i.e. { 'versions': true } will ignore versions table)
  • autoTimestamp — Generate timestamp automatically when inserting/updating records.
  • hooks — For each entity name (like Page) you can customize any of the entity API function. Your custom function will receive the original function as first parameter, and then all the other parameters passed to it.

Code samples

const { connect } = require('@platformatic/sql-mapper')
const { pino } = require('pino')

const logger = pino()

async function onDatabaseLoad (db, sql) {
await db.query(sql`CREATE TABLE pages (
const connectionString =
const mapper = await connect({
log: logger,
ignore: {},
hooks: {
Page: {
find: async function(_find, opts) {
console.log('hook called');
return await _find(opts)
const pageEntity =

await mapper.db.query(mapper.sql`SELECT * FROM pages`)
await mapper.db.find('option1', 'option2')