LibSQL Go Bindings

Depending on how you initialized your connector, you may need to manage synchronization manually:

1. Automatic Sync: If you used libsql.NewEmbeddedReplicaConnectorWithAutoSync, the connector handles periodic updates from the primary instance automatically.
2. Manual Sync: If you used libsql.NewEmbeddedReplicaConnector, you must trigger updates manually by calling the Sync method on the connector instance.

// For connectors created with NewEmbeddedReplicaConnector
err := connector.Sync()
if err != nil {
    // handle error
}

To use go-libsql with the standard database/sql package, you must create a libsql.Connector using one of the provided factory functions and then pass it to sql.OpenDB.

Available factory functions:

• libsql.NewEmbeddedReplicaConnector(dbPath, primaryUrl, authToken): Creates a connector for a local replica that requires manual synchronization.
• libsql.NewEmbeddedReplicaConnectorWithAutoSync(dbPath, primaryUrl, authToken): Creates a connector that automatically fetches updates from the primary database periodically.

dbPath := "// Path to db file on local disk"
primaryUrl := "// URL to primary database instance"
authToken := "// Your auth token"

// Create the connector
connector := libsql.NewEmbeddedReplicaConnector(dbPath, primaryUrl, authToken)

// Obtain a *sql.DB object
db := sql.OpenDB(connector)
defer db.Close()

// Use db as any other database/sql object

The libsql package registers itself as a driver for Go's standard database/sql package. You can connect to local files, remote URLs, or in-memory databases using a connection string.

Supported URL schemes:

• libsql:// or https:// or http://: Remote connections.
• file:: Local file connections.
• :memory:: In-memory database.

To use authentication or encryption with remote URLs, pass them as query parameters (e.g., authToken and remoteEncryptionKey).

import (
	"database/sql"
	_ "github.com/tursodatabase/tursodatabase/go-libsql"
)

func main() {
	// Example: Connecting to a remote libSQL instance
	db, err := sql.Open("libsql", "libsql://your-database-url.com?authToken=your-token")
	if err != nil {
		panic(err)
	}
	defer db.Close()
}

Install the package using go get. Note that go-libsql uses CGO to interface with native LibSQL libraries. You must ensure CGO_ENABLED=1 is set when building your binaries.

Supported platforms for precompiled native libraries:

• linux amd64
• linux arm64
• darwin amd64
• darwin arm64

go get github.com/tursodatabase/go-libsql
# Ensure CGO is enabled during build
CGO_ENABLED=1 go build .

Use NewEmbeddedReplicaConnector to create a local database file that stays in sync with a primary remote database. This is ideal for edge computing or local-first applications where you want low-latency reads from a local file.

Parameters:

• dbPath: Path to the local database file.
• primaryUrl: The URL of the primary remote database.
• opts: Functional options for configuration.

import (
	"github.com/tursodatabase/tursodatabase/go-libsql"
)

// Create an embedded replica that syncs with a primary
connector, err := libsql.NewEmbeddedReplicaConnector(
	"./local.db",
	"https://your-primary-url.com",
	libsql.WithAuthToken("your-token"),
	libsql.WithSyncInterval(1 * time.Minute),
)
if err != nil {
	panic(err)
}

The Connector type provides a Sync() method (noting it is deprecated in favor of the tursogo package) that allows you to manually trigger a synchronization of the local database with the primary instance. It returns a Replicated struct containing the current state of the sync.

// Replicated contains sync metadata
type Replicated struct {
	FrameNo      int
	FramesSynced int
}

// Trigger a manual sync
rep, err := connector.Sync()
if err != nil {
	// handle error
}
fmt.Printf("Synced up to frame %d\n", rep.FrameNo)

When using NewEmbeddedReplicaConnector or NewSyncedDatabaseConnector, you can pass several Option functions to configure the connection:

• WithAuthToken(token string): Sets the authentication token for remote connections. Cannot be empty.
• WithReadYourWrites(enabled bool): Enables/disables the 'read your writes' consistency model.
• WithEncryption(key string): Sets the local encryption key for the database file. Cannot be empty.
• WithRemoteEncryption(key string): Sets the key used for remote encryption. Cannot be empty.
• WithSyncInterval(interval time.Duration): Sets how often the local replica automatically syncs with the primary.

Use NewSyncedDatabaseConnector to create a connector that manages a local database file and synchronizes it with a primary remote instance. This is similar to the embedded replica but is designed for specific synchronization workflows.

connector, err := libsql.NewSyncedDatabaseConnector(
	"./local.db",
	"https://your-primary-url.com",
	libsql.WithAuthToken("your-token"),
)