appdbconsole

package
v1.153.1 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: 6 Imported by: 0

Documentation

Overview

Package appdbconsole is an administrator's direct way into an application database (#2427): statements run in one transaction as the connection's own login, READ ONLY unless asked otherwise, and canceling or terminating a backend of the connection's own roles (#2410). The admin API calls it.

Index

Constants

View Source
const (
	// MaxConsoleStatements is the most statements one console request runs.
	MaxConsoleStatements = 50
	// MaxConsoleSQLBytes is the most SQL text one console request carries.
	MaxConsoleSQLBytes = 1 << 20
)

Console bounds.

View Source
const (
	SignalCancel    = "cancel"
	SignalTerminate = "terminate"
)

The signals a backend can be sent.

Variables

This section is empty.

Functions

This section is empty.

Types

type ConsoleError

type ConsoleError struct {
	Index   int    `json:"index"`
	Code    string `json:"code"`
	Summary string `json:"summary"`
	Detail  string `json:"detail,omitempty"`
}

ConsoleError is the statement the database refused. Summary is the value-free account the audit row and the logs may carry; Detail is what the server said, DETAIL and HINT included, which can repeat a value and goes to the administrator alone.

type ConsoleRequest

type ConsoleRequest struct {
	SQL        string             `json:"sql,omitempty"`
	Params     any                `json:"params,omitempty"`
	Statements []ConsoleStatement `json:"statements,omitempty"`
	// ReadOnly runs the transaction READ ONLY; nil is true. A write needs it
	// turned off for the request that makes it.
	ReadOnly *bool `json:"read_only,omitempty"`
}

ConsoleRequest is what an administrator runs in the console (#2427): one statement, several separated by semicolons in sql, or a list. Every statement runs in one transaction, READ ONLY unless ReadOnly is false.

func (ConsoleRequest) IsReadOnly

func (r ConsoleRequest) IsReadOnly() bool

IsReadOnly is whether the request runs READ ONLY.

func (ConsoleRequest) Parse

func (r ConsoleRequest) Parse() ([]ConsoleStatement, error)

Parse is the statements a request runs, split from sql when it carries no list, checked against the console's bounds.

type ConsoleResult

type ConsoleResult struct {
	Connection string `json:"connection"`
	ReadOnly   bool   `json:"read_only"`
	// Committed is true when a read-write transaction committed.
	Committed bool              `json:"committed"`
	Results   []StatementResult `json:"results"`
	// Error is the statement that failed, after which nothing more ran and
	// the transaction rolled back.
	Error *ConsoleError `json:"error,omitempty"`
}

ConsoleResult is what a console request did.

func RunConsole

func RunConsole(ctx context.Context, kit Transactor, connection string, req ConsoleRequest) (*ConsoleResult, error)

RunConsole runs a console request on connection as the connection's own login, through its pool, in one transaction.

type ConsoleStatement

type ConsoleStatement struct {
	SQL    string `json:"sql"`
	Params any    `json:"params,omitempty"`
}

ConsoleStatement is one statement and the values bound to its placeholders: a list binds $1, $2, ... and an object binds @name.

type ParamShape

type ParamShape struct {
	Name     string `json:"name,omitempty"`
	Position int    `json:"position,omitempty"`
	Type     string `json:"type"`
}

ParamShape is a bound parameter as the audit row records it: its name or position and the JSON type of its value, never the value.

func Shapes

func Shapes(params any) []ParamShape

Shapes reads the parameters of a statement into their shapes.

type RefusedError

type RefusedError struct {
	// contains filtered or unexported fields
}

RefusedError is a signal the platform will not send, with why.

func (*RefusedError) Error

func (e *RefusedError) Error() string

type SignalResult

type SignalResult struct {
	Connection string `json:"connection"`
	Signal     string `json:"signal"`
	PID        int64  `json:"pid"`
	// Sent is whether PostgreSQL delivered it.
	Sent bool `json:"sent"`
}

SignalResult is what a signal did.

func Signal

func Signal(ctx context.Context, s Signaller, connection, signal string, pid int64) (*SignalResult, error)

Signal cancels the statement a backend runs, or terminates the backend (#2410). It acts only on a backend in the connection's database logged in as one of the connection's roles: any other backend is not the platform's.

type Signaller

type Signaller interface {
	Query(ctx context.Context, s postgres.Statement) (*postgres.Result, error)
	ConnectionRoles(connection string) []string
}

Signaller runs a read-only statement and names the connection's roles: the postgres toolkit.

type StatementResult

type StatementResult struct {
	Index        int               `json:"index"`
	Command      string            `json:"command"`
	RowsAffected int64             `json:"rows_affected"`
	Columns      []postgres.Column `json:"columns"`
	Rows         [][]any           `json:"rows"`
	Truncated    bool              `json:"truncated"`
}

StatementResult is what one statement returned.

type Toolkit

type Toolkit struct{ *postgres.Toolkit }

Toolkit is the postgres toolkit as a Transactor.

func (Toolkit) ConsoleTx

func (t Toolkit) ConsoleTx(ctx context.Context, connection string, readOnly bool) (Tx, error)

ConsoleTx implements Transactor.

type Transactor

type Transactor interface {
	ConsoleTx(ctx context.Context, connection string, readOnly bool) (Tx, error)
}

Transactor opens a console request's transaction.

type Tx

type Tx interface {
	Query(ctx context.Context, s postgres.Statement) (*postgres.Result, error)
	Commit(ctx context.Context) error
	Rollback()
}

Tx is the transaction a console request runs in: the postgres toolkit's.

Jump to

Keyboard shortcuts

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