Production Deployment

This guide covers production concerns for adapter-first Arkorm applications, including runtime config loading and compiled migrations or seeders.

Runtime configuration

Use the same adapter-first configuration in production that you use during development:

import { createKyselyAdapter, defineConfig } from 'arkormx';
import { Kysely, PostgresDialect } from 'kysely';
import { Pool } from 'pg';

const db = new Kysely<Record<string, never>>({
  dialect: new PostgresDialect({
    pool: new Pool({
      connectionString: process.env.DATABASE_URL,
    }),
  }),
});

export default defineConfig({
  adapter: createKyselyAdapter(db),
  paths: {
    models: './src/models',
    migrations: './database/migrations',
    seeders: './database/seeders',
    factories: './database/factories',
    buildOutput: './dist',
  },
});

Prisma is optional. Add client only when the application still needs Prisma compatibility delegates or client-backed transaction behavior:

export default defineConfig({
  adapter,
  client: () => prisma,
});

Build strategy

Runtime discovery needs access to migration, seeder, factory, and model modules. Preserve their source folder structure in build output:

database/migrations/CreateUsersMigration.ts
dist/database/migrations/CreateUsersMigration.js

With tsdown, use unbundled output:

export default {
  unbundle: true,
};

If you bundle application code into a single file, register classes explicitly instead of relying on directory discovery:

import {
  registerMigrations,
  registerModels,
  registerSeeders,
} from 'arkormx';

registerModels(User, Post);
registerMigrations(CreateUsersTableMigration);
registerSeeders(DatabaseSeeder);

Generated extension policy

• outputExt: 'ts' generates TypeScript when TypeScript is installed.
• Arkorm falls back to JavaScript generation when TypeScript is unavailable.
• Production Node.js normally executes the compiled .js, .cjs, or .mjs output.

For a configured TypeScript source path, Arkorm checks equivalent runtime scripts and paths under paths.buildOutput.

Migration deployment

For adapter-backed migrations:

npx arkorm migrate --all

For the Prisma compatibility workflow, use deploy mode in production:

npx arkorm migrate --all --deploy

Do not run development-oriented Prisma migration commands against production unless that is an intentional part of your deployment process.

Operational checks

• Validate that the production process can load arkormx.config.*.
• Validate database connectivity before accepting traffic.
• Run migrations as a distinct deployment step.
• Verify compiled migration and seeder paths in staging.
• Keep .arkormx/column-mappings.json with the deployment when persisted mappings or enums are enabled.
• Use debug callbacks with sampling or redaction when forwarding query events to production logs.
• Ensure shutdown hooks close the underlying pool or database client.

See Observability and Errors for query events and structured failures.