diff --git a/Getting-started-with-pgx-through-database-sql.md b/Getting-started-with-pgx-through-database-sql.md new file mode 100644 index 0000000..2f25e61 --- /dev/null +++ b/Getting-started-with-pgx-through-database-sql.md @@ -0,0 +1,99 @@ +# Getting started with pgx through database/sql + +This is a step by step guide to your first database connection with pgx through the standard Go `database/sql` interface. + +The `database/sql` interface should be used when compatibility with non-PostgreSQL databases is required or when using other libraries that require `database/sql` such as [sqlx](https://github.com/jmoiron/sqlx) or [gorm](https://gorm.io/). If this is not the case, prefer the direct pgx interface which offers greater performance and features. + +## Prerequisites + +pgx requires a recent version of Go with module support. Use the `go version` command to display your current version of Go. + +``` +$ go version +go version go1.14.2 darwin/amd64 +``` + +The version should be at least 1.13. + +pgx also requires a PostgreSQL database that is accessible from your host. Use `psql` to test your connection. + +``` +$ psql +Timing is on. +Null display is "∅". +Line style is unicode. +psql (12.3) +Type "help" for help. + +jack@[local]:5432 jack=# +``` + +Only move on to the next step once you have confirmed a working Go install and PostgreSQL connection. + +## Initializing a Project + +pgx uses Go modules. Create a new directory for your project and `cd` into it. + +``` +$ mkdir hello +$ cd hello +``` + +Initialize Go modules for the project. + +``` +$ go mod init hello +go: creating new go.mod: module hello +``` + +## Hello world from PostgreSQL + +Create the file `main.go` and copy and paste the following: + +```go +package main + +import ( + "database/sql" + "fmt" + "os" + + _ "github.com/jackc/pgx/v4/stdlib" +) + +func main() { + db, err := sql.Open("pgx", os.Getenv("DATABASE_URL")) + if err != nil { + fmt.Fprintf(os.Stderr, "Unable to connect to database: %v\n", err) + os.Exit(1) + } + defer db.Close() + + var greeting string + err = db.QueryRow("select 'Hello, world!'").Scan(&greeting) + if err != nil { + fmt.Fprintf(os.Stderr, "QueryRow failed: %v\n", err) + os.Exit(1) + } + + fmt.Println(greeting) +} +``` + +Save the file. + +This example will use the database URL specified in the environment variable `DATABASE_URL`. pgx supports standard PostgreSQL environment variables such as `PGHOST` and `PGDATABASE`. + +Use the same connection settings as were used when testing with `psql` above. If your `psql` connection did not require any arguments then you should not need to specify any for pgx (pgx uses similar logic as `psql` for default connection values). + +``` +$ go run main.go +Hello, world! +``` + +You may see some output from Go when it downloads pgx for the first time. + +``` +go: finding module for package github.com/jackc/pgx/v4 +go: found github.com/jackc/pgx/v4 in github.com/jackc/pgx/v4 v4.6.0 +```