libsql

README

GORM Libsql Driver

Usage

import (
  "github.com/bryanvaz/gorm-libsql"
  "gorm.io/gorm"
)

// Local File
db, err := gorm.Open(libsql.Open("file:my.db"), &gorm.Config{})

// Remote Turso Database
db, err := gorm.Open(libsql.Open("libsql://[DATABASE].turso.io?authToken=[TOKEN]"), &gorm.Config{})

// Remote Libsql Database
db, err := gorm.Open(libsql.Open("http://<hostname>:<port>"), &gorm.Config{})

// Embedded Replica (db stored in temp dir)
import "database/sql"

conn, err := libsql.NewEmbeddedReplicaConnector("/tmp/local_replica.db", "libsql://[DATABASE].turso.io?authToken=[TOKEN]")
if err != nil {
  panic(err)
}
db, err := gorm.Open(libsql.New(libsql.Config{ Conn: sql.OpenDB(conn) }), &gorm.Config{})
// To manually sync replica
replicated, err := conn.Sync()

Description

This driver properly wraps the CGO version of the libsql client, allowing you to use both local and remote databases as well as embedded replicas. The CGO version is required to use the embedded replica feature.

It is possible to use the pure go libsql client github.com/tursodatabase/libsql-client-go/libsql using the custom libsql connector method. However, as this driver still includes the CGO version of the libsql client, you may still run into issues.

NOTE: This driver cannot be used in parallel with any other libsql or sqlite3 CGO drivers. The symbols will conflict

Development Notes

• Since libsql aims to be a drop-in replacement for sqlite, the goal of this wrapper is to minimize the amount of code that needs to be written to support libsql, beyond the base gorm-sqlite driver.
• In order to minimize the maintenance burden and version churn, only the most basic connection scenario is covered by the built in Open and New methods. For production use, you should initialize a libsql connection outside of the gorm driver, then use this wrapper to provide gorm ergonomics around your connection.

Testing

To run tests locally, run docker compose up to stand up a local libsql database.

Acknowledgements

This driver is largely based on the go-gorm/sqlite driver by jinzhu.

Author

Bryan Vaz - https://github.com/bryanvaz

Documentation

Index

• Constants
• Variables
• func New(config Config) gorm.Dialector
• func Open(dsn string) gorm.Dialector
• type Config
• type Dialector
  • func (dialector Dialector) BindVarTo(writer clause.Writer, stmt *gorm.Statement, v interface{})
  • func (dialector Dialector) ClauseBuilders() map[string]clause.ClauseBuilder
  • func (dialector Dialector) DataTypeOf(field *schema.Field) string
  • func (dialector Dialector) DefaultValueOf(field *schema.Field) clause.Expression
  • func (dialector Dialector) Explain(sql string, vars ...interface{}) string
  • func (dialector Dialector) Initialize(db *gorm.DB) (err error)
  • func (dialector Dialector) Migrator(db *gorm.DB) gorm.Migrator
  • func (dialector Dialector) Name() string
  • func (dialector Dialector) QuoteTo(writer clause.Writer, str string)
  • func (dialectopr Dialector) RollbackTo(tx *gorm.DB, name string) error
  • func (dialectopr Dialector) SavePoint(tx *gorm.DB, name string) error
  • func (dialector Dialector) Translate(err error) error
• type ErrMessage
• type Index
• type Migrator
  • func (m Migrator) AlterColumn(value interface{}, name string) error
  • func (m Migrator) BuildIndexOptions(opts []schema.IndexOption, stmt *gorm.Statement) (results []interface{})
  • func (m Migrator) ColumnTypes(value interface{}) ([]gorm.ColumnType, error)
  • func (m Migrator) CreateConstraint(value interface{}, name string) error
  • func (m Migrator) CreateIndex(value interface{}, name string) error
  • func (m Migrator) CurrentDatabase() (name string)
  • func (m Migrator) DropColumn(value interface{}, name string) error
  • func (m Migrator) DropConstraint(value interface{}, name string) error
  • func (m Migrator) DropIndex(value interface{}, name string) error
  • func (m Migrator) DropTable(values ...interface{}) error
  • func (m Migrator) GetIndexes(value interface{}) ([]gorm.Index, error)
  • func (m Migrator) GetTables() (tableList []string, err error)
  • func (m Migrator) HasColumn(value interface{}, name string) bool
  • func (m Migrator) HasConstraint(value interface{}, name string) bool
  • func (m Migrator) HasIndex(value interface{}, name string) bool
  • func (m Migrator) HasTable(value interface{}) bool
  • func (m Migrator) RenameIndex(value interface{}, oldName, newName string) error
  • func (m *Migrator) RunWithoutForeignKey(fc func() error) error

Constants

const DriverName = "libsql"

DriverName is the default driver name for SQLite.

Variables

var (
	ErrConstraintsNotImplemented = errors.New("constraints not implemented on sqlite, consider using DisableForeignKeyConstraintWhenMigrating, more details https://github.com/go-gorm/gorm/wiki/GORM-V2-Release-Note-Draft#all-new-migrator")
)

Functions

func New

func New(config Config) gorm.Dialector

func Open

func Open(dsn string) gorm.Dialector

Types

type Config

type Config struct {
	DriverName string
	DSN        string
	Conn       gorm.ConnPool
}

type Dialector

type Dialector struct {
	DriverName string
	DSN        string
	Conn       gorm.ConnPool
}

func (Dialector) BindVarTo

func (dialector Dialector) BindVarTo(writer clause.Writer, stmt *gorm.Statement, v interface{})

func (Dialector) ClauseBuilders

func (dialector Dialector) ClauseBuilders() map[string]clause.ClauseBuilder

func (Dialector) DataTypeOf

func (dialector Dialector) DataTypeOf(field *schema.Field) string

func (Dialector) DefaultValueOf

func (dialector Dialector) DefaultValueOf(field *schema.Field) clause.Expression

func (Dialector) Explain

func (dialector Dialector) Explain(sql string, vars ...interface{}) string

func (Dialector) Initialize

func (dialector Dialector) Initialize(db *gorm.DB) (err error)

func (Dialector) Migrator

func (dialector Dialector) Migrator(db *gorm.DB) gorm.Migrator

func (Dialector) Name

func (dialector Dialector) Name() string

func (Dialector) QuoteTo

func (dialector Dialector) QuoteTo(writer clause.Writer, str string)

func (Dialector) RollbackTo

func (dialectopr Dialector) RollbackTo(tx *gorm.DB, name string) error

func (Dialector) SavePoint

func (dialectopr Dialector) SavePoint(tx *gorm.DB, name string) error

func (Dialector) Translate

func (dialector Dialector) Translate(err error) error

Translate it will translate the error to native gorm errors. We are not using go-sqlite3 error type intentionally here because it will need the CGO_ENABLED=1 and cross-C-compiler.

type ErrMessage

type ErrMessage struct {
	Code         int `json:"Code"`
	ExtendedCode int `json:"ExtendedCode"`
	SystemErrno  int `json:"SystemErrno"`
}

type Index

type Index struct {
	Seq     int
	Name    string
	Unique  bool
	Origin  string
	Partial bool
}

type Migrator

type Migrator struct {
	migrator.Migrator
}

func (Migrator) AlterColumn

func (m Migrator) AlterColumn(value interface{}, name string) error

func (Migrator) BuildIndexOptions

func (m Migrator) BuildIndexOptions(opts []schema.IndexOption, stmt *gorm.Statement) (results []interface{})

func (Migrator) ColumnTypes

func (m Migrator) ColumnTypes(value interface{}) ([]gorm.ColumnType, error)

ColumnTypes return columnTypes []gorm.ColumnType and execErr error

func (Migrator) CreateConstraint

func (m Migrator) CreateConstraint(value interface{}, name string) error

func (Migrator) CreateIndex

func (m Migrator) CreateIndex(value interface{}, name string) error

func (Migrator) CurrentDatabase

func (m Migrator) CurrentDatabase() (name string)

func (Migrator) DropColumn

func (m Migrator) DropColumn(value interface{}, name string) error

func (Migrator) DropConstraint

func (m Migrator) DropConstraint(value interface{}, name string) error

func (Migrator) DropIndex

func (m Migrator) DropIndex(value interface{}, name string) error

func (Migrator) DropTable

func (m Migrator) DropTable(values ...interface{}) error

func (Migrator) GetIndexes

func (m Migrator) GetIndexes(value interface{}) ([]gorm.Index, error)

GetIndexes return Indexes []gorm.Index and execErr error, See the doc

func (Migrator) GetTables

func (m Migrator) GetTables() (tableList []string, err error)

func (Migrator) HasColumn

func (m Migrator) HasColumn(value interface{}, name string) bool

func (Migrator) HasConstraint

func (m Migrator) HasConstraint(value interface{}, name string) bool

func (Migrator) HasIndex

func (m Migrator) HasIndex(value interface{}, name string) bool

func (Migrator) HasTable

func (m Migrator) HasTable(value interface{}) bool

func (Migrator) RenameIndex

func (m Migrator) RenameIndex(value interface{}, oldName, newName string) error

func (*Migrator) RunWithoutForeignKey

func (m *Migrator) RunWithoutForeignKey(fc func() error) error