Turso Quickstart (Go)

Get started with Turso and Go in a few simple steps.

In this Go quickstart we will learn how to:

• Install the Turso package
• Connect to a local or remote database
• Execute a query using SQL
• Sync changes to the cloud

Recommended: tursogo (Local + Cloud Sync)

tursogo is the recommended package for running a local database, including synchronizing it to and from Turso Cloud. It is built on the Turso Database engine — a ground-up rewrite of SQLite with concurrent writes (MVCC) and async I/O. It implements the standard database/sql driver interface, so it works as a drop-in replacement for any Go SQLite driver. It ships prebuilt native libraries and uses purego for FFI — no CGO required.

1. Install

   go get turso.tech/database/tursogo
   
2. Connect

   package main
   
   import (
   	"database/sql"
   	"fmt"
   
   	_ "turso.tech/database/tursogo"
   )
   
   func main() {
   	db, _ := sql.Open("turso", "app.db")
   	defer db.Close()
   
   	db.Exec(`CREATE TABLE IF NOT EXISTS users (
   		id INTEGER PRIMARY KEY AUTOINCREMENT,
   		name TEXT NOT NULL
   	)`)
   
   	db.Exec("INSERT INTO users (name) VALUES (?)", "Alice")
   
   	rows, _ := db.Query("SELECT * FROM users")
   	defer rows.Close()
   	for rows.Next() {
   		var id int
   		var name string
   		rows.Scan(&id, &name)
   		fmt.Printf("User: %d %s\n", id, name)
   	}
   }
   
3. Sync (push and pull)

   If you need to sync your local database with Turso Cloud, use the sync driver:

   package main
   
   import (
   	"context"
   	"os"
   
   	turso "turso.tech/database/tursogo"
   )
   
   func main() {
   	ctx := context.Background()
   
   	syncDb, _ := turso.NewTursoSyncDb(ctx, turso.TursoSyncDbConfig{
   		Path:      "app.db",
   		RemoteUrl: os.Getenv("TURSO_DATABASE_URL"),
   		AuthToken: os.Getenv("TURSO_AUTH_TOKEN"),
   	})
   
   	db, _ := syncDb.Connect(ctx)
   	defer db.Close()
   
   	db.ExecContext(ctx, "INSERT INTO users (name) VALUES (?)", "Bob")
   
   	// Push local writes to Turso Cloud
   	syncDb.Push(ctx)
   
   	// Pull remote changes to local database
   	syncDb.Pull(ctx)
   }
   

   All reads and writes happen against the local database file — fast, offline-capable. Push() sends your changes to the cloud. Pull() brings remote changes down. See the reference for checkpoint, stats, and encryption. See Turso Sync for details on conflict resolution and more.

   You can test sync locally without a Turso Cloud account by starting a local sync server:

   tursodb :memory: --sync-server 127.0.0.1:8080
   

   Then set RemoteUrl to http://127.0.0.1:8080 (no AuthToken needed). See Turso Database quickstart for how to install tursodb.

Remote Access (Over-the-Wire)

If your application needs to query a Turso Cloud database directly over the network (e.g., from a web server or serverless function), use the libsql-client-go package. It connects to your database via the libSQL wire protocol — no local file needed, pure Go.

For most applications, we recommend running a local database with sync (NewTursoSyncDb) instead — it gives you faster reads, offline support, and lower latency. Remote access is useful when you cannot store a local database file (e.g., stateless serverless environments).

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

   go get github.com/tursodatabase/libsql-client-go/libsql
   
3. Connect and query

   package main
   
   import (
   	"database/sql"
   	"fmt"
   	"os"
   
   	_ "github.com/tursodatabase/libsql-client-go/libsql"
   )
   
   func main() {
   	url := os.Getenv("TURSO_DATABASE_URL") + "?authToken=" + os.Getenv("TURSO_AUTH_TOKEN")
   
   	db, _ := sql.Open("libsql", url)
   	defer db.Close()
   
   	rows, _ := db.Query("SELECT * FROM users")
   	defer rows.Close()
   	for rows.Next() {
   		var id int
   		var name string
   		rows.Scan(&id, &name)
   		fmt.Printf("User: %d %s\n", id, name)
   	}
   }
   

Embedded Replicas (go-libsql)

Embedded Replicas give your Go app a local read copy of a Turso Cloud database. Reads are served locally; writes go to the cloud primary and are reflected back to the replica. Embedded Replicas are fully supported in production.

For new projects that need sync, we recommend tursogo with NewTursoSyncDb: both reads and writes are local, you sync explicitly with Push() / Pull(), and the wire format is logical change-data-capture rather than page frames (benchmark).

See the reference for full documentation on Embedded Replicas with go-libsql.