change Handle to a generic interface without explicit dep on database/sql

1 files changed, 52 insertions, 0 deletions

diff --git a/handle/handle.go b/handle/handle.go
new file mode 100644
index 0000000..41d82b5
--- /dev/null
+++ b/handle/handle.go
@@ -0,0 +1,52 @@
+// SPDX-FileCopyrightText: 2026 Stefan Majewsky <majewsky@gmx.net>
+// SPDX-License-Identifier: Apache-2.0
+
+// Package handle contains type definitions for connecting non-std database drivers to Oblast.
+// Since most database drivers use the standard interface from databse/sql, the Wrap() function from the main package covers the needs of most users.
+package handle
+
+import (
+	"context"
+	"database/sql"
+)
+
+// Handle contains behavior that database handles must offer to Oblast.
+// The standard-library types [*sql.DB] and [*sql.Tx] can satisfy this interface through the Wrap() function from the main package.
+// Custom implementations of this interface can be used to connect non-std database drivers to Oblast.
+type Handle interface {
+	// Prepare prepares to execute a certain SQL query one or multiple times.
+	//
+	// The "repeated" flag is a hint to the implementation whether the same statement is going to be run many times.
+	// If false, the implementation shall choose to forego the additional effort of a full statement preparation if possible,
+	// and execute one-off queries instead.
+	Prepare(ctx context.Context, query string, repeated bool) (Statement, error)
+
+	// Query works like db.QueryContext(ctx, query, args...).
+	Query(ctx context.Context, query string, args []any) (Rows, error)
+}
+
+// Statement represents a prepared statement returned from [Handle.Prepare].
+// The Exec and QueryRow methods shall work similarly to the respective functions on [*sql.Tx], as indicated in the comments.
+//
+// You will not need to interact with this type except when implementing your own [Handle].
+type Statement interface {
+	Close() error
+
+	// Exec works like stmt.ExecContext(ctx, args...).
+	Exec(ctx context.Context, args []any) (sql.Result, error)
+
+	// QueryRow works like stmt.QueryRow(ctx, args...).Scan(slots...).
+	QueryRow(ctx context.Context, args []any, slots []any) error
+}
+
+// Rows represents a set of rows returned from [Handle.Query] in response to a DB query.
+// All methods shall behave like on the [*sql.Rows] type from std.
+//
+// You will not need to interact with this type except when implementing your own [Handle].
+type Rows interface {
+	Columns() ([]string, error)
+	Close() error
+	Err() error
+	Next() bool
+	Scan(slots ...any) error
+}