Documentation
¶
Overview ¶
Package sqldb provides Encore services direct access to their databases.
For the documentation on how to use databases within Encore see https://encore.dev/docs/develop/databases.
Index ¶
- Variables
- func Commit(tx *Tx) (_ error)
- func Driver[T SupportedDrivers](db *Database) (_ T)
- func DriverConn[T SupportedDriverConns](conn *sql.Conn, f func(driverConn T) error) (_ error)
- func ErrCode(err error) (_ sqlerr.Code)
- func RegisterStdlibDriver(db *Database) (_ string)
- func Rollback(tx *Tx) (_ error)
- type Database
- func (*Database) Begin(ctx context.Context) (_ *Tx, _ error)
- func (*Database) Exec(ctx context.Context, query string, args ...interface{}) (_ ExecResult, _ error)
- func (*Database) Query(ctx context.Context, query string, args ...interface{}) (_ *Rows, _ error)
- func (*Database) QueryRow(ctx context.Context, query string, args ...interface{}) (_ *Row)
- func (*Database) Stdlib() (_ *sql.DB)
- type DatabaseConfig
- type Error
- type ExecResult
- type Row
- type Rows
- type SupportedDriverConns
- type SupportedDrivers
- type Tx
- func (*Tx) Commit() (_ error)
- func (*Tx) Exec(ctx context.Context, query string, args ...interface{}) (_ ExecResult, _ error)
- func (*Tx) Query(ctx context.Context, query string, args ...interface{}) (_ *Rows, _ error)
- func (*Tx) QueryRow(ctx context.Context, query string, args ...interface{}) (_ *Row)
- func (*Tx) Rollback() (_ error)
Constants ¶
This section is empty.
Variables ¶
var ErrNoRows = sql.ErrNoRows
ErrNoRows is an error reported by Scan when QueryRow doesn't return a row. It must be tested against with errors.Is.
Functions ¶
func Commit ¶
Commit commits the given transaction.
See (*database/sql.Tx).Commit() for additional documentation. Deprecated: use tx.Commit() instead.
func Driver ¶ added in v1.12.0
func Driver[T SupportedDrivers](db *Database) (_ T)
Driver returns the underlying database driver for this database connection pool.
var db = sqldb.Driver[*pgxpool.Pool](sqldb.Named("mydatabase"))
This is defined as a generic function to allow compile-time type checking that the Encore application is expecting a driver that is supported.
At some point in the future where Encore adds support for a different database driver this will be made with backwards compatibility in mind, providing ample notice and time to migrate in an opt-in fashion.
func DriverConn ¶ added in v1.16.1
func DriverConn[T SupportedDriverConns](conn *sql.Conn, f func(driverConn T) error) (_ error)
DriverConn provides access to the underlying driver connection given a stdlib *sql.Conn connection. The driverConn must not be used outside of f, and conn must be a *sql.Conn originating from sqldb.Database or this function panics.
conn, _ := db.Stdlib().Conn(ctx) // Checkout a connection from the pool
sqldb.DriverConn(conn, func(driverConn *pgx.Conn) error) error {
// do stuff with *pgx.Conn
}
This is defined as a generic function to allow compile-time type checking that the Encore application is expecting a driver that is supported.
At some point in the future where Encore adds support for a different database driver this will be made with backwards compatibility in mind, providing ample notice and time to migrate in an opt-in fashion.
func ErrCode ¶ added in v1.11.0
ErrCode reports the error code for a given error. If the error is nil or is not of type *Error it reports sqlerr.Other.
func RegisterStdlibDriver ¶ added in v1.27.0
RegisterStdlibDriver returns a connection string that can be used with the standard library's sql.Open function to connect to the same db.
The connection string should be used with the "encore" driver name:
connStr := sqldb.RegisterStdlibDriver(myDB)
db, err := sql.Open("encore", connStr)
The main use case is to support libraries that expect to call sql.Open themselves without exposing the underlying database credentials.
Types ¶
type Database ¶ added in v0.17.0
type Database struct {
// contains filtered or unexported fields
}
func Named ¶ added in v0.17.0
func Named(name constStr) (_ *Database)
Named returns a database object connected to the database with the given name.
The name must be a string literal constant, to facilitate static analysis.
func NewDatabase ¶ added in v1.17.0
func NewDatabase(name string, config DatabaseConfig) (_ *Database)
NewDatabase declares a new SQL database.
Encore uses static analysis to identify databases and their configuration, so all parameters passed to this function must be constant literals.
A call to NewDatabase can only be made when declaring a package level variable. Any calls to this function made outside a package level variable declaration will result in a compiler error.
The database name must be unique within the Encore application. Database names must be defined in kebab-case (lowercase alphanumerics and hyphen separated). Once created and deployed never change the database name, or else a new database will be created.
func (*Database) Begin ¶ added in v0.17.0
Begin opens a new database transaction.
See (*database/sql.DB).Begin() for additional documentation.
func (*Database) Exec ¶ added in v0.17.0
func (*Database) Exec(ctx context.Context, query string, args ...interface{}) (_ ExecResult, _ error)
Exec executes a query without returning any rows. The args are for any placeholder parameters in the query.
See (*database/sql.DB).ExecContext() for additional documentation.
func (*Database) Query ¶ added in v0.17.0
Query executes a query that returns rows, typically a SELECT. The args are for any placeholder parameters in the query.
See (*database/sql.DB).QueryContext() for additional documentation.
type DatabaseConfig ¶ added in v1.17.0
type DatabaseConfig struct {
// Migrations is the directory containing the migration files
// for this database.
//
// The path must be slash-separated relative path, and must be rooted within
// the package directory (it cannot contain "../").
// Valid paths are, for example, "migrations" or "db/migrations".
//
// Migrations are an ordered sequence of sql files of the format <number>_<description>.up.sql.
Migrations string
}
DatabaseConfig specifies configuration for declaring a new database.
type Error ¶ added in v1.11.0
type Error struct {
// Code defines the general class of the error.
// See [sqlerr.Code] for a list of possible values.
Code sqlerr.Code
// Severity is the severity of the error.
Severity sqlerr.Severity
// DatabaseCode is the database server-specific error code.
// It is specific to the underlying database server.
DatabaseCode string
// Message: the primary human-readable error message. This should be accurate
// but terse (typically one line). Always present.
Message string
// SchemaName: if the error was associated with a specific database object,
// the name of the schema containing that object, if any.
SchemaName string
// TableName: if the error was associated with a specific table, the name of the table.
// (Refer to the schema name field for the name of the table's schema.)
TableName string
// ColumnName: if the error was associated with a specific table column,
// the name of the column. (Refer to the schema and table name fields to identify the table.)
ColumnName string
// Data type name: if the error was associated with a specific data type,
// the name of the data type. (Refer to the schema name field for the name of the data type's schema.)
DataTypeName string
// Constraint name: if the error was associated with a specific constraint,
// the name of the constraint. Refer to fields listed above for the associated
// table or domain. (For this purpose, indexes are treated as constraints,
// even if they weren't created with constraint syntax.)
ConstraintName string
}
Error represents an error reported by the database server. It's not guaranteed all errors reported by sqldb functions will be of this type; it is only returned when the database reports an error.
Note that the fields for schema name, table name, column name, data type name, and constraint name are supplied only for a limited number of error types; see https://www.postgresql.org/docs/current/errcodes-appendix.html.
You should not assume that the presence of any of these fields guarantees the presence of another field.
type ExecResult ¶ added in v0.17.0
type ExecResult interface {
// RowsAffected returns the number of rows affected. If the result was not
// for a row affecting command (e.g. "CREATE TABLE") then it returns 0.
RowsAffected() int64
}
ExecResult is the result of an Exec query.
type Row ¶
type Row struct {
// contains filtered or unexported fields
}
Row is the result of calling QueryRow to select a single row.
See *database/sql.Row for additional documentation.
func QueryRow ¶
QueryRow executes a query that is expected to return at most one row.
See (*database/sql.DB).QueryRowContext() for additional documentation.
func QueryRowTx ¶
QueryRowTx is like QueryRow but executes the query in the given transaction.
See (*database/sql.Tx).QueryRowContext() for additional documentation. Deprecated: use tx.QueryRow() instead.
type Rows ¶
type Rows struct {
// contains filtered or unexported fields
}
Rows is the result of a query. Its cursor starts before the first row of the result set. Use Next to advance from row to row.
See *database/sql.Rows for additional documentation.
func Query ¶
Query executes a query that returns rows, typically a SELECT. The args are for any placeholder parameters in the query.
See (*database/sql.DB).QueryContext() for additional documentation.
func QueryTx ¶
QueryTx is like Query but executes the query in the given transaction.
See (*database/sql.Tx).QueryContext() for additional documentation. Deprecated: use tx.Query() instead.
func (*Rows) Close ¶
func (*Rows) Close()
Close closes the Rows, preventing further enumeration.
See (*database/sql.Rows).Close() for additional documentation.
func (*Rows) Err ¶
Err returns the error, if any, that was encountered during iteration. Err may be called after an explicit or implicit Close.
See (*database/sql.Rows).Err() for additional documentation.
func (*Rows) Next ¶
Next prepares the next result row for reading with the Scan method. It returns true on success, or false if there is no next result row or an error happened while preparing it. Err should be consulted to distinguish between the two cases.
Every call to Scan, even the first one, must be preceded by a call to Next.
See (*database/sql.Rows).Next() for additional documentation.
type SupportedDriverConns ¶ added in v1.16.1
type SupportedDriverConns interface {
*pgx.Conn
}
SupportedDriverConns is a type list of all supported database drivers connections. Currently only *pgx.Conn is supported.
type SupportedDrivers ¶ added in v1.12.0
SupportedDrivers is a type list of all supported database drivers. Currently only *pgxpool.Pool is supported.
type Tx ¶
type Tx struct {
// contains filtered or unexported fields
}
Tx is a handle to a database transaction.
See *database/sql.Tx for additional documentation.
func Begin ¶
Begin opens a new database transaction.
See (*database/sql.DB).Begin() for additional documentation.
func (*Tx) Commit ¶ added in v0.17.0
Commit commits the given transaction.
See (*database/sql.Tx).Commit() for additional documentation.
Source Files
Directories