remoteha

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 19 Imported by: 0

README

go-remote-ha

Overview

go-remote-ha is a Go database/sql driver designed for remote access to SQLite HA databases over gRPC. This driver enables seamless interaction with high-availability SQLite databases using Go's standard library interface.

Features

  • Remote Access: Connect to SQLite HA databases over gRPC (http, https, grpc, grpcs).
  • Connection Multiplexing: Shares a single underlying gRPC connection across pooled database/sql streams.
  • Easy Integration: Works directly with Go's standard database/sql package.

Installation

To install go-remote-ha, use the following command:

go get -u github.com/litesql/go-remote-ha

Usage

Here’s an example of how to use go-remote-ha:

package main

import (
	"database/sql"

	_ "github.com/litesql/go-remote-ha"
)

func main() {
	db, err := sql.Open("remote-ha", "https://:your-secret-token@db.example.com:8443/my-replication-id")
	if err != nil {
		panic(err)
	}
	defer db.Close()

	// Your database operations here
}

DSN Format

<scheme>://[:<token>@]<host>:<port>[/<replicationID>][?<options>]
Schemes
  • https:// or grpcs://: Enables TLS transport security.
  • http:// or grpc://: Uses insecure plaintext transport (suitable for local development or trusted networks).
Authentication

Pass the authentication token in any of the following ways:

  • Password in userinfo: https://:my-token@host:8443/mydb or https://user:my-token@host:8443/mydb
  • Username in userinfo: https://my-token@host:8443/mydb
  • Query parameter: https://host:8443/mydb?token=my-token (or grpcToken=my-token)
Query Parameters
Parameter Description Default
replicationID / replID Target database replication ID (if not provided in the URL path) ""
token / grpcToken Authorization token sent in gRPC metadata ""
insecure / grpcInsecure Disable TLS (true/false) Depends on scheme
insecureSkipVerify Skip TLS certificate verification (true/false) false
keepalive Stream keepalive ping interval (0s disables application pings) 25s
Custom gRPC Dial Options

You can pass custom grpc.DialOptions via NewConnector and sql.OpenDB:

connector, err := remoteha.NewConnector("https://db.example.com:8443/mydb", customDialOpts...)
if err != nil {
	panic(err)
}
db := sql.OpenDB(connector)
defer db.Close()

Embedded replicas

For embedded replicas, use go-sqlite-ha or go-sqlite3-ha drivers.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Connector

type Connector struct {
	Name string
	// contains filtered or unexported fields
}

func NewConnector added in v0.1.0

func NewConnector(name string, dialOpts ...grpc.DialOption) (*Connector, error)

NewConnector validates the DSN and returns a new Connector with optional custom gRPC DialOptions.

func (*Connector) Close added in v0.1.0

func (c *Connector) Close() error

func (*Connector) Connect

func (c *Connector) Connect(ctx context.Context) (driver.Conn, error)

func (*Connector) Driver

func (c *Connector) Driver() driver.Driver

type Driver

type Driver struct{}

func (*Driver) Open

func (d *Driver) Open(name string) (driver.Conn, error)

func (*Driver) OpenConnector

func (d *Driver) OpenConnector(name string) (driver.Connector, error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL