SQL
Real SQL files
Keep schemas and statements readable instead of translating them into a separate query abstraction.
Type-safe database development
Sqldelight turns real SQL into reliable Kotlin APIs
Write schemas and labeled queries in SQL, generate strongly typed Kotlin code, validate migrations during the build and keep database behavior clear across supported platforms.
SQL-first workflow
Kotlin Multiplatform
Apache-2.0 licensed
Compile-time query checks
Generated Kotlin models
About the tool
What is Sqldelight?
Sqldelight is a SQL code generator for Kotlin projects. It reads your database schema and labeled statements, verifies them, then generates typed APIs for application code.
Unlike tools that hide SQL, it keeps the database language visible. Developers can review exact statements, use database-specific features where supported and still receive Kotlin types for parameters and result rows. This makes it suitable for teams that value direct SQL control and predictable generated code.
Current referenceStable release 2.3.2
Primary modelSQL files → Kotlin APIs
Project styleGradle-based source generation
LicenseApache License 2.0
Core capabilities
Features that keep database work explicit
The value comes from combining readable SQL with generated code, build-time verification and a driver model that fits multiple application targets.
KT
Typed Kotlin APIs
Generated functions and result models reduce manual mapping and surface type mistakes during builds.
✓
Compile-time checks
Validate schema references, query shapes and migration steps before application runtime.
KMP
Multiplatform flow
Share database definitions and repository logic while selecting an appropriate driver per target.
IDE
Editor support
Use completion, navigation and refactoring support around SQL files and generated Kotlin code.
DB
Multiple dialects
Work with supported SQLite, MySQL, PostgreSQL and experimental JVM dialect combinations.
↻
Observable queries
Connect query changes to reactive application state with listeners or supported extensions.
M
Versioned migrations
Maintain ordered schema upgrades and test realistic transitions between released database versions.
Simple generation flow
How Sqldelight works
The build converts SQL definitions into Kotlin-facing APIs, while the runtime driver performs the actual database operations on each platform.
Configure
Apply a compatible plugin version and define the generated package and database name.
Write SQL
Add schema statements and label the queries your application needs in editable .sq files.
Generate APIs
Build the project to validate the SQL and create typed Kotlin query functions and models.
Run with a driver
Provide a platform driver, initialize the schema, test migrations and call generated operations.
Platform matrix
Compatibility depends on dialect and driver
Sqldelight supports several SQL dialects and application targets, but each combination has its own driver and runtime requirements. Choose the database family first, then confirm target support.
SQLiteAndroid, JVM, Native, JavaScript, Multiplatform
MySQLSupported JVM driver combinations
PostgreSQLJVM and selected Native combinations
HSQL / H2Experimental JVM combinations
Wasm planningVerify current driver compatibility
IDE setupMatch plugin, Kotlin and Gradle versions
Compatibility checklist
- Confirm the SQL dialect supports the statements and column types you plan to use.
- Choose a driver built for every target included in the project.
- Keep plugin and runtime dependencies on compatible versions.
- Test file locations, threading and lifecycle behavior on each platform.
- Run migrations against copies of older production schemas.
Practical scenarios
Where Sqldelight fits best
It is especially useful when a team wants SQL control, generated Kotlin types and a shared persistence design across more than one platform.
Shared local storage
Keep schema and repository logic in shared code while platform modules provide their own database drivers.
SQL-first applications
Use SQLite directly with typed generated calls instead of writing manual cursor mapping for every statement.
JVM and native tools
Build local-first applications with explicit SQL, transactions and portable data-access interfaces.
JDBC or R2DBC services
Generate typed APIs for supported server-side dialects while retaining the SQL reviewed by database teams.
Predictable query behavior
Test exact statements, adapters and migrations against temporary databases before releasing schema changes.
Incremental modernization
Introduce generated APIs around an existing schema without rewriting every database concept into a new model.
Installation overview
Set up the plugin, database and driver
Use the current plugin coordinates for your chosen version, create a named database configuration and add the matching runtime driver to each target.
1. Pin compatible versions
Align Sqldelight, Kotlin, Gradle and platform tooling in one upgrade branch.
Align Sqldelight, Kotlin, Gradle and platform tooling in one upgrade branch.
2. Place SQL correctly
Keep .sq and .sqm files under the configured source set and package path.
Keep .sq and .sqm files under the configured source set and package path.
3. Verify generation
Build, inspect generated APIs and run database tests before integrating UI code.
Build, inspect generated APIs and run database tests before integrating UI code.
plugins {
id("app.cash.sqldelight") version "2.3.2"
}
sqldelight {
databases {
create("AppDatabase") {
packageName.set("com.example.data")
}
}
}
-- Note.sq
CREATE TABLE note (
id INTEGER NOT NULL PRIMARY KEY,
title TEXT NOT NULL
);
selectAll:
SELECT * FROM note ORDER BY title;
Main source download
Download Sqldelight source archive
This ZIP contains the editable source from the repository’s main branch. It is intended for developers who want to inspect, build or contribute to the project.
The main branch may contain changes newer than the latest stable release. Review project files and dependency versions before building.
Safety notice
Review source and build settings before use
The archive is developer source code, not a signed end-user installer. Extract it into a separate folder, read the included license and build files, use a trusted JDK and Gradle environment, and avoid replacing production dependencies until tests and migrations pass.
Balanced assessment
Pros and cons of a SQL-first generator
Sqldelight offers strong transparency and generated types, but the team still owns SQL design, migrations, driver choices and platform testing.
Pros
- Queries remain visible and reviewable as real SQL.
- Generated Kotlin APIs reduce manual row mapping.
- Compile-time verification catches many schema mistakes early.
- Works well with shared Kotlin Multiplatform data layers.
- Supports custom adapters for domain-focused Kotlin types.
Cons
- Developers need solid SQL and database design skills.
- Driver availability differs across dialects and targets.
- Generated API changes can affect many call sites after schema edits.
- Migration testing remains a project responsibility.
- Toolchain upgrades may require coordinated Gradle and Kotlin changes.
2.3.2Stable reference • March 16, 2026
Release information
Use stable coordinates for application dependencies
The current stable release referenced when this website was prepared is 2.3.2. The provided download points to the repository’s main branch archive, which can move ahead of a stable tag.
For production builds, pin a reviewed release rather than an unversioned branch snapshot. Read change notes, regenerate code, compare generated interfaces and run migration tests before merging an upgrade.
Download NowProblem solving
Common setup and generation issues
Most failures come from mismatched tool versions, incorrect source paths, unsupported SQL or missing platform drivers.
Generated package is missing
Confirm the plugin applied successfully, the database block has a package name and .sq files are under the expected source directory.
SQL fails during build
Read the first compiler message, verify the selected dialect and reduce the statement to the smallest failing query before rebuilding.
Driver cannot open the database
Check that the correct driver dependency is present and that platform-specific paths, permissions and lifecycle setup are valid.
Migration works only on fresh installs
Test an upgrade from each supported old schema. Confirm migration numbering, transaction behavior and the expected final schema.
Boolean or date type mismatch
Review custom type declarations and ColumnAdapter conversions. Both encode and decode paths must agree with stored SQL values.
IDE and command-line builds differ
Synchronize Gradle, invalidate stale generated output only when necessary and make sure both environments use the same JDK and project settings.
Guides preview
Learn Sqldelight through focused examples
Each guide covers one practical search intent with local code examples, implementation checks and links to related pages on this website.
Sqldelight Example
Build a small shared notes database with labeled SQL statements and generated Kotlin calls.
Read Example Guide
SQLDelight vs Room
Compare SQL-first generation, annotations, migrations, platforms and team workflow.
Read Comparison
Sqldelight Wasm
Plan a web target without assuming every existing driver can run unchanged.
Read Wasm Guide
Query Patterns
Write labels, parameters and result projections that stay readable as a schema grows.
Read Query Guide
Testing Guide
Cover generated operations, adapters, transactions and migration upgrades.
Read Testing Guide
Common Errors
Diagnose source-set, driver, migration and generated-code problems methodically.
Read Troubleshooting GuideFrequently asked questions
Sqldelight setup, queries and platform answers
Twenty concise answers covering the source archive, generated APIs, migrations, drivers, Boolean mapping, testing and platform planning.
1
Core and Setup
Sqldelight generates type-safe Kotlin APIs from SQL statements. It lets developers keep schemas and queries in SQL files while receiving generated Kotlin models and query functions, with compile-time validation for schemas, statements and migrations.
It is better described as a SQL code generator than a traditional object-relational mapper. You write the SQL, and Sqldelight generates typed Kotlin APIs around that SQL instead of hiding database behavior behind annotations or a separate query language.
Apply the Sqldelight Gradle plugin, declare a database configuration, place schema and query files in the configured sqldelight source folder, then add the driver required by each target. Exact Gradle syntax depends on the project and plugin version.
It generates Kotlin interfaces, models, query containers and database schema helpers based on labeled statements in .sq files. The exact output depends on your schema, package configuration, selected dialect and any custom column mappings.
Yes. Schema definitions, statements and migrations are checked during the build, helping expose invalid columns, mismatched result types and migration problems before runtime. Platform-specific driver behavior should still be covered by tests.
They belong in the Sqldelight source directory for the relevant source set, usually within a package-like folder structure. In multiplatform projects this is commonly under commonMain, while platform-specific modules can use their own configured source sets.
Migration steps are stored as ordered .sqm files. Each file represents a schema change, and the generated database schema can apply them in sequence. Teams should test upgrades from realistic older schemas rather than checking only fresh database creation.
No. The download provided here is a source-code ZIP from the main repository branch. It is intended for review or development and must be extracted, configured and built with the project toolchain; it is not a one-click desktop installer.
Review the release notes, plugin coordinates, Kotlin and Gradle compatibility, driver versions, migration behavior and target support. Pin versions in a branch, run the full test suite and confirm generated APIs before upgrading production code.
The project is distributed under the Apache License 2.0. Teams should still read the included license file and confirm that their use, redistribution and notices follow internal policy and the license terms.
2
Queries and Platforms
Its documented platform matrix includes Android, JVM, JavaScript browser and Node environments, native targets such as iOS, macOS, Linux and Windows, plus multiplatform projects. Available drivers and dialects differ, so verify the target combination before implementation.
Yes. A common pattern keeps schema, generated interfaces and repository logic in shared code, while each platform supplies its own database driver and file-location details. This preserves a shared SQL model without forcing identical runtime storage APIs.
Wasm planning requires careful driver and platform verification. The public platform overview emphasizes JavaScript browser and Node support, so teams should treat wasm integration as target-dependent, test the current toolchain and avoid assuming every native or JavaScript driver works unchanged.
A label placed before a SQL statement becomes a generated Kotlin function. Labels make operations such as selectById, insertNote or deleteExpired explicit and easy to call, test and refactor from application code.
Storage depends on the SQL dialect. With SQLite, Boolean values are commonly represented by integer data and mapped to Kotlin Boolean through a custom type declaration and ColumnAdapter. The adapter must consistently convert both database and Kotlin values.
Yes. Query objects can expose listeners or reactive integrations, depending on the runtime and extensions used. Keep observation scopes focused so that only the UI or service components that need a result are refreshed after relevant table changes.
Test generated operations against a temporary or in-memory database driver where available. Cover insert, update, delete, null handling, sorting, transaction boundaries and migration upgrades. Also run platform-specific tests because driver behavior can vary.
Sqldelight starts with SQL files and generates Kotlin APIs. Room typically models tables and access through entities, annotations and DAOs. Both can support typed persistence workflows, but the right choice depends on platform targets, SQL control, migration style and team preference.
The documented dialect matrix includes MySQL and PostgreSQL for supported JVM drivers, with additional PostgreSQL native combinations. Driver, dialect and runtime support are not identical across targets, so configure only combinations listed for the version you use.
Common causes include a renamed or removed label, invalid SQL that prevents generation, files placed in the wrong source folder, Gradle sync problems or stale generated output. Fix build errors first, confirm package paths and regenerate the project.