aboutsummaryrefslogtreecommitdiff
path: root/gsql/gsql.go
blob: 23068fd1aca2f09295c0fed01af4131a0ccb2e53 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
// SPDX-FileCopyrightText: 2026 Stefan Majewsky <majewsky@gmx.net>
// SPDX-License-Identifier: Apache-2.0

// Package gsql abstracts over database libraries, supporting both database/sql drivers and non-standard drivers like [pgx].
// The main abstractions are [Handle] and [ConnectionHandle].
//
// This package only provides [Handle] implementations for use with database/sql.
// A [Handle] implementation for use with [pgx] is provided in [gg-pgx].
//
// [pgx]: https://github.com/jackc/pgx
// [gg-pgx]: https://pkg.go.dev/go.xyrillian.de/gg-pgx
package gsql

import (
	"context"
	"database/sql"
	"errors"

	"go.xyrillian.de/gg/errext"
	. "go.xyrillian.de/gg/option"
)

// ConnectionHandle extends [Handle] with methods that make sense for handles referring to entire connections or connection pools, but not e.g. to transactions.
// The standard-library types [*sql.DB] and [*sql.Conn] can satisfy this interface through the wrappers [NewDB] and [NewConn].
//
// Like for [Handle], the method names are deliberately clunky to avoid name clashes with well-known methods.
type ConnectionHandle interface {
	Handle

	// GSQLClose closes the connection represented by this handle.
	// Once this method has been called, other methods must not be called.
	GSQLClose(ctx context.Context) error

	// GSQLTransact executes an action within a database transaction.
	// The callback will be provided with a [Handle] referring to the transaction.
	// The transaction will be committed if the callback returns successfully, or rolled back otherwise.
	GSQLTransact(ctx context.Context, action func(tx Handle) error) error
}

// Handle can be implemented by objects that allow executing SQL queries.
// The standard-library types [*sql.DB], [*sql.Conn] and [*sql.Tx] can satisfy this interface through the wrappers [NewDB], [NewConn] and [NewTx].
// Custom implementations of this interface can be used to connect non-std database drivers to functions accepting this interface.
//
// The method names are deliberately clunky to avoid name clashes with well-known methods like [sql.DB.Prepare] or [sql.DB.Query].
type Handle interface {
	// GSQLPrepare 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.
	GSQLPrepare(ctx context.Context, query string, repeated bool) (Statement, error)

	// GSQLQuery works like db.QueryContext(ctx, query, args...).
	GSQLQuery(ctx context.Context, query string, args []any) (Rows, error)
}

// Statement represents a prepared statement returned from the GSQLPrepare() method of [Handle].
// The Exec and QueryRow methods shall work similarly to the respective functions on [*sql.Stmt], 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...).
	// The returned Result object must remain usable after Close() is called on this Statement instance.
	Exec(ctx context.Context, args []any) (sql.Result, error)

	// QueryRow works like stmt.QueryRowContext(ctx, args...).Scan(slots...).
	QueryRow(ctx context.Context, args []any, slots []any) error
}

// Rows represents a set of rows returned from the GSQLQuery() method of [Handle].
// 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
}

// NoneIfNoRows wraps any call returning a record from a DB that may return [sql.ErrNoRows],
// and converts that error into a [None] in the value position instead.
//
// [None]: https://pkg.go.dev/go.xyrillian.de/gg/option#None
func NoneIfNoRows[T any](value T, err error) (Option[T], error) {
	switch {
	case err == nil:
		return Some(value), nil
	case errors.Is(err, sql.ErrNoRows):
		return None[T](), nil
	default:
		return None[T](), err
	}
}

// Exec is a shorthand for preparing and executing a one-off query that returns an [sql.Result].
//
// For executing the same query multiple times, see [WithPreparedStatement].
//
// For shorthands involving [Statement.QueryRow] instead of [Statement.Exec],
// look at Select() and SelectOne() in [gg/oblast].
//
// [gg/oblast]: https://pkg.go.dev/go.xyrillian.de/gg/oblast
func Exec(ctx context.Context, db Handle, query string, args ...any) (sql.Result, error) {
	stmt, err := db.GSQLPrepare(ctx, query, false)
	if err != nil {
		return nil, err
	}
	result, err := stmt.Exec(ctx, args)
	return result, errext.WithCleanup(err, "Statement.Close", stmt.Close())
}

// WithPreparedStatement is a shorthand for preparing a query to be executed multiple times.
// The provided action callback will be executed with access to the [PreparedStatement],
// which will automatically be closed once the callback returns.
//
// For executing a query just once, see [Exec].
func WithPreparedStatement(ctx context.Context, db Handle, query string, action func(stmt PreparedStatement) error) error {
	stmt, err := db.GSQLPrepare(ctx, query, true)
	if err != nil {
		return err
	}
	err = action(PreparedStatement{stmt})
	return errext.WithCleanup(err, "Statement.Close", stmt.Close())
}

// PreparedStatement is made available to actions executed within [WithPreparedStatement];
// see documentation over there for details.
type PreparedStatement struct {
	stmt Statement
}

// Exec is like [Statement.Exec], but takes args as a variadic parameter for ergonomic reasons.
func (p PreparedStatement) Exec(ctx context.Context, args ...any) (sql.Result, error) {
	// TODO(v2): change Statement.Exec to variadic and remove this type, using Statement directly instead
	return p.stmt.Exec(ctx, args)
}