Query Layer Migration from Prisma to Kysely

Authors

Prathik Shetty

                                                            RFC-DBOPS-0002
                                                            Category: Standards Track
                                                            Status: Draft
                                                            Database Engineering
                                                            March 2026

Status of This Memo

This document specifies a standards-track architecture for migrating the runtime query layer from Prisma Client to Kysely across backend services. Distribution of this memo is unlimited within the organization and to authorized external reviewers.

This document is a DRAFT and is subject to change based on review feedback.

Abstract

This RFC defines the architecture decision to adopt Kysely as the primary query builder for PostgreSQL database operations, replacing Prisma Client for runtime query generation. The decision is motivated by empirical evidence of non-trivial query-layer overhead in the current Prisma path and by the need for finer control over query composition in a multi-tenant, schema-per-tenant environment.

An initial benchmark on the company list retrieval endpoint measured a 46.9% latency reduction when using Kysely (241 ms) compared to the existing Prisma path (454 ms) under controlled conditions. This RFC codifies the architectural constraints, invariants, and phased migration strategy required to replace Prisma Client while preserving type safety, multi-tenant isolation, and feature parity.

The platform currently uses Prisma Client across 134+ query call sites spanning 20 tenant-scoped modules in backend-main. Five separate Prisma generated clients serve three PostgreSQL databases and two MongoDB databases. This RFC concerns the tenant SQL query path only. Prisma Migrate and Atlas remain the schema migration tools. MongoDB clients are unaffected.

Copyright Notice

Copyright (c) 2026 ProficientNow Engineering. All rights reserved.

Changelog

Scope Boundaries

Intended Audience

This document is written for:

• Backend Engineers working on backend-main and tenant-scoped modules
• Platform and Infrastructure Engineers responsible for database connectivity
• Architecture and Review Board
• Tech Leads evaluating query-layer decisions

No prior knowledge of Kysely internals is assumed.

Conventions and Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Table of Contents

Part 1: Foundation

1. Introduction and Motivation

   • 1.1 Background
   • 1.2 Current State
   • 1.3 Benchmark Evidence
   • 1.4 Motivation
   • 1.5 Scope Statement

2. Requirements and Invariants

   • 2.1 Design Goals
   • 2.2 Non-Goals
   • 2.3 Invariants
   • 2.4 Success Criteria

Part 2: Architecture

3. System Architecture

   • 3.1 System Overview
   • 3.2 Authority Domains
   • 3.3 Trust Boundaries
   • 3.4 Stable Interfaces

4. System Components

   • 4.1 Kysely Query Builder
   • 4.2 PostgreSQL Driver and Connection Pool
   • 4.3 Schema-Scoped Dialect
   • 4.4 Relation Hydration Layer
   • 4.5 Prisma Migrate and Atlas (Retained)
   • 4.6 Prisma Client (Sunset Path)

Part 3: Migration Strategy

5. Migration Strategy
   • 5.1 Coexistence Model
   • 5.2 Phase 1 — High-Read Endpoints
   • 5.3 Phase 2 — Complex Query Endpoints
   • 5.4 Phase 3 — Write Operations
   • 5.5 Validation Gates
   • 5.6 Rollback Mechanics

Part 4: Rationale and Evolution

6. Design Rationale

   • 6.1 Why This Section Exists
   • 6.2 Rejected Alternatives

7. Future Considerations

   • 7.1 Future Considerations

Appendices

• Appendix A: Glossary and Indexes
• Appendix B: References

Quick Navigation

Reading Paths

Backend Engineers? Start with Introduction → Requirements → Components → Migration Strategy

Platform / Infra Engineers? Focus on Introduction → Architecture → Components → Glossary

Review Board? Read all sections, especially Requirements (Invariants) → Rationale → Evolution

Understanding Design Decisions? Read Requirements → Rationale → Evolution