backend

type Backend interface {
	// OpenSession establishes the server-side session. Called once by the
	// connector factory at connect time, before the conn is handed to the pool.
	OpenSession(ctx context.Context) error

	// CloseSession tears down the server-side session. Called from conn.Close.
	CloseSession(ctx context.Context) error

	// SessionValid backs driver.Validator (conn.IsValid): it reports whether the
	// session is still usable, so a broken conn is evicted from the pool rather
	// than reused. It does no I/O — it inspects state captured at OpenSession.
	SessionValid() bool

	// SessionID is the formatted server session id (conn.id). Valid only after a
	// successful OpenSession; empty otherwise.
	SessionID() string

	// Execute runs a statement to a terminal state and returns an Operation
	// describing the outcome.
	//
	// An implementation MUST return a non-nil Operation, even when err is non-nil:
	// the caller reads StatementID, wraps the error via ExecutionError, and closes
	// the operation via Close on both the success and failure paths. When the
	// server returned no handle, the accessors return zero values (StatementID "",
	// Close closed=false) rather than panicking.
	Execute(ctx context.Context, req ExecRequest) (Operation, error)
}

type ExecRequest struct {
	// Query is the SQL text to execute.
	Query string
	// Params are the bound query parameters, already type-inferred and rendered
	// to their string wire form (see Param); empty when the statement has none.
	// Inference lives in the dbsql package because it depends on the public
	// dbsql.Parameter/SqlType types; each backend maps these neutral params to its
	// own wire type.
	Params []Param
}

type Operation interface {
	// StatementID is the server statement/operation id (empty if the server
	// returned no handle).
	StatementID() string

	// AffectedRows is the modified-row count for ExecContext results. Unlike the
	// other accessors it is defined only on the success path — the caller reads it
	// only after Execute returned a nil error — so an implementation need not make
	// it safe to call on a failed/handle-less operation.
	AffectedRows() int64

	// Results builds the driver.Rows for the operation's result set. The callbacks
	// carry the telemetry hooks (chunk timing, close, CloudFetch file); the caller
	// supplies whichever subset it needs (a full query wires all three, the
	// staging path wires only chunk timing).
	//
	// On the query path the returned Rows owns closing the server-side operation:
	// the caller does not invoke Operation.Close on that path and relies on
	// Rows.Close to issue any needed teardown RPC. See the type-level Operation
	// comment for the idempotency contract this places on both closers.
	Results(ctx context.Context, callbacks *dbsqlrows.TelemetryCallbacks) (driver.Rows, error)

	// IsStaging reports whether this is a staging (PUT/GET/REMOVE) operation. It
	// may issue a metadata lookup if the answer is not already available from
	// direct results.
	IsStaging(ctx context.Context) (bool, error)

	// Close best-effort closes the server-side operation, if one is still open.
	// It is called only on the exec/staging paths — on the query path the
	// returned Rows owns close (see the Operation and Results doc comments).
	// It is idempotent and safe to call regardless of whether execution
	// succeeded: a second call on the same Operation, or a call after Rows.Close
	// already tore down the server operation, must be a no-op rather than
	// issuing a duplicate close RPC. closed reports whether a close RPC was
	// actually issued (false when the operation had no handle, was already
	// closed via direct results, was already closed by a prior invocation, or
	// was already closed via Rows.Close), so the caller can record
	// CLOSE_STATEMENT telemetry only when a real close happened.
	Close(ctx context.Context) (closed bool, err error)

	// ExecutionError wraps cause as the driver's execution error, attaching this
	// operation's terminal sqlstate. Returns nil when cause is nil.
	ExecutionError(ctx context.Context, cause error) error
}

type Param struct {
	Name  string
	Type  string
	Value *string
}