The libSQL package is designed to work with database/sql to provide the usual methods you’d expect when working with databases in Go.

The go-libsql package uses CGO. You can use github.com/tursodatabase/libsql-client-go/libsql instead, but it doesn’t support embedded replicas.

In this Go quickstart we will learn how to:

  • Retrieve database credentials
  • Install Go libSQL
  • Connect to a local or remote Turso database
  • Execute a query using SQL
  • Sync changes to local database (optional)
1

Retrieve database credentials

You will need an existing database to continue. If you don’t have one, create one.

Get the database URL:

turso db show --url <database-name>

Get the database authentication token:

turso db tokens create <database-name>

Assign credentials to the environment variables inside .env.

TURSO_DATABASE_URL=
TURSO_AUTH_TOKEN=
You will want to store these as environment variables.
2

Install

First begin by adding libSQL to your project:

3

Connect

Now connect to your local or remote database using the libSQL connector:

4

Execute

You can execute a SQL query against your existing database. Create a function to query your database that accepts the pointer to sql.DB as an argument:

type User struct {
	ID   int
	Name string
}

func queryUsers(db *sql.DB)  {
  rows, err := db.Query("SELECT * FROM users")
  if err != nil {
    fmt.Fprintf(os.Stderr, "failed to execute query: %v\n", err)
    os.Exit(1)
  }
  defer rows.Close()

  var users []User

  for rows.Next() {
    var user User

    if err := rows.Scan(&user.ID, &user.Name); err != nil {
      fmt.Println("Error scanning row:", err)
      return
    }

    users = append(users, user)
    fmt.Println(user.ID, user.Name)
  }

  if err := rows.Err(); err != nil {
    fmt.Println("Error during rows iteration:", err)
  }
}

Now inside func main() call queryUsers and pass in the pointer to sql.DB:

queryUsers(db)
5

Sync (Embedded Replicas only)

When using embedded replicas you should call Sync() on the connector to sync your local database with the primary database.

if err := connector.Sync(); err != nil {
  fmt.Println("Error syncing database:", err)
}

The connector can automatically sync your database at a regular interval when using the WithSyncInterval option:

syncInterval := time.Minute

connector, err := libsql.NewEmbeddedReplicaConnector(dbPath, primaryUrl,
    libsql.WithAuthToken(authToken),
    libsql.WithSyncInterval(syncInterval),
)