Skip to content

feat(go): add sql queries documentation #13594

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions docs/platforms/go/common/tracing/instrumentation/sql-module.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
---
title: Instrument Database
sidebar_order: 3000
description: "Learn how to manually instrument your code to use Sentry's SQL module."
---
Sentry provides you the ability to capture, trace and monitor SQL database queries with the `sentrysql` package. The package supports all third-party drivers that adhere to Go's [`database/sql/driver`](https://go.dev/src/database/sql/doc.txt).

<Alert>
Make sure that there's a transaction running when you create the spans. See <PlatformLink to="/tracing/">Tracing</PlatformLink> for more information.
</Alert>

## Automatic instrumentation

The `sentrysql` package gives you the ability to either wrap a driver (recommended for `sql.Open`) or wrap a connector (recommended for `sql.OpenDB`).

### Wrapping a driver

```go
dsn := "postgres://postgres:[email protected]:5432/postgres"
sql.Register("sentrysql-postgres", sentrysql.NewSentrySQL(
&pq.Driver{},
sentrysql.WithDatabaseSystem(sentrysql.PostgreSQL),
sentrysql.WithDatabaseName("postgres"),
sentrysql.WithServerAddress("write.postgres.internal", "5432"),
))

db, err := sql.Open("sentrysql-postgres", dsn)
if err != nil {
panic(fmt.Sprintf("failed to open write postgres db: %s\n", err.Error()))
}
defer func() {
err := db.Close()
if err != nil {
sentry.CaptureException(err)
}
}()
```
This allows you to connect like normal with `sql.Open`.

### Wrapping a connector

For more control (for example, for a read replica), you can wrap a connector:

```go
dsn := "postgres://postgres:[email protected]:5432/postgres"
connector, err := pq.NewConnector(dsn)
if err != nil {
panic(fmt.Sprintf("failed to create a postgres connector: %s\n", err.Error()))
}
wrappedConnector := sentrysql.NewSentrySQLConnector(
connector,
sentrysql.WithDatabaseSystem(sentrysql.PostgreSQL),
sentrysql.WithDatabaseName("postgres"),
sentrysql.WithServerAddress("read.postgres.internal", "5432"),
)

db := sql.OpenDB(wrappedConnector)
defer func() {
err := db.Close()
if err != nil {
sentry.CaptureException(err)
}
}()
```