typelevel/skunk

This system is a high-performance, multi-platform PostgreSQL client library for Scala that supports JVM, JavaScript, and Native targets. It provides comprehensive data encoding and decoding capabilities, including native support for JSON, PostGIS geometry, and refined types, while managing connections through a configurable, telemetry-aware connection pool. The library features a modern, type-safe API for constructing and executing SQL queries, with built-in OpenTelemetry integration for tracing and metrics, and robust error handling with structured diagnostics.

33 changes.

This period centered on a comprehensive rewrite of the Skunk library for version 2.0, introducing a modular architecture with platform-specific implementations for JVM, JavaScript, and Native targets. The work established a new core API featuring session builders, telemetry integration via OpenTelemetry, and robust error handling, while expanding support for PostgreSQL features like SSL, JSON codecs, and complex data types. Extensive test coverage and example applications were added to validate the new protocol stack and ensure compatibility across all supported platforms.

7 changes.

This period focused on expanding the library's capabilities with native PostgreSQL authentication support for Scala Native and comprehensive PostGIS geometry codec integration. It also introduced refined type support and established performance benchmarks to compare Skunk against JDBC, alongside refactoring enum codec compatibility layers.

Introduces a new \JsonCodecs\ trait in the Circe module that provides implicit encoders and decoders for PostgreSQL \json\ and \jsonb\ columns using the Circe library. Users can now seamlessly serialize and deserialize case classes or Circe \Json\ values to and from these database types via the \json\ and \jsonb\ methods, leveraging the Jawn parser for JSON parsing.

modules/circe · high confidence

The \modules/postgis\ module now provides native support for PostGIS geometry types. Users can encode and decode spatial data using Well-Known Binary (EWKB) via \skunk.postgis.codecs\, which exposes codecs for \Point\, \LineString\, \Polygon\, \MultiPoint\, \MultiLineString\, \MultiPolygon\, and \GeometryCollection\. Additionally, the module includes an Extended Well-Known Text (EWKT) parser (\skunk.postgis.ewkt.parser\) to parse geometry strings, supporting SRID prefixes and Z/M dimensionality.

modules/postgis · high confidence

The World database Docker image now supports SSL connections. This is achieved by adding a self-signed certificate and key, a script to handle file permissions for the PostgreSQL user, and SQL configuration to enable SSL. The image also includes the ltree extension and the standard world database schema.

world · high confidence

Introduces a new \SqlState.scala\ file in the Scala 2 source directory that defines an enumerated type of PostgreSQL error codes using the enumeratum library. This allows users to pattern-match against specific Postgres error codes (such as \ForeignKeyViolation\ or \CheckViolation\) for more precise error handling in Scala 2 environments.

modules/core/shared/src/main/scala-2 · high confidence

Skunk now supports running in JavaScript environments by introducing platform-specific implementations for core cryptographic operations. New files in the \modules/core/js\ directory provide JavaScript-native versions of the SSL companion trait, MD5 password hashing, and SCRAM-SHA-256 authentication (including HMAC, hashing, and key derivation). These changes enable the library to compile and function correctly on Scala.js by leveraging the Node.js \crypto\ module for required security primitives.

modules/core/js · high confidence

The \modules/refined\ module now provides integration with the \eu.timepit.refined\ library, allowing Skunk codecs to work with refined types. New files \RefTypeCodecs.scala\, \RefinedCodecs.scala\, and \Syntax.scala\ define \Codec\, \Encoder\, and \Decoder\ instances for \Refined\[T, P\]\ and generic \RefType\ wrappers. This enables users to automatically validate and unwrap refined types during database read/write operations using either the direct \refined\ object or the implicit syntax extensions on existing Skunk codecs.

modules/refined · high confidence

A new JMH benchmark file (SelectBench.scala) has been added to the Skunk benchmark module. It provides baseline performance comparisons between hand-written JDBC code and Skunk's streaming API for SELECT queries. The benchmark setup uses the new Session.Builder API and incorporates OpenTelemetry providers (TracerProvider and MeterProvider) for instrumentation.

modules/bench/src/main/scala/skunk · high confidence

Added native Scala implementations for MD5 and SCRAM authentication mechanisms required for PostgreSQL connections. This includes new platform-specific files (\PasswordMessagePlatform\, \ScramPlatform\, and \openssl\) that utilize Scala Native's FFI to call OpenSSL functions (such as \EVP\_Digest\, \HMAC\, and \PKCS5\_PBKDF2\_HMAC\) for computing password hashes and secure random nonces, enabling authentication on native targets where JVM-based crypto providers are unavailable.

modules/core/native · high confidence

This release introduces several new data types for the \skunk.data\ package, including \Arr\ for handling PostgreSQL arrays, \Cache\ for LRU caching, \Encoded\ for managing redacted text (now using '?' instead of '\<redacted\>'), \Identifier\ with support for quoted identifiers, \LTree\ for hierarchical data, and transaction-related enums (\TransactionAccessMode\, \TransactionIsolationLevel\, \TransactionStatus\). Additionally, the \Completion\ sealed abstract class has been significantly expanded to cover a wide range of SQL commands (such as \CALL\, \GRANT\, \REVOKE\, \ALTER\, \CREATE\, \DROP\ for various objects like tables, views, roles, extensions, and materialized views), including a specific \SelectWithoutCount\ variant for Amazon Redshift compatibility.

modules/core/shared/src/main/scala/data · high confidence

Added a suite of new example programs in the \modules/example\ module to showcase Skunk capabilities, including applied fragments, channel/listen-notify, error handling, join queries, transaction management, and bulk value insertion. These examples also demonstrate the integration of OpenTelemetry via \TracerProvider\ and \MeterProvider\ for tracing and metrics.

modules/example · high confidence

This change introduces a suite of new utility components in the \skunk.util\ package to enhance resource management and debugging. A new \Pool\ abstraction provides a configurable, telemetry-aware resource pool with health checks (via \Recycler\) and leak detection. An LRU \StatementCache\ is added to cache prepared statements, improving performance by reducing redundant database round-trips. Additionally, \Namer\ generates unique identifiers, \Origin\ and \Located\ track source locations for better error reporting, and \Pretty\ and \Text\ provide utilities for formatting and styling console output.

modules/core/shared/src/main/scala/util · high confidence

This change establishes the foundational project structure and tooling for local development. It introduces configuration files for code formatting (scalafmt), JVM options, and CI automation (Mergify, Codecov). It adds a comprehensive docker-compose setup to spin up local Postgres, PostGIS, Redshift, and Jaeger tracing instances for testing, alongside a new CONTRIBUTING guide detailing these local workflows. Additionally, it updates the README to reflect the move to the Typelevel organization and updates the license copyright.

(repo-wide) · high confidence

The \modules/core/src\ directory has been completely removed, deleting the foundational components for the PostgreSQL client library. This includes the socket abstractions (\ActiveMessageSocket\, \MessageSocket\, \BitVectorSocket\), the protocol message definitions (\proto/message/\*\), and the high-level session and query execution logic (\Session\, \SimpleQuery\, \Startup\). Users relying on this module for database connectivity will lose access to these core networking and query-handling capabilities.

modules/core/src · high confidence

The empty \Benchmark\ class in the \skunk.bench\ package has been removed from the codebase, eliminating unused code from the benchmark module.

modules/bench/src/main/scala · high confidence

The codec implementation has been reorganized into separate traits (NumericCodecs, TextCodecs, TemporalCodecs, BooleanCodec, EnumCodec, UuidCodec, BinaryCodecs, LTreeCodec) aggregated by AllCodecs, improving modularity. This change introduces new codecs for the PostgreSQL LTREE type (LTreeCodec) and UUID arrays (\_uuid in UuidCodec), while also fixing temporal codec behavior for years with fewer than three digits and ensuring explicit Locale usage for era formatting to prevent platform-dependent parsing issues.

modules/core/shared/src/main/scala/codec · high confidence

The library now provides a complete set of specific exception types (such as DecodeException, PostgresErrorException, and ColumnAlignmentException) that replace generic failures with detailed, structured diagnostics. These exceptions include contextual information like SQL statements, argument values (subject to redaction), and precise error locations, and they integrate with OpenTelemetry to expose error attributes for observability. This change significantly improves the developer experience by making debugging database issues, type mismatches, and protocol errors much faster and more informative.

modules/core/shared/src/main/scala/exception · high confidence

The \modules/core/shared/src/main/scala/net/message\ package has been significantly expanded to support a wider range of PostgreSQL protocol messages and command completions. New message types have been added for authentication methods including Cleartext Password, GSS, Kerberos V5, SCM Credential, and SSPI, alongside SASL authentication support (SCRAM-SHA-256) and various Copy protocol messages. The \CommandComplete\ decoder now recognizes a comprehensive set of SQL commands—such as \CALL\, \MERGE\, \EXPLAIN\, \GRANT\/\REVOKE\, \ALTER\ variants for views, roles, and policies, and materialized view operations—mapping them to specific \Completion\ types. Additionally, a special case for \SELECT\ without a row count has been added to better support Amazon Redshift servers.

modules/core/shared/src/main/scala/net/message · high confidence

The JVM core module now includes platform-specific implementations for SSL context creation and SCRAM authentication. Users on the JVM platform will benefit from native Java-based TLS handling via \SSLPlatform\ (supporting \SSLContext\, key stores, and classpath resources) and a built-in SCRAM mechanism using \HmacSHA256\ and \PBKDF2WithHmacSHA256\, removing the need for external SCRAM client dependencies.

modules/core/jvm · high confidence

The core library has been refactored to introduce a new \Session.Builder\ for constructing sessions, replacing previous pooled and single methods. A new \Channel\ trait provides \listenR\ for resource-managed notification streams, and \PreparedQuery\ now includes a \fetchAll\ method for efficient single-exchange retrieval. Telemetry support is added via \otel4s\, allowing \Command\ and \Query\ to carry span attributes and query summaries. Redaction strategies (\OptIn\, \All\, \None\) are now configurable at the session level to control how encoded values are masked in exceptions and traces. The library also adopts Typelevel Twiddles for type-safe case-class mapping via \.to\[CaseClass\]\, deprecating the older \gimap\/\gcontramap\ syntax.

modules/core/shared/src/main/scala · high confidence

The \sql\ string interpolator now supports \Identifier\ arguments directly, and a new \ident\ interpolator is introduced to preserve quoted identifiers verbatim. The legacy \id\ interpolator is deprecated in favor of \ident\, with a note that users requiring the old case-folding behavior should pass a lower-cased literal. This change is implemented via macro expansions in \StringContextOps\ that handle identifier splicing and encoder assembly, supporting the new default command syntax while allowing opt-in to the legacy syntax via feature flags.

modules/core/shared/src/main/scala-2/syntax · high confidence

A new \bin/local\ script has been added to manage the local development environment. It accepts a direction (\up\ or \down\) and an optional second argument for extra flags passed to \docker-compose\. To resolve file ownership issues within Docker containers, the script now loads the server key and certificate from \world/server.key\ and \world/server.crt\ into environment variables (\SERVER\_KEY\, \SERVER\_CERT\) before invoking \docker-compose\, rather than mounting them directly.

bin · high confidence

The enum codec compatibility implementation has been reorganized into a new \EnumCodecCompat\ trait. For Scala 2, this trait provides the concrete \enum\ codec method that maps enumeratum enum entries to and from database strings, while the Scala 3 version remains an empty trait placeholder. This change consolidates the platform-specific codec logic into a dedicated compatibility module.

modules/core/shared/src/main/scala-2/codec, modules/core/shared/src/main/scala-3/codec · high confidence

The network protocol layer has been restructured into distinct, modular components (Bind, BindExecute, Close, Describe, Exchange, Execute, Parse, ParseDescribe, Prepare, Query, Startup, and Unroll) to improve code organization and maintainability. This refactoring introduces a new \Exchange\ abstraction backed by a \Mutex\ to manage concurrent protocol interactions, integrates \Telemetry\ for tracing and metrics across all protocol operations, and implements specific authentication support including \AuthenticationCleartextPassword\. The changes also add caching mechanisms for \Parse\ and \Describe\ operations to optimize repeated query execution, and refine error handling and redaction strategies throughout the protocol stack.

modules/core/shared/src/main/scala/net/protocol · high confidence

The network layer has been restructured to improve reliability and performance. A new \BufferedMessageSocket\ now handles asynchronous backend messages (such as notifications and parameter updates) in a background loop, decoupling them from the synchronous request-response flow. This architecture introduces \isHealthy\ checks on both the socket and protocol layers, allowing the client to detect and fail notification streams when the underlying connection is lost. Additionally, a configurable \readTimeout\ has been added to prevent indefinite hangs during data reception, and the \Protocol\ interface now exposes \prepareR\ methods for one-shot prepared statements that are automatically closed upon resource finalization without caching.

modules/core/shared/src/main/scala/net · high confidence

The new \modules/core/shared/src/main/scala-3/syntax\ module provides Scala 3-specific syntax extensions. It introduces \sql\, \ident\, and \id\ string interpolators that use Scala 3 quotes for compile-time validation, supporting \Identifier\ types in \sql\ and offering \ident\ for verbatim identifier preservation. Additionally, it defines \CodecOps\, \DecoderOps\, and \EncoderOps\ traits that deprecate the \pimap\, \pmap\, and \pcontramap\ methods in favor of \.to\[P\]\, while maintaining binary compatibility with Skunk 0.5 via private \\*:\ operators.

modules/core/shared/src/main/scala-3/syntax · high confidence

The Twiddler utility, which previously mapped case classes to HList structures, is now deprecated and users should switch to twiddle tuples (\*:) instead. This change affects the core shared utilities used for type-level transformations in the library.

modules/core/shared/src/main/scala-2/util · high confidence

The Scala 3 implementation of the Twiddler utility now supports case classes with up to 15 fields, expanding the previous limit of 12. This change allows users to map larger case classes to twiddle-list types without encountering type-class resolution failures, leveraging Scala 3's mirror-based derivation for products of increased arity.

modules/core/shared/src/main/scala-3/util · high confidence

Added Scala.js test platform support; Added comprehensive codec test coverage; Added native platform test framework base trait; Added regression tests for issues 129, 181, 210, 238, 313, 628, and 990; Added simulation-based tests for Postgres protocol behavior; Added test coverage for data types; Added tests for 16-element Twiddle lists in Scala 3; Added tests for EnumCodec with Enumeratum support; Added tests for PostGIS geometry codecs; Added tests for Telemetry integration and performance benchmarks; Expanded test coverage for Skunk core components; New FTest framework for shared test utilities.

The project has been upgraded to base version 2.0, updating the Scala versions to 2.13.18 and 3.3.8, and significantly bumping core dependencies including fs2 to 3.14.0, OpenTelemetry to 1.65.0, otel4s to 1.1.0, and refined to 0.11.4. The build infrastructure has been migrated to sbt-typelevel, replacing the previous microsites setup, and binary compatibility filters (MiMa) have been added to handle breaking changes in the net and codec modules.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 34 → 59 (+24.7)
• Rubric changed (rubric-2026.08.15 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 100 → 90 (-9.8)
• Architecture 95 (new)
• Maturity 40 → 48 (+8.1)
• Readiness 17 → 58 (+41.3)
• Security 45 → 69 (+23.6)

• Dimension evaluation failed
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 18 more

• Arr.parseWith (cognitive 72) (modules/core/shared/src/main/scala/data/Arr.scala)
• Arr.parseWith (cyclomatic 34) (modules/core/shared/src/main/scala/data/Arr.scala)
• Bind.apply (cognitive 58) (modules/core/shared/src/main/scala/net/protocol/Bind.scala)
• BindExecute.apply (cognitive 142) (modules/core/shared/src/main/scala/net/protocol/BindExecute.scala)
• BindExecute.apply (cyclomatic 49) (modules/core/shared/src/main/scala/net/protocol/BindExecute.scala)
• BufferedMessageSocket.fromMessageSocket (cognitive 65) (modules/core/shared/src/main/scala/net/BufferedMessageSocket.scala)
• Documentation: no installation or build instructions (README.md)
• Documentation: no installation or build instructions (modules/docs/src/main/laika/tutorial/index.md)
• Documentation: no project overview (modules/docs/src/main/laika/tutorial/index.md)
• Documentation: no usage examples (README.md)
• Documentation: no usage examples (modules/docs/src/main/laika/tutorial/index.md)
• Duplicated block (11 lines × 2) (modules/core/shared/src/main/scala/net/protocol/Bind.scala)
• Duplicated block (18 lines × 2) (modules/core/shared/src/main/scala/util/Pool.scala)
• Duplicated block (8 lines × 2) (modules/core/shared/src/main/scala/exception/ProtocolError.scala)
• Duplicated block (9 lines × 2) (modules/core/shared/src/main/scala-2/syntax/StringContextOps.scala)
• Duplicated block (9 lines × 2) (modules/core/shared/src/main/scala-3/syntax/StringContextOps.scala)
• Further sole-owners (lower concentration)
• HackComment (modules/core/shared/src/main/scala/net/message/StartupMessage.scala)
• High IaC: WD-COMPOSE-0002 (docker-compose.yml)
• High: security finding (details withheld)
• …and 87 more

• 46 commits — 43 feature/other, 3 fixes

• (repo) — 17 commits
• modules/core — 15 commits
• modules/tests — 6 commits
• (root) — 5 commits
• .github/workflows — 1 commit
• modules/example — 1 commit
• project/build.properties — 1 commit

• fix: Fix DisconnectTest
• fix: Merge pull request #1362 from massimosiani/fix/alter-view-completions
• fix: fix race condition
• change: Add PreparedQuery.fetchAll
• change: Add BufferedMessageSocket#isHealthy
• change: Add Pool.ofF variant with checkout Recycler
• change: Add Protocol#isHealthy
• change: Add Recyclers.ensureHealthy
• change: Add Session#isHealthy
• change: Add a harness that counts protocol exchanges per operation
• change: Add disconnect tests for isHealthy and while idle
• change: Bind, execute and Sync in one exchange for one-shot queries
• change: Change Protocol#cleanup to no-op on unhealthy socket
• change: Change Session to use Recyclers.ensureHealthy on checkout
• change: Cleanup BufferedMessageSocket
• change: Fail notification streams when the connection is lost
• change: Generate GitHub workflow
• change: Merge branch 'main' into pool-checkout-recycler
• change: Merge branch 'main' into round-trip-reduction
• change: Merge branch 'main' into update/otel4s-core-1.1.0
• …and 26 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

typelevel/skunk was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.