Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.turso.tech/llms.txt

Use this file to discover all available pages before exploring further.

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
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)
	}
}

​
Legacy: go-libsql (Embedded Replicas)

Usage of embedded replicas is strongly discouraged. With embedded replicas, reads are local but writes are sent to the remote database — this means writes fail when offline, have higher latency, and don’t support concurrent writes. Use tursogo with NewTursoSyncDb instead: all reads and writes are local, and you explicitly sync with Push() / Pull().
See the reference for legacy documentation on embedded replicas if you have an existing go-libsql codebase.