scripttx

package
v1.153.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package scripttx is a managed script's transactions and batches on an application database (#2402): platform.transaction, which opens one transaction, calls the script's function with it and commits when the function returns, and platform.batch, which sends statements pipelined in one transaction of their own.

The bindings hold no connection. Every step -- opening the transaction, each statement in it, the commit or rollback -- is one call through the run's call path, answered by the session against the connection's pool (scriptsession's appdb calls). That is what makes a draft refuse a write inside a transaction, a recording keep each statement and how the transaction ended, and a script test replay it with the database stopped. Extracted from internal/platform/scriptrun for its size budget.

Index

Constants

View Source
const (
	CapabilityCopyIn  = "platform.copy_in"
	CapabilityCopyOut = "platform.copy_out"
)

The members of #2453.

View Source
const (
	CapabilityTransaction = "platform.transaction"
	CapabilityBatch       = "platform.batch"
)

The platform members this package binds.

View Source
const CapabilityMaintain = "platform.maintain"

CapabilityMaintain is platform.maintain (#2410).

View Source
const CapabilityQueryIter = "platform.query_iter"

CapabilityQueryIter is platform.query_iter (#2454).

View Source
const MaxAttempts = 3

MaxAttempts is how many times a retried transaction is tried: the first try and two retries.

Variables

View Source
var OutsideEffects = map[string]bool{
	"platform.call": true, "platform.query": true, "platform.execute": true, CapabilityBatch: true,
	CapabilityQueryIter: true, CapabilityCopyIn: true, CapabilityCopyOut: true, CapabilityMaintain: true,
	"platform.export": true, "platform.publish_data": true, "platform.notify": true, "platform.publish": true,
	"platform.save_state": true, "platform.mint_token": true,
}

OutsideEffects are the bindings a retried transaction's function may not call (#2402): each has an effect outside the transaction, which a retry would repeat. A function that is tried again must do nothing but read and write through its transaction.

Functions

func Retryable

func Retryable(err error) bool

Retryable reports whether err is a serialization failure or a deadlock, the failures a retried transaction is tried again on.

Types

type Host

type Host struct {
	// Ctx is the run's context.
	Ctx context.Context //nolint:containedctx // the run's lifetime, which the retry pause reads
	// Invoke issues one call where the run's calls go: the write barrier, the
	// call, and the record of what it wrote.
	Invoke func(b *starlark.Builtin, tool string, args map[string]any) (map[string]any, error)
	// Rows is platform.query's handling of a statement's rows: the row cap,
	// the byte cap and the truncation check.
	Rows func(name string, out map[string]any) (starlark.Value, error)
	// Failed hands a failed call to the script as on_error asked.
	Failed func(b *starlark.Builtin, err error, returnFailure bool) (starlark.Value, error)
	// Replaying is a test or a replay, whose answers are recorded: a retry
	// is tried again without pausing.
	Replaying bool
	// Check and Hold are the run's memory meter (#2454). The page a
	// query_iter loop holds is outside every value a walk of the
	// interpreter reaches, so it is reported with Hold (nil when the loop
	// ends) and counts toward the peak and the budget, which Check then
	// refuses past. Nil measures nothing.
	Check func(thread *starlark.Thread, at string) error
	Hold  func(page starlark.Value)
	// Export is platform.export's path under copy_out's name (#2453): the
	// copied bytes are written as an output the way an export's rows are.
	Export starlark.Callable
	// contains filtered or unexported fields
}

Host is the two members as a run binds them. One Host serves one run and holds whether a transaction's function is running, which Refuse reads.

func (*Host) Batch

func (h *Host) Batch(_ *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

Batch is platform.batch(connection, statements, on_error = ""): the statements pipelined in one transaction that commits when every one succeeds, and their results in order.

func (*Host) CopyIn

func (h *Host) CopyIn(_ *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

CopyIn is platform.copy_in(connection, table, columns, rows, on_error = ""): rows written into table's columns through COPY, in a transaction of their own, and the number written. A row is a list in columns' order or a dict keyed by column.

func (*Host) CopyOut

func (h *Host) CopyOut(thread *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

CopyOut is platform.copy_out(connection, name, sql, params = None, format = "csv", timeout_seconds = 0, on_error = "", and platform.export's destination, key, register, tags, metadata, scope, scope_id and index): the query's rows written as an output named name, in CSV with a header or in COPY's text format, every row of it however many max_rows allows a query, streamed from the database to the output and never held as the script's values.

func (*Host) Maintain

func (h *Host) Maintain(_ *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

Maintain is platform.maintain(connection, command, table = None, on_error = ""): ANALYZE, VACUUM (with ANALYZE) or REINDEX TABLE CONCURRENTLY, run outside a transaction, for the administrator or a persona the connection's schema_apply_personas names. It answers what ran and how long it took. Creating or dropping an index is refused naming manage_schema.

func (*Host) QueryIter

func (h *Host) QueryIter(thread *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

QueryIter is platform.query_iter(connection, sql, params = None, page_rows = 0, timeout_seconds = 0, on_error = ""): the query's rows, read in pages of page_rows from a cursor in a READ ONLY transaction of its own, as an iterable a script loops over. Each page is charged against the run's memory budget, so a loop holds one page at a time.

func (*Host) Refuse

func (h *Host) Refuse(name string) error

Refuse refuses a binding a retried transaction's function may not call.

func (*Host) Stopped

func (h *Host) Stopped() error

Stopped is the failure that stopped the run from inside a loop, nil when none did.

func (*Host) Transaction

func (h *Host) Transaction(thread *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

Transaction is platform.transaction(connection, fn, isolation = "read_committed", read_only = False, retry = False, on_error = ""): fn's return value, after the transaction it was handed committed.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL