GOMODULES
/
pgx
mirror of https://github.com/jackc/pgx.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Rewrap doc.go

pull/594/head
Jack Christensen 2019-08-24 20:46:36 -05:00
parent 3675337e5b
commit ebf88b691f
1 changed files with 30 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
doc.go
View File

@ -1,8 +1,7 @@
// Package pgx is a PostgreSQL database driver. // Package pgx is a PostgreSQL database driver.
/* /*
pgx provides lower level access to PostgreSQL than the standard database/sql. pgx provides lower level access to PostgreSQL than the standard database/sql. It remains as similar to the database/sql
It remains as similar to the database/sql interface as possible while interface as possible while providing better speed and access to PostgreSQL specific features. Import
providing better speed and access to PostgreSQL specific features. Import
github.com/jackc/pgx/v4/stdlib to use pgx as a database/sql compatible driver. github.com/jackc/pgx/v4/stdlib to use pgx as a database/sql compatible driver.
Query Interface Query Interface
@ -66,8 +65,7 @@ See sub-package pgxpool for connection pool.
Base Type Mapping Base Type Mapping
pgx maps between all common base types directly between Go and PostgreSQL. In pgx maps between all common base types directly between Go and PostgreSQL. In particular:
particular:
Go PostgreSQL Go PostgreSQL
----------------------- -----------------------
@ -100,9 +98,8 @@ particular:
Null Mapping Null Mapping
pgx can map nulls in two ways. The first is package pgtype provides types that pgx can map nulls in two ways. The first is package pgtype provides types that have a data field and a status field.
have a data field and a status field. They work in a similar fashion to They work in a similar fashion to database/sql. The second is to use a pointer to a pointer.
database/sql. The second is to use a pointer to a pointer.
var foo pgtype.Varchar var foo pgtype.Varchar
var bar *string var bar *string
@ -113,53 +110,44 @@ database/sql. The second is to use a pointer to a pointer.
Array Mapping Array Mapping
pgx maps between int16, int32, int64, float32, float64, and string Go slices pgx maps between int16, int32, int64, float32, float64, and string Go slices and the equivalent PostgreSQL array type.
and the equivalent PostgreSQL array type. Go slices of native types do not Go slices of native types do not support nulls, so if a PostgreSQL array that contains a null is read into a native Go
support nulls, so if a PostgreSQL array that contains a null is read into a slice an error will occur. The pgtype package includes many more array types for PostgreSQL types that do not directly
native Go slice an error will occur. The pgtype package includes many more map to native Go types.
array types for PostgreSQL types that do not directly map to native Go types.
JSON and JSONB Mapping JSON and JSONB Mapping
pgx includes built-in support to marshal and unmarshal between Go types and pgx includes built-in support to marshal and unmarshal between Go types and the PostgreSQL JSON and JSONB.
the PostgreSQL JSON and JSONB.
Inet and CIDR Mapping Inet and CIDR Mapping
pgx encodes from net.IPNet to and from inet and cidr PostgreSQL types. In pgx encodes from net.IPNet to and from inet and cidr PostgreSQL types. In addition, as a convenience pgx will encode
addition, as a convenience pgx will encode from a net.IP; it will assume a /32 from a net.IP; it will assume a /32 netmask for IPv4 and a /128 for IPv6.
netmask for IPv4 and a /128 for IPv6.
Custom Type Support Custom Type Support
pgx includes support for the common data types like integers, floats, strings, pgx includes support for the common data types like integers, floats, strings, dates, and times that have direct
dates, and times that have direct mappings between Go and SQL. In addition, mappings between Go and SQL. In addition, pgx uses the github.com/jackc/pgx/pgtype library to support more types. See
pgx uses the github.com/jackc/pgx/pgtype library to support more types. See documention for that library for instructions on how to implement custom types.
documention for that library for instructions on how to implement custom
types.
See example_custom_type_test.go for an example of a custom type for the See example_custom_type_test.go for an example of a custom type for the PostgreSQL point type.
PostgreSQL point type.
pgx also includes support for custom types implementing the database/sql.Scanner pgx also includes support for custom types implementing the database/sql.Scanner and database/sql/driver.Valuer
and database/sql/driver.Valuer interfaces. interfaces.
If pgx does cannot natively encode a type and that type is a renamed type (e.g. If pgx does cannot natively encode a type and that type is a renamed type (e.g. type MyTime time.Time) pgx will attempt
type MyTime time.Time) pgx will attempt to encode the underlying type. While to encode the underlying type. While this is usually desired behavior it can produce suprising behavior if one the
this is usually desired behavior it can produce suprising behavior if one the underlying type and the renamed type each implement database/sql interfaces and the other implements pgx interfaces. It
underlying type and the renamed type each implement database/sql interfaces and is recommended that this situation be avoided by implementing pgx interfaces on the renamed type.
the other implements pgx interfaces. It is recommended that this situation be
avoided by implementing pgx interfaces on the renamed type.
Raw Bytes Mapping Raw Bytes Mapping
[]byte passed as arguments to Query, QueryRow, and Exec are passed unmodified []byte passed as arguments to Query, QueryRow, and Exec are passed unmodified to PostgreSQL.
to PostgreSQL.
Transactions Transactions
Transactions are started by calling Begin. The second argument Transactions are started by calling Begin. The second argument can create a transaction with a specified isolation
can create a transaction with a specified isolation level. level.
tx, err := conn.Begin(context.Background(), nil) tx, err := conn.Begin(context.Background(), nil)
if err != nil { if err != nil {
@ -187,10 +175,9 @@ automatically prepared on first execution and the prepared statement is reused o
Copy Protocol Copy Protocol
Use CopyFrom to efficiently insert multiple rows at a time using the PostgreSQL Use CopyFrom to efficiently insert multiple rows at a time using the PostgreSQL copy protocol. CopyFrom accepts a
copy protocol. CopyFrom accepts a CopyFromSource interface. If the data is already CopyFromSource interface. If the data is already in a [][]interface{} use CopyFromRows to wrap it in a CopyFromSource
in a [][]interface{} use CopyFromRows to wrap it in a CopyFromSource interface. Or interface. Or implement CopyFromSource to avoid buffering the entire data set in memory.
implement CopyFromSource to avoid buffering the entire data set in memory.
rows := [][]interface{}{ rows := [][]interface{}{
{"John", "Smith", int32(36)}, {"John", "Smith", int32(36)},
@ -212,9 +199,8 @@ Use the underlying pgconn.PgConn for listen and notify.
Logging Logging
pgx defines a simple logger interface. Connections optionally accept a logger pgx defines a simple logger interface. Connections optionally accept a logger that satisfies this interface. Set
that satisfies this interface. Set LogLevel to control logging verbosity. LogLevel to control logging verbosity. Adapters for github.com/inconshreveable/log15, github.com/sirupsen/logrus, and
Adapters for github.com/inconshreveable/log15, github.com/sirupsen/logrus, and
the testing log are provided in the log directory. the testing log are provided in the log directory.
*/ */
package pgx package pgx