Create a database session
Use go get
to grab the database adapter:
export GO111MODULE=on
go get -v -u github.com/upper/db/v4/adapter/$ADAPTER_NAME
Import the adapter package into your application:
import (
"github.com/upper/db/v4/adapter/{{adapter_name}}"
)
{{adapter_name}}
could be any of the following supported adapters:
postgresql
, mysql
, cockroachdb
, mssql
, sqlite
, ql
or mongodb
.
In this example we'll use the postgresql
adapter:
import (
"github.com/upper/db/v4/adapter/postgresql"
)
All adapters come with a ConnectionURL
struct that you can use to describe
parameters to open a database:
import (
"github.com/upper/db/v4/adapter/postgresql"
)
// Use the `ConnectionURL` struct to create a DSN:
var settings = postgresql.ConnectionURL{
User: "maria",
Password: "p4ss",
Address: "10.0.0.99",
Database: "myprojectdb",
}
fmt.Printf("DSN: %s", settings)
also, every adapter comes with an Open()
function that takes a
ConnectionURL
and attempts to create a database session:
// sess is a db.Session type
sess, err := postgresql.Open(settings)
...
Instead of
postgresql.ConnectionURL
you can usemysql.ConnectionURL
,mssql.ConnectionURL
, etc. All of these structs satisfydb.ConnectionURL
.
It is also possible to use a DSN string like
([adapter]://[user]:[password]@[host]/[database]
), you can easily convert it
into a ConnectionURL
struct and use it to connect to a database by using the
ParseURL
function that comes with your adapter:
import (
...
"github.com/upper/db/v4/adapter/postgresql"
...
)
const connectDSN = `postgres://demouser:[email protected]/booktown`
// Convert the DSN into a ConnectionURL
settings, err := postgresql.ParseURL(connectDSN)
...
// And use it to connect to your database.
sess, err := postgresql.Open(settings)
...
log.Println("Now you're connected to the database!")
Once you finish to work with the database session, use Close()
to free all
associated resources and caches. Keep in mind that Go apps are long-lived
processes, you may never need to manually Close()
a session unless you don't
need it at all anymore.
// Closing session
err = sess.Close()
...
The following example demonstrates how to connect, ping and disconnect from a PostgreSQL database.
Please note that different databases may have particular ways of connecting to a database server or openning a database file, some databases like SQLite do not have a server concept and they just use files. Please refer to the page of the adapter you're using to see such particularities.
Underlying driver
In case you require methods that are only available from the underlying driver,
you can use the Driver()
method, which returns an interface{}
. For
instance, if you need the
mgo.Session.Ping method, you
can retrieve the underlying *mgo.Session
as an interface{}
, cast it into
the appropriate type, and use Ping()
, as shown below:
drv = sess.Driver().(*mgo.Session) // The driver is cast into the
// the appropriate type.
err = drv.Ping()
You can do the same when working with an SQL adapter by changing the casting:
drv = sess.Driver().(*sql.DB)
rows, err = drv.Query("SELECT name FROM users WHERE age = ?", age)