Align API with Ecto Repo conventions (breaking change)

[tylerbarker]

Summary

Aligns SqlKit's API with Ecto Repo conventions for a more intuitive developer experience. This is a breaking change targeting version 0.2.0.

• query_all/4 now returns list directly and raises on errors (matches Ecto.Repo.all/2)
• query_all!/4 removed entirely (no Ecto equivalent)
• query_one/4 now returns result or nil, raises on multiple results (matches Ecto.Repo.one/2)
• File-based API (use SqlKit) follows the same conventions

Migration Guide

# query_all: remove tuple wrapper
# Before
{:ok, users} = SqlKit.query_all(Repo, "SELECT * FROM users")
# After
users = SqlKit.query_all(Repo, "SELECT * FROM users")

# query_all!: use query_all instead
# Before
users = SqlKit.query_all!(Repo, "SELECT * FROM users")
# After
users = SqlKit.query_all(Repo, "SELECT * FROM users")

# query_one: remove tuple wrapper
# Before
{:ok, user} = SqlKit.query_one(Repo, "SELECT * FROM users WHERE id = $1", [1])
{:ok, nil} = SqlKit.query_one(Repo, "SELECT * FROM users WHERE id = $1", [999])
# After
user = SqlKit.query_one(Repo, "SELECT * FROM users WHERE id = $1", [1])
nil = SqlKit.query_one(Repo, "SELECT * FROM users WHERE id = $1", [999])

# query_one multiple results: now raises instead of returning error tuple
# Before
{:error, %SqlKit.MultipleResultsError{}} = SqlKit.query_one(Repo, "SELECT * FROM users")
# After
# Raises SqlKit.MultipleResultsError
SqlKit.query_one(Repo, "SELECT * FROM users")

[Copilot]

Pull request overview

This PR aligns SqlKit's API with Ecto Repo conventions, making it more intuitive for Elixir developers familiar with Ecto. The changes target version 0.2.0 and introduce breaking changes to the API.

Key Changes:

• query_all/4 now returns results directly instead of {:ok, results} and raises on errors (matching Ecto.Repo.all/2)
• query_all!/4 has been removed entirely (developers should use query_all/4 instead)
• query_one/4 now returns result or nil directly and raises on multiple results or errors (matching Ecto.Repo.one/2)

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
lib/sql_kit/query.ex	Refactored all/4 to raise instead of returning tuples; updated one/4 to return result/nil and raise on errors
lib/sql_kit.ex	Updated public API functions and documentation to match new semantics; file-based SQL API updated similarly
lib/sql_kit/duckdb.ex	Updated documentation examples to use new API
lib/sql_kit/duckdb/pool.ex	Updated documentation examples and added sobelow security annotations
test/sql_kit_test.exs	Comprehensive test updates: removed query_all!/3 tests, updated query_all/3 and query_one/3 tests to expect direct returns and raises
test/sql_kit/duckdb_test.exs	Updated DuckDB-specific tests to match new API behavior
README.md	Updated all usage examples, API reference, and migration guidance
CLAUDE.md	Updated AI assistant documentation with new API patterns
CHANGELOG.md	Added detailed breaking changes documentation with before/after examples
mix.exs	Version bumped from 0.1.0 to 0.2.0
.gitignore	Added *.db and *.duckdb patterns for database files

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.