Saferis SQL Development

Development guidelines for building type-safe SQL clients using Scala 3, ZIO, and test containers.

Instructions

Running Commands

1. **Prefer Metals MCP commands over sbt**

- Always try Metals MCP commands first, especially for compiling, testing, and running

- Metals MCP provides better IDE integration and faster feedback

2. **Use sbt only when Metals MCP doesn't support your task**

- When using sbt, use client mode: `sbt --client "..."`

- Always quote your commands, especially for multi-part commands

- Exception: For code coverage, use: `sbt "clean; coverage; test; coverageReport"`

Coding Style

1. **Scala 3 Modern Syntax**

- Use braceless syntax in all code

- Conform to the Scala 3 style guide

- Leverage Scala 3 features like union types, opaque types, and given/using

2. **Idiomatic ZIO**

- Use ZIO for effect management

- Use ZIO layers for services and dependency injection

- Write pure, referentially transparent code

- Code for performance: if a function is simple and doesn't need to be an effect, make it a plain function

3. **Testing with zio-test**

- Use idiomatic zio-test for all tests

- Use for-comprehensions to chain ZIO effects in tests

- Use test containers for database integration tests (see existing tests for examples)

- Remember: this is an SQL client library, so most tests will use test containers

Examples

Braceless Syntax

```scala

def queryUser(id: UserId): ZIO[Database, Throwable, User] =

for

conn <- ZIO.service[Database]

user <- conn.query(sql"SELECT * FROM users WHERE id = $id")

yield user

```

ZIO Layer Pattern

```scala

val live: ZLayer[ConnectionPool, Nothing, UserRepository] =

ZLayer:

for pool <- ZIO.service[ConnectionPool]

yield UserRepositoryLive(pool)

```

Test with Test Containers

```scala

test("fetch user by id"):

for

repo <- ZIO.service[UserRepository]

user <- repo.findById(UserId(1))

yield assertTrue(user.name == "Alice")

.provide(

PostgresContainer.layer,

UserRepository.live

)

```

Constraints