{"id":28881935,"url":"https://github.com/softinio/duck4s","last_synced_at":"2026-04-29T16:08:30.203Z","repository":{"id":298052541,"uuid":"994473983","full_name":"softinio/duck4s","owner":"softinio","description":"Scala 3 wrapper library for DuckDB","archived":false,"fork":false,"pushed_at":"2025-06-09T07:35:22.000Z","size":2758,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-20T20:49:30.418Z","etag":null,"topics":["database","duckdb","functional-programming","jvm","millbuild","munit","scala"],"latest_commit_sha":null,"homepage":"https://www.duck4s.com","language":"Scala","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/softinio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-02T01:48:24.000Z","updated_at":"2025-06-17T11:59:06.000Z","dependencies_parsed_at":"2025-06-09T06:40:53.034Z","dependency_job_id":null,"html_url":"https://github.com/softinio/duck4s","commit_stats":null,"previous_names":["softinio/duck4s"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/softinio/duck4s","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softinio%2Fduck4s","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softinio%2Fduck4s/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softinio%2Fduck4s/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softinio%2Fduck4s/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/softinio","download_url":"https://codeload.github.com/softinio/duck4s/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softinio%2Fduck4s/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264868549,"owners_count":23676091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","duckdb","functional-programming","jvm","millbuild","munit","scala"],"created_at":"2025-06-20T20:31:00.952Z","updated_at":"2026-04-29T16:08:30.194Z","avatar_url":"https://github.com/softinio.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n![tests](https://github.com/softinio/duck4s/actions/workflows/ci.yml/badge.svg) | ![release](https://github.com/softinio/duck4s/actions/workflows/release.yml/badge.svg)  | ![documentation](https://github.com/softinio/duck4s/actions/workflows/docs.yml/badge.svg) | [![duck4s Scala version support](https://index.scala-lang.org/softinio/duck4s/duck4s/latest.svg)](https://index.scala-lang.org/softinio/duck4s/duck4s)\n\n# duck4s\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"duck4s/docs/_assets/images/duck4s_logo.jpeg\" alt=\"Duck4s Logo\" width=\"400\"\u003e\n\u003c/p\u003e\n\nA 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.\n\n## Overview\n\nDuck4s makes working with DuckDB in Scala applications a pleasant experience by:\n- Providing type-safe APIs that leverage Scala 3's advanced type system\n- Supporting functional programming patterns with `Either[DuckDBError, T]` error handling\n- Offering automatic resource management with `withConnection`, `withPreparedStatement`, and `withBatch` methods\n- Maintaining full compatibility with DuckDB's JDBC interface while providing idiomatic Scala abstractions\n\n## Features\n\n- 🦆 **Type Safety** - Comprehensive error handling with `Either[DuckDBError, T]` types\n- 🔧 **Resource Management** - Automatic resource cleanup with `withConnection`, `withPreparedStatement`, and `withBatch` methods\n- 🚀 **Functional Programming** - Designed for composition with for-comprehensions and functional patterns\n- 📊 **Modern Scala 3** - Utilizes Scala 3 features like extension methods, given instances, and braceless syntax\n- 🔄 **Batch Operations** - Efficient type-safe batch processing with type classes\n- 💼 **Transaction Support** - First-class transaction management with automatic rollback\n- 🐱 **Cats-Effect Integration** - Optional `duck4s-cats-effect` module with `Resource`-based connection management, `IO`-wrapped operations, and `fs2.Stream` result set streaming\n- 📱 **LTS and Latest Scala Version Support** - Supports Scala 3.3.6 (LTS) and 3.8.2\n\n## Getting Started\n\n### Installation\n\n#### SBT\n\nAdd duck4s to your `build.sbt`:\n\n```scala\n// Core library\nlibraryDependencies += \"com.softinio\" %% \"duck4s\" % \"0.1.4\"\n\n// Optional: cats-effect integration (includes fs2)\nlibraryDependencies += \"com.softinio\" %% \"duck4s-cats-effect\" % \"0.1.4\"\n```\n\n#### Mill\n\nAdd duck4s to your `build.mill`:\n\n```scala\n// Core library\ndef ivyDeps = Agg(\n  ivy\"com.softinio::duck4s::0.1.4\"\n)\n\n// Optional: cats-effect integration (includes fs2)\ndef ivyDeps = Agg(\n  ivy\"com.softinio::duck4s::0.1.4\",\n  ivy\"com.softinio::duck4s-cats-effect::0.1.4\"\n)\n```\n\n### Prerequisites\n\n- Scala 3.3.6 or 3.8.2\n- Java 17 or higher\n- Mill build tool (or use the provided Nix development environment)\n\n### Development Setup\n\nThis project uses Nix for reproducible development environments. To get started:\n\n```bash\n# Enter the development shell (requires Nix with flakes)\nnix develop\n\n# Build for all Scala versions\nmill __.compile\n\n# Build for specific Scala version\nmill 'duck4s[3.8.2].compile'\n\n# Run tests\nmill __.test\n\n# Generate documentation\nmill 'duck4s[3.8.2].docJar'\n\n# Format code\nmill mill.scalalib.scalafmt.ScalafmtModule/reformatAll __.sources\n```\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/softinio/duck4s.git\ncd duck4s\n\n# Build the project\nmill __.compile\n\n# Run tests\nmill __.test\n```\n\n## Quick Example\n\n```scala\nimport com.softinio.duck4s.*\nimport com.softinio.duck4s.algebra.*\n\n// Simple query execution\nval result = DuckDBConnection.withConnection() { conn =\u003e\n  for\n    _ \u003c- conn.executeUpdate(\"CREATE TABLE users (id INTEGER, name VARCHAR)\")\n    _ \u003c- conn.executeUpdate(\"INSERT INTO users VALUES (1, 'Alice'), (2, 'Bob')\")\n    rs \u003c- conn.executeQuery(\"SELECT * FROM users ORDER BY id\")\n  yield\n    while rs.next() do\n      println(s\"${rs.getInt(\"id\")}: ${rs.getString(\"name\")}\")\n    rs.close()\n}\n\nresult match\n  case Right(_) =\u003e println(\"Query executed successfully\")\n  case Left(error) =\u003e println(s\"Error: $error\")\n```\n\n## Cats-Effect Quick Example\n\n```scala\nimport cats.effect.{IO, IOApp}\nimport com.softinio.duck4s.algebra.*\nimport com.softinio.duck4s.effect.*\n\nobject Main extends IOApp.Simple:\n  def run: IO[Unit] =\n    DuckDBIO.connect().use { conn =\u003e\n      for\n        _ \u003c- conn.executeUpdateIO(\"CREATE TABLE users (id INTEGER, name VARCHAR)\")\n        _ \u003c- conn.executeUpdateIO(\"INSERT INTO users VALUES (1, 'Alice'), (2, 'Bob')\")\n        _ \u003c- DuckDBIO\n          .stream(conn, \"SELECT * FROM users ORDER BY id\") { rs =\u003e\n            s\"${rs.getInt(\"id\")}: ${rs.getString(\"name\")}\"\n          }\n          .evalTap(row =\u003e IO(println(row)))\n          .compile.drain\n      yield ()\n    }\n```\n\n## Documentation\n\n- [Getting Started Guide](https://softinio.github.io/duck4s/docs/getting-started.html) - Learn the basics of duck4s\n- [Cats-Effect Integration](https://softinio.github.io/duck4s/docs/cats-effect.html) - Effectful IO and streaming with cats-effect and fs2\n- [API Documentation](https://softinio.github.io/duck4s/) - Complete API reference\n\n## Contributing\n\n**GitHub Issues** are disabled to encourage direct community contribution. When you encounter bugs or documentation issues, please contribute fixes through Pull Requests instead.\n\n**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.\n\nThis approach creates faster fixes while building a stronger, community-driven project where everyone benefits from shared contributions.\n\n## Using AI Help to use or contribute to this project\n\nThis 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.\n\n\n## License\n\nDuck4s is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\n- [DuckDB](https://duckdb.org/) for creating an excellent analytical database\n- The Scala community for continuous innovation in functional programming\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftinio%2Fduck4s","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftinio%2Fduck4s","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftinio%2Fduck4s/lists"}