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 ¶
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.
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 ¶
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.