summaryrefslogtreecommitdiff
path: root/vendor/github.com/jackc/pgx/v5/doc.go
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/github.com/jackc/pgx/v5/doc.go')
-rw-r--r--vendor/github.com/jackc/pgx/v5/doc.go194
1 files changed, 0 insertions, 194 deletions
diff --git a/vendor/github.com/jackc/pgx/v5/doc.go b/vendor/github.com/jackc/pgx/v5/doc.go
deleted file mode 100644
index 0e91d64e8..000000000
--- a/vendor/github.com/jackc/pgx/v5/doc.go
+++ /dev/null
@@ -1,194 +0,0 @@
-// Package pgx is a PostgreSQL database driver.
-/*
-pgx provides a native PostgreSQL driver and can act as a database/sql driver. The native PostgreSQL interface is similar
-to the database/sql interface while providing better speed and access to PostgreSQL specific features. Use
-github.com/jackc/pgx/v5/stdlib to use pgx as a database/sql compatible driver. See that package's documentation for
-details.
-
-Establishing a Connection
-
-The primary way of establishing a connection is with [pgx.Connect]:
-
- conn, err := pgx.Connect(context.Background(), os.Getenv("DATABASE_URL"))
-
-The database connection string can be in URL or key/value format. Both PostgreSQL settings and pgx settings can be
-specified here. In addition, a config struct can be created by [ParseConfig] and modified before establishing the
-connection with [ConnectConfig] to configure settings such as tracing that cannot be configured with a connection
-string.
-
-Connection Pool
-
-[*pgx.Conn] represents a single connection to the database and is not concurrency safe. Use package
-github.com/jackc/pgx/v5/pgxpool for a concurrency safe connection pool.
-
-Query Interface
-
-pgx implements Query in the familiar database/sql style. However, pgx provides generic functions such as CollectRows and
-ForEachRow that are a simpler and safer way of processing rows than manually calling defer rows.Close(), rows.Next(),
-rows.Scan, and rows.Err().
-
-CollectRows can be used collect all returned rows into a slice.
-
- rows, _ := conn.Query(context.Background(), "select generate_series(1,$1)", 5)
- numbers, err := pgx.CollectRows(rows, pgx.RowTo[int32])
- if err != nil {
- return err
- }
- // numbers => [1 2 3 4 5]
-
-ForEachRow can be used to execute a callback function for every row. This is often easier than iterating over rows
-directly.
-
- var sum, n int32
- rows, _ := conn.Query(context.Background(), "select generate_series(1,$1)", 10)
- _, err := pgx.ForEachRow(rows, []any{&n}, func() error {
- sum += n
- return nil
- })
- if err != nil {
- return err
- }
-
-pgx also implements QueryRow in the same style as database/sql.
-
- var name string
- var weight int64
- err := conn.QueryRow(context.Background(), "select name, weight from widgets where id=$1", 42).Scan(&name, &weight)
- if err != nil {
- return err
- }
-
-Use Exec to execute a query that does not return a result set.
-
- commandTag, err := conn.Exec(context.Background(), "delete from widgets where id=$1", 42)
- if err != nil {
- return err
- }
- if commandTag.RowsAffected() != 1 {
- return errors.New("No row found to delete")
- }
-
-PostgreSQL Data Types
-
-pgx uses the pgtype package to converting Go values to and from PostgreSQL values. It supports many PostgreSQL types
-directly and is customizable and extendable. User defined data types such as enums, domains, and composite types may
-require type registration. See that package's documentation for details.
-
-Transactions
-
-Transactions are started by calling Begin.
-
- tx, err := conn.Begin(context.Background())
- if err != nil {
- return err
- }
- // Rollback is safe to call even if the tx is already closed, so if
- // the tx commits successfully, this is a no-op
- defer tx.Rollback(context.Background())
-
- _, err = tx.Exec(context.Background(), "insert into foo(id) values (1)")
- if err != nil {
- return err
- }
-
- err = tx.Commit(context.Background())
- if err != nil {
- return err
- }
-
-The Tx returned from Begin also implements the Begin method. This can be used to implement pseudo nested transactions.
-These are internally implemented with savepoints.
-
-Use BeginTx to control the transaction mode. BeginTx also can be used to ensure a new transaction is created instead of
-a pseudo nested transaction.
-
-BeginFunc and BeginTxFunc are functions that begin a transaction, execute a function, and commit or rollback the
-transaction depending on the return value of the function. These can be simpler and less error prone to use.
-
- err = pgx.BeginFunc(context.Background(), conn, func(tx pgx.Tx) error {
- _, err := tx.Exec(context.Background(), "insert into foo(id) values (1)")
- return err
- })
- if err != nil {
- return err
- }
-
-Prepared Statements
-
-Prepared statements can be manually created with the Prepare method. However, this is rarely necessary because pgx
-includes an automatic statement cache by default. Queries run through the normal Query, QueryRow, and Exec functions are
-automatically prepared on first execution and the prepared statement is reused on subsequent executions. See ParseConfig
-for information on how to customize or disable the statement cache.
-
-Copy Protocol
-
-Use CopyFrom to efficiently insert multiple rows at a time using the PostgreSQL copy protocol. CopyFrom accepts a
-CopyFromSource interface. If the data is already in a [][]any use CopyFromRows to wrap it in a CopyFromSource interface.
-Or implement CopyFromSource to avoid buffering the entire data set in memory.
-
- rows := [][]any{
- {"John", "Smith", int32(36)},
- {"Jane", "Doe", int32(29)},
- }
-
- copyCount, err := conn.CopyFrom(
- context.Background(),
- pgx.Identifier{"people"},
- []string{"first_name", "last_name", "age"},
- pgx.CopyFromRows(rows),
- )
-
-When you already have a typed array using CopyFromSlice can be more convenient.
-
- rows := []User{
- {"John", "Smith", 36},
- {"Jane", "Doe", 29},
- }
-
- copyCount, err := conn.CopyFrom(
- context.Background(),
- pgx.Identifier{"people"},
- []string{"first_name", "last_name", "age"},
- pgx.CopyFromSlice(len(rows), func(i int) ([]any, error) {
- return []any{rows[i].FirstName, rows[i].LastName, rows[i].Age}, nil
- }),
- )
-
-CopyFrom can be faster than an insert with as few as 5 rows.
-
-Listen and Notify
-
-pgx can listen to the PostgreSQL notification system with the `Conn.WaitForNotification` method. It blocks until a
-notification is received or the context is canceled.
-
- _, err := conn.Exec(context.Background(), "listen channelname")
- if err != nil {
- return err
- }
-
- notification, err := conn.WaitForNotification(context.Background())
- if err != nil {
- return err
- }
- // do something with notification
-
-
-Tracing and Logging
-
-pgx supports tracing by setting ConnConfig.Tracer. To combine several tracers you can use the multitracer.Tracer.
-
-In addition, the tracelog package provides the TraceLog type which lets a traditional logger act as a Tracer.
-
-For debug tracing of the actual PostgreSQL wire protocol messages see github.com/jackc/pgx/v5/pgproto3.
-
-Lower Level PostgreSQL Functionality
-
-github.com/jackc/pgx/v5/pgconn contains a lower level PostgreSQL driver roughly at the level of libpq. pgx.Conn in
-implemented on top of pgconn. The Conn.PgConn() method can be used to access this lower layer.
-
-PgBouncer
-
-By default pgx automatically uses prepared statements. Prepared statements are incompatible with PgBouncer. This can be
-disabled by setting a different QueryExecMode in ConnConfig.DefaultQueryExecMode.
-*/
-package pgx