https://github.com/softinio/duck4s
Scala 3 wrapper library for DuckDB
https://github.com/softinio/duck4s
database duckdb functional-programming jvm millbuild munit scala
Last synced: about 2 months ago
JSON representation
Scala 3 wrapper library for DuckDB
- Host: GitHub
- URL: https://github.com/softinio/duck4s
- Owner: softinio
- License: apache-2.0
- Created: 2025-06-02T01:48:24.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-09T07:35:22.000Z (about 1 year ago)
- Last Synced: 2025-06-20T20:49:30.418Z (12 months ago)
- Topics: database, duckdb, functional-programming, jvm, millbuild, munit, scala
- Language: Scala
- Homepage: https://www.duck4s.com
- Size: 2.63 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
 |  |  | [](https://index.scala-lang.org/softinio/duck4s/duck4s)
# duck4s
A modern, type-safe Scala 3 wrapper library for [DuckDB](https://duckdb.org/) that provides idiomatic, functional programming-friendly access to DuckDB's analytical database capabilities through its Java JDBC client.
## Overview
Duck4s makes working with DuckDB in Scala applications a pleasant experience by:
- Providing type-safe APIs that leverage Scala 3's advanced type system
- Supporting functional programming patterns with `Either[DuckDBError, T]` error handling
- Offering automatic resource management with `withConnection`, `withPreparedStatement`, and `withBatch` methods
- Maintaining full compatibility with DuckDB's JDBC interface while providing idiomatic Scala abstractions
## Features
- 🦆 **Type Safety** - Comprehensive error handling with `Either[DuckDBError, T]` types
- 🔧 **Resource Management** - Automatic resource cleanup with `withConnection`, `withPreparedStatement`, and `withBatch` methods
- 🚀 **Functional Programming** - Designed for composition with for-comprehensions and functional patterns
- 📊 **Modern Scala 3** - Utilizes Scala 3 features like extension methods, given instances, and braceless syntax
- 🔄 **Batch Operations** - Efficient type-safe batch processing with type classes
- 💼 **Transaction Support** - First-class transaction management with automatic rollback
- 🐱 **Cats-Effect Integration** - Optional `duck4s-cats-effect` module with `Resource`-based connection management, `IO`-wrapped operations, and `fs2.Stream` result set streaming
- 📱 **LTS and Latest Scala Version Support** - Supports Scala 3.3.6 (LTS) and 3.8.2
## Getting Started
### Installation
#### SBT
Add duck4s to your `build.sbt`:
```scala
// Core library
libraryDependencies += "com.softinio" %% "duck4s" % "0.1.4"
// Optional: cats-effect integration (includes fs2)
libraryDependencies += "com.softinio" %% "duck4s-cats-effect" % "0.1.4"
```
#### Mill
Add duck4s to your `build.mill`:
```scala
// Core library
def ivyDeps = Agg(
ivy"com.softinio::duck4s::0.1.4"
)
// Optional: cats-effect integration (includes fs2)
def ivyDeps = Agg(
ivy"com.softinio::duck4s::0.1.4",
ivy"com.softinio::duck4s-cats-effect::0.1.4"
)
```
### Prerequisites
- Scala 3.3.6 or 3.8.2
- Java 17 or higher
- Mill build tool (or use the provided Nix development environment)
### Development Setup
This project uses Nix for reproducible development environments. To get started:
```bash
# Enter the development shell (requires Nix with flakes)
nix develop
# Build for all Scala versions
mill __.compile
# Build for specific Scala version
mill 'duck4s[3.8.2].compile'
# Run tests
mill __.test
# Generate documentation
mill 'duck4s[3.8.2].docJar'
# Format code
mill mill.scalalib.scalafmt.ScalafmtModule/reformatAll __.sources
```
### Building from Source
```bash
# Clone the repository
git clone https://github.com/softinio/duck4s.git
cd duck4s
# Build the project
mill __.compile
# Run tests
mill __.test
```
## Quick Example
```scala
import com.softinio.duck4s.*
import com.softinio.duck4s.algebra.*
// Simple query execution
val result = DuckDBConnection.withConnection() { conn =>
for
_ <- conn.executeUpdate("CREATE TABLE users (id INTEGER, name VARCHAR)")
_ <- conn.executeUpdate("INSERT INTO users VALUES (1, 'Alice'), (2, 'Bob')")
rs <- conn.executeQuery("SELECT * FROM users ORDER BY id")
yield
while rs.next() do
println(s"${rs.getInt("id")}: ${rs.getString("name")}")
rs.close()
}
result match
case Right(_) => println("Query executed successfully")
case Left(error) => println(s"Error: $error")
```
## Cats-Effect Quick Example
```scala
import cats.effect.{IO, IOApp}
import com.softinio.duck4s.algebra.*
import com.softinio.duck4s.effect.*
object Main extends IOApp.Simple:
def run: IO[Unit] =
DuckDBIO.connect().use { conn =>
for
_ <- conn.executeUpdateIO("CREATE TABLE users (id INTEGER, name VARCHAR)")
_ <- conn.executeUpdateIO("INSERT INTO users VALUES (1, 'Alice'), (2, 'Bob')")
_ <- DuckDBIO
.stream(conn, "SELECT * FROM users ORDER BY id") { rs =>
s"${rs.getInt("id")}: ${rs.getString("name")}"
}
.evalTap(row => IO(println(row)))
.compile.drain
yield ()
}
```
## Documentation
- [Getting Started Guide](https://softinio.github.io/duck4s/docs/getting-started.html) - Learn the basics of duck4s
- [Cats-Effect Integration](https://softinio.github.io/duck4s/docs/cats-effect.html) - Effectful IO and streaming with cats-effect and fs2
- [API Documentation](https://softinio.github.io/duck4s/) - Complete API reference
## Contributing
**GitHub Issues** are disabled to encourage direct community contribution. When you encounter bugs or documentation issues, please contribute fixes through Pull Requests instead.
**How to contribute:** [Open a PR](https://github.com/softinio/duck4s/pulls) with your solution, draft changes, or a test reproducing the issue. We'll collaborate from there to refine and merge improvements.
This approach creates faster fixes while building a stronger, community-driven project where everyone benefits from shared contributions.
## Using AI Help to use or contribute to this project
This project is optimized and setup for you to use [Claude Code](https://www.anthropic.com/claude-code) as your AI programming agent. It is recommended to use Claude Code.
## License
Duck4s is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.
## Acknowledgments
- [DuckDB](https://duckdb.org/) for creating an excellent analytical database
- The Scala community for continuous innovation in functional programming