@venturekit/data

Warning: This package is in active development and not production-ready. APIs may change without notice.

Database and data layer for VentureKit — RDS configuration, migrations, query utilities, and transactions.

Installation

npm install @venturekit/data@dev

Overview

@venturekit/data provides:

• RDS configuration — createRdsConfig(), buildRdsConfig() for PostgreSQL and MySQL
• Migration utilities — createMigrationConfig(), Flyway environment helpers
• Query utilities — query(), getPool(), mapResults(), mapRow()
• Transaction support — beginTransaction(), withTransaction(), buildTransaction()

Query Utilities

import { query, getPool, mapResults } from '@venturekit/data';

// Simple query
const result = await query('SELECT * FROM tasks WHERE id = $1', [taskId]);

// Get the connection pool
const pool = getPool();

// Map results with a custom mapper
const tasks = mapResults(result, row => ({
  id: row.id,
  title: row.title,
  completed: row.completed,
}));

Transactions

import { withTransaction, beginTransaction } from '@venturekit/data';

// Automatic commit/rollback
const result = await withTransaction(async (tx) => {
  await tx.query('INSERT INTO tasks (title) VALUES ($1)', ['New task']);
  await tx.query('UPDATE counters SET count = count + 1 WHERE name = $1', ['tasks']);
  return { created: true };
});

// Manual transaction control
const tx = await beginTransaction();
try {
  await tx.query('INSERT INTO tasks (title) VALUES ($1)', ['New task']);
  await tx.commit();
} catch (error) {
  await tx.rollback();
  throw error;
}

Transactional Handlers

When used with @venturekit/runtime, enable automatic transactions per request:

import { handler } from '@venturekit/runtime';

export const main = handler(async (body, ctx, logger) => {
  // ctx.tx is available — auto-commits on success, rolls back on error
  await ctx.tx.query('INSERT INTO tasks (title) VALUES ($1)', [body.title]);
  return { created: true };
}, { scopes: ['tasks.write'], transactional: true });

RDS Configuration

import { createRdsConfig, DEFAULT_RDS_CONFIG } from '@venturekit/data';

const rdsConfig = createRdsConfig({
  engine: 'postgres',
  instanceSize: 'small',
  databaseName: 'mydb',
});

Migrations

@venturekit/data ships a pure-SQL migration runner. Drop .sql files into db/migrations/ and apply them with the CLI:

vk migrate            # Apply pending schema migrations
vk migrate --seed     # Apply migrations, then seeds from db/seeds/
vk migrate status     # Show which migrations and seeds have been applied

Applied files are tracked in __vk_migrations / __vk_seeds. The file-content hash is locked once recorded — editing an applied file hard-fails on the next run; write a new migration instead.

API Reference

See the API reference for full documentation.

License

Apache-2.0 — see LICENSE for details.