Skip to content

@venturekit/data

Installation

npm install @venturekit/data@dev

What It Provides

RDS Configuration

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

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

Query Utilities

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

const result = await query('SELECT * FROM tasks WHERE id = $1', [taskId]);
const tasks = mapResults(result, row => ({ id: row.id, title: row.title }));

Transactions

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

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

Migration Utilities

Config helpers and the tool-agnostic dispatcher used by vk migrate:

import {
  createMigrationConfig,
  DEFAULT_MIGRATION_CONFIG,
  getFlywayEnv,
} from '@venturekit/data';

Built-in Migration Runner

@venturekit/data ships a pure-SQL migration runner that the CLI uses by default — files in db/migrations/ are applied in lexical order, one per transaction, tracked in the __vk_migrations table along with a content hash:

import {
  runMigrations,
  getMigrationStatus,
  runSeeds,
  getSeedStatus,
  MIGRATIONS_TRACKING_TABLE,   // '__vk_migrations'
  SEEDS_TRACKING_TABLE,        // '__vk_seeds'
} from '@venturekit/data';

await runMigrations({
  config: createMigrationConfig(),
  onApply: (entry) => console.log('applied', entry.filename),
});

Error Classes

Thrown by the migration runner — catch these in CI to fail loudly:

import {
  MigrationToolNotImplementedError,   // unsupported runner selected
  MigrationHashMismatchError,          // applied file was edited after the fact
  MigrationCollisionError,             // duplicate version across dirs
} from '@venturekit/data';

Env-Var Bridges

Hydrate DATABASE_URL from a Secrets Manager secret or an existing connection string at Lambda cold start:

import {
  applyDatabaseUrlToEnv,
  applyDbSecretToEnv,
} from '@venturekit/data';

Mapper Customisation

The default row mapper converts snake_case columns to camelCase properties. Override globally if your schema uses a different convention:

import { configureMapper, getMapperConfig } from '@venturekit/data';

configureMapper({ rename: (col) => col });   // identity (no rename)

Types

RdsOutputs, RdsInfraConfig — RDS infrastructure types
Transaction, ResultsMapper — query and transaction types
RunOptions, RunResult, StatusEntry, SeedRunOptions — runner types
Querier, MapperOptions — mapper customisation types

Dependencies

@venturekit/core — required
pg — PostgreSQL client

Database Guide — setup walkthrough
Handlers — transactional handlers
CLI: migrate — migration commands
API Reference — full type documentation