SQLBraid: TypeScript-native SQL with type safety and no query builders
A SQL-first data access toolkit that preserves raw SQL while adding TypeScript type safety
1SQL-first TypeScript approach
SQLBraid maintains raw SQL visibility while adding TypeScript type safety, avoiding the abstraction layer of traditional query builders. It supports value binding, dynamic SQL composition, and explicit result contracts through SQL template tags. The library works with multiple SQL dialects including PostgreSQL, MySQL, SQLite, and Oracle, providing driver-specific implementations while keeping a consistent API surface.
2Type-safe query execution
Queries are executed with strict result type contracts through methods like db.all, db.one, and db.maybeOne. The system validates result shapes against TypeScript interfaces or Standard Schema definitions. SQLBraid distinguishes between row queries, commands, and stored procedure calls at the type level, preventing mismatches between expected and actual result kinds. Execution options include transaction isolation levels and read-only modes when supported by the underlying adapter.
3Dynamic SQL composition
The library provides structured helpers like sql.ident, sql.fragment, and sql.join for dynamic SQL generation. Conditional SQL fragments use @braid directives that are compiled away, keeping inactive branches lazy. The system maintains immutable RenderedStatement objects where segments and parameters are strictly separated, preventing SQL injection while allowing flexible query construction. Parameter materialization is handled by the selected database adapter.
4Transaction management
SQLBraid offers explicit transaction control through db.tx() with configurable isolation levels and read-only modes. Nested transactions automatically use savepoints when available. The library strictly enforces transaction boundaries, preventing options from being silently changed in nested scopes. Physical connection ownership is clearly separated from logical operations, with pooled databases managing lease acquisition and release.
5Prepared statement handling
The system supports prepared statements with stable SQL shapes that are locked after first execution. Prepared queries can be reused with different parameter values but reject shape changes. SQLBraid distinguishes between input-required and zero-input prepared statements, exposing appropriate execution methods for each case. The library tracks effective statement reuse through adapter-reported metrics.
6Execution observability
Database operations emit lifecycle events including query:ready, query:result, and transaction events. Observers can inspect but not modify execution flow, with events exposing adapter details and diagnostics. Optional OpenTelemetry integration provides DB client spans and operation duration metrics without exposing sensitive bind values. Event timing is captured in milliseconds for performance analysis.
7Driver-specific adaptations
SQLBraid accommodates database-specific behaviors through dedicated adapters. SQLite implementations handle synchronous execution in native drivers while maintaining async API surfaces. Bun's SQL adapter supports multiple dialects but lacks certain features like cancellation. Oracle and SQL Server have specialized handling for output parameters and result sets. Each adapter documents its capabilities and limitations explicitly.
8Runtime compatibility
The toolkit supports Node.js, Bun, Deno, browsers, and Worker environments. It separates dialect semantics from driver protocols, allowing new JavaScript runtimes to use existing driver APIs. SQLBraid requires Node.js 22.18 or newer for certain features. Runtime-specific behaviors like Bun's result metadata and SQLite's synchronous execution are properly abstracted while preserving type safety.
9Standard Schema integration
Applications can attach schema validators to queries or provide them per execution. Mapping follows a strict one-row-to-one-value pattern without ORM-style hydration or identity mapping. The system validates result sets against schemas after execution, preventing type mismatches. Schema validation occurs after physical I/O completion, maintaining clear operation boundaries.
10Connection management
SQLBraid clearly separates physical connection ownership from logical operations. Pooled databases use ConnectionProviders to acquire leases per operation. Sessions maintain consistent physical connections for nested operations. The library prevents connection leakage by enforcing proper handle usage and automatically releasing resources. Applications retain control over pool shutdown procedures.
11Cancellation support
Operations respect AbortSignal for cancellation when the underlying adapter supports it. Unsupported cancellation attempts fail explicitly rather than silently proceeding. Active signals require adapter capability; otherwise operations reject with UnsupportedFeatureError. The system ensures cancellation requests are checked before lease acquisition and physical I/O begins.
12Production-ready stability
With its 1.0.0 release, SQLBraid offers stable public APIs and clear capability boundaries. The library maintains rigorous versioning for certified database/driver/runtime combinations. Changes require fresh certification rather than inheriting from neighboring versions. This approach ensures predictable behavior across environments while allowing for database-specific optimizations where appropriate.