DEV Community: LuxQuant

A Critical Analysis of Kysera: Why This Project Exists

LuxQuant — Fri, 12 Dec 2025 15:05:10 +0000

Preface: On Honesty

This article is not marketing material. It does not attempt to convince you that Kysera is the best solution for all tasks. Instead, it presents a critical analysis: what problems led to the creation of Kysera, what place it occupies among existing solutions, and for which cases it is actually suitable.

If after reading this you decide that Kysera is not for you — that is a normal and possibly correct conclusion.

The Landscape of Problems

Developer Pain Points in Large Projects

Working with databases in production systems comes with recurring problems that are independent of the chosen tool:

Architectural Problems:

Transactions distributed across multiple services or layers
Soft delete that needs to be applied everywhere but is easy to forget
Audit trail requiring uniformity across all write operations
Row-Level Security for multi-tenant applications
Graceful shutdown and connection pool management

Operational Problems:

Database errors that are hard to understand without knowing PostgreSQL/MySQL codes
Health checks and connection state monitoring
Slow queries that need to be found and profiled
Testing with transaction isolation

Typing Problems:

Generated<T> fields that exist on read but not on write
Validation schemas for create/update that differ from the entity type
Error types that get lost in unknown

How Different Tools Solve These Problems

Prisma

Approach: Full abstraction. Prisma hides SQL behind a declarative schema and generated client.

Strengths:

Excellent DX for simple CRUD operations
Automatic migrations from schema
Built-in relations and nested queries
Type-safe client out of the box

Weaknesses:

Generated code is a black box
Complex queries require $queryRaw, losing typing
Limited control over SQL
Soft delete requires middleware, which is not obvious
Query engine as a separate process (or WASM) adds overhead
Migrations are tied to Prisma, difficult to exit

Philosophy: "We know better how to work with databases. Trust the abstraction."

TypeORM

Approach: Classic ORM with decorators, Active Record or Data Mapper.

Strengths:

Familiar patterns for developers from the Java/C# world
Support for multiple databases
Entity lifecycle management
Query Builder for complex cases

Weaknesses:

Decorators and metadata are runtime magic
Identity Map creates non-obvious state
Lazy loading is a source of N+1 problems
Typing is often lost in complex queries
Migrations require synchronization with entities

Philosophy: "ORM should manage the lifecycle of entities."

Drizzle

Approach: Type-safe schema-first query builder with ORM-like API.

Strengths:

Excellent typing from schema
SQL is close to the surface
Lightweight (no runtime engine)
Relational queries for simple JOINs

Weaknesses:

Schema in code, not in the database (requires synchronization)
Smaller ecosystem/plugins than Prisma
Relational queries are not full-fledged relations
Complex queries still need raw SQL

Philosophy: "Type safety matters more than abstraction. SQL is not the enemy."

Knex

Approach: Query builder without ORM pretensions.

Strengths:

Simple and clear API
Migrations as code
Support for multiple dialects
Minimal overhead

Weaknesses:

Weak typing (from the pre-TypeScript-first era)
No validation
No plugin system
Every project writes its own utilities

Philosophy: "A query builder is all you need."

Kysely

Approach: Type-safe query builder for TypeScript.

Strengths:

Full query typing
SQL as a first-class citizen
Zero runtime overhead
Predictable SQL output

Weaknesses:

Only a query builder — no data access patterns
No validation
No plugin system
No utilities for production (health, retry, pagination)
Every project implements soft delete differently

Philosophy: "Type-safe SQL. Nothing more, nothing less."

Kysera's Position

What Kysera Does NOT Attempt to Do

Before talking about what Kysera does, it's important to understand what it deliberately avoids:

Does not replace Kysely. Kysera is a layer on top of Kysely, not an alternative. You can always use Kysely directly.
Is not an ORM. No entity mapping, Unit of Work, Identity Map, lazy loading. These patterns are a source of complexity that Kysera rejects.
Does not hide SQL. Queries are written in Kysely, SQL remains visible and predictable.
Does not impose architecture. Repository or DAL — the choice is yours. You can use both.
Does not solve all problems. Kysera focuses on specific pain points, not on trying to be "everything for everyone."

What Kysera Does

Kysera provides a toolkit for solving recurring problems in database work:

Plugin System with Query Interception

Instead of remembering about soft delete in every query:

// Without Kysera — easy to forget
const users = await db
  .selectFrom('users')
  .selectAll()
  .where('deleted_at', 'is', null)  // Forgot? You'll get deleted users
  .execute();

// With Kysera — applied automatically
const executor = await createExecutor(db, [softDeletePlugin()]);
const users = await executor
  .selectFrom('users')
  .selectAll()
  .execute();  // WHERE deleted_at IS NULL added automatically

This works through Proxy-based interception — the same approach used by middleware in Express or interceptors in Axios.

Dual API: Repository and Functional DAL

Repository — for structured CRUD with validation:

const userRepo = orm.createRepository(createUserRepository);
const user = await userRepo.create({
  email: 'test@example.com',
  name: 'Test'
});
// Validation, typing, plugins — all out of the box

Functional DAL — for complex queries with composition:

const getUserWithStats = createQuery(async (ctx, id: number) => {
  const user = await ctx.db
    .selectFrom('users')
    .selectAll()
    .where('id', '=', id)
    .executeTakeFirst();

  const stats = await ctx.db
    .selectFrom('events')
    .select(sql<number>`count(*)`.as('total'))
    .where('user_id', '=', id)
    .executeTakeFirst();

  return { user, stats };
});

Typed Error Handling

Instead of parsing error strings:

// Without Kysera
try {
  await db.insertInto('users').values(data).execute();
} catch (error: unknown) {
  // What is this? UniqueConstraint? ForeignKey? Who knows?
  if (error.message.includes('duplicate')) { /* ... */ }
}

// With Kysera
try {
  await userRepo.create(data);
} catch (error) {
  const dbError = parseDatabaseError(error, 'postgres');
  if (dbError instanceof UniqueConstraintError) {
    // Typed error with constraint name, table, columns
  }
}

Production Utilities

Opt-in packages for production:

// Health checks
const health = await checkDatabaseHealth(db, pool);
// { status: 'healthy', latency: 12, poolMetrics: {...} }

// Retry with exponential backoff
const result = await withRetry(
  () => userRepo.findById(id),
  { maxAttempts: 3, backoff: 'exponential' }
);

// Graceful shutdown
await gracefulShutdown(db, {
  timeout: 30000,
  onClose: () => console.log('DB connections closed')
});

Architectural Decision: Unified Execution Layer

The key architectural decision in Kysera is KyseraExecutor. It's a Proxy wrapper over Kysely that:

Intercepts selectFrom, insertInto, updateTable, deleteFrom
Applies plugins to each query
Propagates plugins into transactions
Maintains zero overhead when no plugins are present

┌─────────────────────────────────────────┐
│  Application Code                       │
│         │                               │
│         ▼                               │
│  ┌─────────────────┐                    │
│  │ KyseraExecutor  │ ← Proxy intercepts │
│  │ (selectFrom)    │   query methods    │
│  └────────┬────────┘                    │
│           │                             │
│           ▼                             │
│  ┌─────────────────┐                    │
│  │ Plugin Chain    │ ← Plugins modify   │
│  │ (interceptors)  │   query builders   │
│  └────────┬────────┘                    │
│           │                             │
│           ▼                             │
│  ┌─────────────────┐                    │
│  │     Kysely      │ ← Original QB      │
│  └────────┬────────┘                    │
│           │                             │
│           ▼                             │
│       Database                          │
└─────────────────────────────────────────┘

This allows plugins to work with both patterns — Repository and DAL — without code duplication.

Honest Comparison

Kysera vs Prisma

Aspect	Prisma	Kysera
Abstraction	High (hides SQL)	Low (SQL visible)
Typing	Generated from schema	From Kysely + DB schema
Soft delete	Middleware (not obvious)	Plugin (explicit)
Complex queries	`$queryRaw` (loses types)	Kysely (preserves types)
Bundle size	~2MB (with engine)	~30KB (all packages)
Lock-in	High	Low (can fall back to Kysely)

When Prisma is better:

Quick start with simple CRUD
Team doesn't want to think about SQL
Need automatic migrations from schema

When Kysera is better:

Complex queries make up a significant part of the project
SQL control is important
Bundle size is critical
Need gradual migration or exit capability

Kysera vs Drizzle

Aspect	Drizzle	Kysera
Schema source	Code (schema.ts)	Database
Plugin system	No	Yes
Repository pattern	No	Optional
Error handling	Generic	Typed errors
Production utils	Partial	Full set (opt-in)

When Drizzle is better:

You prefer schema-first approach
Relational queries cover your JOINs
You don't need plugins

When Kysera is better:

Schema in DB (database-first)
Need soft delete, audit, RLS as plugins
Production utilities are important

Kysera vs "Just Kysely"

This is the most important question: why Kysera if Kysely exists?

Problem	Kysely	Kysely + Kysera
Soft delete	Manual WHERE in every query	Plugin automatically
Audit trail	Your own implementation	Plugin with full history
RLS	Manual filtering	Plugin with AsyncLocalStorage
Error parsing	`try/catch` + strings	Typed errors
Pagination	Your own implementation	Offset + cursor out of the box
Health checks	Your own implementation	@kysera/infra
Retry logic	Your own implementation	@kysera/infra
Validation	Your own integration	Built-in (Zod, Valibot, etc.)
Testing	Your own isolation	Transaction rollback helpers

Conclusion: Kysera is a codification of best practices that every team otherwise writes from scratch.

A Critical Look at Kysera

Weaknesses

1. Additional Abstraction

Every layer of abstraction is:

A potential place for bugs
A need to study documentation
A dependency on maintainers

For simple projects, the overhead may not pay off.

2. Smaller Ecosystem Than Prisma

Prisma has a huge ecosystem: Prisma Studio, Prisma Accelerate, integrations with all frameworks. Kysera is a young project with a smaller community.

3. Two Patterns — Potential Confusion

Repository and DAL in the same project can create inconsistency if the team doesn't agree on conventions.

4. Plugin Dependencies

Plugins have execution order and dependencies. Wrong order can lead to unexpected behavior.

When NOT to Use Kysera

Simple CRUD project — Prisma or even raw Kysely will be simpler.
Team doesn't know SQL — Kysera doesn't hide SQL, this is a deliberate choice.
Need entity lifecycle — Kysera rejects these patterns. If you need Identity Map or Unit of Work — look at TypeORM.
Maximum DX matters more than control — Prisma gives better out-of-the-box experience for simple cases.
You already have a working solution — Migration for migration's sake doesn't make sense.

Who is Kysera For?

The "Ideal" User Profile

Kysera is created for developers who:

Understand SQL and want to control it
Work on production systems with reliability requirements
Value explicitness over magic
Prefer composition over inheritance
Want opt-in functionality, not "all-inclusive"
Use TypeScript with strict mode

Typical Scenarios

1. Multi-tenant SaaS

RLS plugin + AsyncLocalStorage for automatic filtering by tenant_id.

2. Applications with Audit Requirements

Audit plugin for full change history with restore capability.

3. Complex Domain-Driven Applications

Functional DAL for complex queries + Repository for CRUD.

4. Microservices with Shared Database Patterns

Plugins as reusable packages between services.

The Philosophy of "Start minimal, grow as needed, stay transparent"

Start Minimal

Minimal installation — only @kysera/core (8KB):

npm install kysely @kysera/core

You get error handling and pagination. Everything else is opt-in.

Grow as Needed

As your project grows, add what you need:

# Need soft delete?
npm install @kysera/soft-delete

# Need audit?
npm install @kysera/audit

# Need health checks?
npm install @kysera/infra

Stay Transparent

Every operation:

Generates predictable SQL
Can be debugged via @kysera/debug
Has no hidden state
Works in transactions the same as outside them

Conclusion: An Honest Assessment

Kysera is not a revolution in data access. It is an evolutionary solution to specific problems that arise when scaling TypeScript projects with relational databases.

Strengths:

Solves real production problems (soft delete, audit, RLS, error handling)
Preserves SQL control through Kysely
Modular architecture — take only what you need
Low lock-in — can fall back to pure Kysely
Plugin system for reusing patterns

Weaknesses:

Additional abstraction over Kysely
Smaller ecosystem than Prisma
Requires understanding of SQL
Young project

Verdict:

If you:

Already use or are planning to use Kysely
Work on a production system
Want plugins for cross-cutting concerns
Value explicit over implicit

...then Kysera is worth considering.

If you need maximum DX with minimal SQL, or you're working on a simple project — Prisma or Drizzle might be a better fit.

Kysera doesn't try to be the best solution for everyone. It tries to be the right solution for a certain class of problems.

Appendix: Links for Further Reading

Kysely Documentation — the foundation on which Kysera is built
Kysera Documentation — quick start in 5 minutes

Xec - Write Once, Execute Anywhere: Universal Shell Commands in TypeScript

LuxQuant — Tue, 29 Jul 2025 13:14:16 +0000

Have you ever wished you could write shell scripts in TypeScript with the same ease as bash, but with type safety, better error handling, and the ability to seamlessly execute commands across SSH, Docker, and Kubernetes? Meet Xec - the universal command execution system that's changing how we think about shell automation.

The Problem: Context Switching Hell

As developers, we constantly switch between different execution contexts:

Running commands locally during development
SSHing into production servers for debugging
Executing commands in Docker containers
Managing Kubernetes pods

Each context traditionally requires different tools, APIs, and mental models. What if there was a better way?

Enter Xec: One API to Rule Them All

import { $ } from '@xec-sh/core';

// Same syntax, different contexts
await $`echo "Hello from local machine"`;

const server = $.ssh({ host: 'prod.example.com' });
await server`echo "Hello from SSH"`;

const container = $.docker({ container: 'my-app' });
await container`echo "Hello from Docker"`;

const pod = $.k8s({ namespace: 'production' }).pod('web-app');
await pod.exec`echo "Hello from Kubernetes"`;

That's it. Same API, same syntax, different execution environments. No more context switching.

🎯 Key Features That Make Xec Special

1. Template Literal Magic with Auto-Escaping

Remember the nightmare of escaping shell arguments? Xec handles it automatically:

const filename = "my file with spaces & special chars.txt";
const content = "Hello $USER";

// Variables are automatically escaped
await $`echo ${content} > ${filename}`;
// Executes: echo 'Hello $USER' > 'my file with spaces & special chars.txt'

// Need raw shell interpretation? Use .raw
await $.raw`echo $HOME`;  // Shell interprets $HOME

2. Intelligent Connection Pooling

Xec automatically manages connections for optimal performance:

const remote = $.ssh({ 
  host: 'server.com',
  username: 'deploy',
  privateKey: '~/.ssh/id_rsa'
});

// These commands reuse the same SSH connection
for (const service of ['nginx', 'app', 'redis']) {
  const status = await remote`systemctl status ${service}`;
  console.log(`${service}: ${status.stdout.includes('active') ? '✅' : '❌'}`);
}

// Connection automatically closed when done

3. Real-World Error Handling

Unlike traditional shell scripts, Xec provides robust error handling:

// Don't throw on non-zero exit codes
const result = await $`grep "pattern" file.txt`.nothrow();
if (!result.isSuccess()) {
  console.log('Pattern not found, using default...');
  await $`echo "default content" > file.txt`;
}

// Automatic retries for flaky commands
await $`curl https://api.example.com/webhook`.retry({
  maxAttempts: 3,
  backoff: 'exponential',
  initialDelay: 1000
});

// Set timeouts
try {
  await $`npm install`.timeout(30000);
} catch (error) {
  console.error('Installation took too long!');
}

4. Streaming and Real-Time Output

Handle large outputs and long-running processes efficiently:

// Stream output in real-time
await $`npm install`.stream();

// Custom stream processing
await $`tail -f /var/log/app.log`.pipe(line => {
  if (line.includes('ERROR')) {
    console.error(`🚨 ${line}`);
  }
});

// Process large files line by line
let errorCount = 0;
await $`find . -name "*.log"`.pipe(async (file) => {
  const errors = await $`grep -c ERROR ${file}`.nothrow();
  if (errors.stdout) {
    errorCount += parseInt(errors.stdout);
  }
});
console.log(`Total errors found: ${errorCount}`);

🛠 Real-World Use Cases

1. Multi-Environment Deployment Script

#!/usr/bin/env xec

import { $ } from '@xec-sh/core';
import { confirm, select } from '@clack/prompts';

// Select deployment environment
const env = await select({
  message: 'Choose deployment environment',
  options: [
    { value: 'staging', label: 'Staging' },
    { value: 'production', label: 'Production ⚠️' }
  ]
});

// Run tests first
console.log('🧪 Running tests...');
await $`npm test`;

// Build the application
console.log('🔨 Building application...');
await $`npm run build`;

// Deploy based on environment
if (env === 'staging') {
  // Direct SSH deployment for staging
  const staging = $.ssh({ host: 'staging.example.com' });
  await staging`cd /app && git pull`;
  await staging`npm install --production`;
  await staging`pm2 restart app`;
} else {
  // Kubernetes deployment for production
  const shouldContinue = await confirm({
    message: 'Deploy to PRODUCTION?'
  });

  if (shouldContinue) {
    const k8s = $.k8s({ namespace: 'production' });

    // Build and push Docker image
    await $`docker build -t myapp:${Date.now()} .`;
    await $`docker push myapp:latest`;

    // Update Kubernetes deployment
    await k8s`kubectl set image deployment/web app=myapp:latest`;
    await k8s`kubectl rollout status deployment/web`;
  }
}

console.log('✅ Deployment complete!');

2. Database Backup Across Environments

import { $ } from '@xec-sh/core';
import { parallel } from '@xec-sh/core';

async function backupDatabase(env: string, config: any) {
  const timestamp = new Date().toISOString().split('T')[0];
  const filename = `backup-${env}-${timestamp}.sql`;

  if (config.type === 'ssh') {
    // Backup remote PostgreSQL
    const remote = $.ssh(config);
    await remote`pg_dump ${config.database} | gzip > /backups/${filename}.gz`;
    await remote.downloadFile(`/backups/${filename}.gz`, `./backups/${filename}.gz`);
  } else if (config.type === 'k8s') {
    // Backup from Kubernetes pod
    const pod = $.k8s(config).pod(config.podName);
    await pod.exec`pg_dump ${config.database} > /tmp/${filename}`;
    await pod.copyFrom(`/tmp/${filename}`, `./backups/${filename}`);
    await $`gzip ./backups/${filename}`;
  }

  return filename;
}

// Backup all databases in parallel
const databases = [
  { env: 'prod-us', type: 'ssh', host: 'db1.us.example.com', database: 'app_prod' },
  { env: 'prod-eu', type: 'ssh', host: 'db1.eu.example.com', database: 'app_prod' },
  { env: 'prod-k8s', type: 'k8s', namespace: 'production', podName: 'postgres-0', database: 'app' }
];

const results = await parallel(
  databases.map(db => () => backupDatabase(db.env, db)),
  { maxConcurrent: 2 }
);

console.log('Backups completed:', results);

3. Container Management and Debugging

import { $ } from '@xec-sh/core';

class ContainerDebugger {
  async debug(containerName: string) {
    const container = $.docker({ container: containerName });

    // Check if container is running
    const isRunning = await $`docker ps --format "{{.Names}}" | grep -q ${containerName}`.nothrow();

    if (!isRunning.isSuccess()) {
      console.log('Container not running, starting it...');
      await $`docker start ${containerName}`;
    }

    // Gather debug information
    console.log('\n📊 Container Stats:');
    await container`df -h`.stream();

    console.log('\n🔍 Running Processes:');
    await container`ps aux`.stream();

    console.log('\n🌐 Network Connections:');
    await container`netstat -tulpn`.stream();

    console.log('\n📝 Recent Logs:');
    await $`docker logs --tail 50 ${containerName}`.stream();

    // Interactive shell if needed
    const shouldEnterShell = await confirm({
      message: 'Enter interactive shell?'
    });

    if (shouldEnterShell) {
      // This will give you an interactive shell
      await $`docker exec -it ${containerName} /bin/bash`.stdio('inherit');
    }
  }
}

const debugger = new ContainerDebugger();
await debugger.debug('my-app');

4. Advanced SSH Tunneling and Port Forwarding

import { $ } from '@xec-sh/core';

// Setup SSH tunnel for database access
async function setupDatabaseTunnel() {
  const jumpHost = $.ssh({
    host: 'bastion.example.com',
    username: 'admin'
  });

  // Create tunnel through bastion to internal database
  const tunnel = await jumpHost.tunnel({
    localPort: 5432,
    remoteHost: 'postgres.internal',
    remotePort: 5432
  });

  console.log(`Database available at localhost:${tunnel.localPort}`);

  // Now you can connect to the database locally
  await $`psql -h localhost -p ${tunnel.localPort} -U dbuser -d myapp -c "SELECT version();"`;

  // Tunnel automatically closes when done
  return tunnel;
}

// Kubernetes port forwarding
async function debugKubernetesPod() {
  const k8s = $.k8s({ namespace: 'production' });
  const pod = k8s.pod('web-app-7d4b8c-x2kl9');

  // Forward multiple ports
  const forwards = await Promise.all([
    pod.portForward(8080, 80),    // HTTP
    pod.portForward(8443, 443),   // HTTPS
    pod.portForward(9229, 9229)   // Node.js debugger
  ]);

  console.log('Pod ports forwarded:');
  console.log(`- HTTP: http://localhost:${forwards[0].localPort}`);
  console.log(`- HTTPS: https://localhost:${forwards[1].localPort}`);
  console.log(`- Debugger: chrome://inspect at localhost:${forwards[2].localPort}`);
}

🏗 Architecture That Scales

Xec's architecture is built on a simple but powerful adapter pattern:

// Core execution engine
interface ExecutionAdapter {
  execute(command: string, options?: ExecutionOptions): ProcessPromise;
  dispose(): Promise<void>;
}

// Specialized adapters extend the base
class SSHAdapter extends BaseAdapter {
  private connectionPool: SSHConnectionPool;
  // Manages SSH connections, tunnels, and file transfers
}

class DockerAdapter extends BaseAdapter {
  private containerManager: ContainerManager;
  // Handles container lifecycle and Docker operations
}

class KubernetesAdapter extends BaseAdapter {
  private k8sClient: K8sClient;
  // Manages kubectl commands and port forwarding
}

This design allows for:

Easy addition of new execution environments
Consistent behavior across all adapters
Optimal resource management per environment

🚀 Getting Started

Installation

# Install the CLI globally
npm install -g @xec-sh/cli

# Install the core library for your project
npm install @xec-sh/core

Your First Xec Script

Create deploy.ts:

#!/usr/bin/env xec

import { $ } from '@xec-sh/core';

// Build and test locally
await $`npm test`;
await $`npm run build`;

// Deploy to staging
const staging = $.ssh({ host: 'staging.myapp.com' });
await staging`cd /app && git pull && npm install`;
await staging`pm2 restart all`;

console.log('✅ Deployed to staging!');

Make it executable and run:

chmod +x deploy.ts
./deploy.ts

🤝 Why Xec Matters

In an era of microservices, containers, and distributed systems, we need tools that match our mental models. Xec brings:

Unified Mental Model: Think about what you want to do, not how to do it in each environment
Type Safety: Catch errors at compile time, not in production
Modern JavaScript: Use async/await, destructuring, and all ES2022+ features
Better Error Handling: No more silent failures or cryptic exit codes
Developer Experience: Auto-completion, inline documentation, and familiar APIs

🎯 What's Next?

Xec is actively developed and has an exciting roadmap:

AI Integration: Natural language to command translation
Workflow Engine: Define complex multi-step operations declaratively
Cloud Provider Adapters: Native AWS, GCP, Azure command execution
Performance Monitoring: Built-in metrics and tracing

🏁 Conclusion

Shell scripting doesn't have to be stuck in the 1970s. With Xec, you get the simplicity of shell commands with the power of TypeScript, all wrapped in a universal API that works everywhere.

Whether you're automating deployments, managing infrastructure, or building complex DevOps workflows, Xec provides the foundation for reliable, maintainable, and enjoyable shell automation.

Give it a try and let us know what you think!

Links:

Star us on GitHub if you find Xec useful! ⭐