rivermysql

package module
v0.0.0-...-003bd8e Latest Latest
Warning

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

Go to latest
Published: Oct 17, 2026 License: MPL-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package rivermysql provides a River driver implementation for MySQL.

This driver targets MySQL 8.0+ and requires `go-sql-driver/mysql` or a compatible driver registered with `database/sql`. DSNs used with River should include `parseTime=true`, `loc=UTC`, and `multiStatements=true`. `parseTime` and `loc` ensure `DATETIME` columns are scanned as UTC time.Time values, while `multiStatements` is needed to run River's migrations.

MySQL does not support LISTEN/NOTIFY, so this driver uses a `river_notification` outbox table for notifications. It also does not support `RETURNING` clauses, so most write operations are carried out as two-step operations (write + read).

This driver is currently in early development. It's exercised in the test suite, but has minimal real world use as of yet.

Example (Mysql)

Example_mysql demonstrates use of River's MySQL driver.

package main

import (
	"cmp"
	"context"
	"database/sql"
	"fmt"
	"log/slog"
	"os"
	"sort"

	_ "github.com/go-sql-driver/mysql"

	"github.com/riverqueue/river"
	"github.com/riverqueue/river/riverdriver/rivermysql"
	"github.com/riverqueue/river/rivermigrate"
	"github.com/riverqueue/river/rivershared/riversharedtest"
	"github.com/riverqueue/river/rivershared/util/slogutil"
	"github.com/riverqueue/river/rivershared/util/testutil"
)

type MySQLSortArgs struct {
	// Strings is a slice of strings to sort.
	Strings []string `json:"strings"`
}

func (MySQLSortArgs) Kind() string { return "sort" }

type MySQLSortWorker struct {
	river.WorkerDefaults[MySQLSortArgs]
}

func (w *MySQLSortWorker) Work(ctx context.Context, job *river.Job[MySQLSortArgs]) error {
	sort.Strings(job.Args.Strings)
	fmt.Printf("Sorted strings: %+v\n", job.Args.Strings)
	return nil
}

// Example_mysql demonstrates use of River's MySQL driver.
func main() {
	// MySQL tests are opt-in because they require a running server. When
	// disabled, print the expected output so the example test always passes.
	val := os.Getenv("RIVER_MYSQL_TESTS_ENABLED")
	if val != "1" && val != "true" {
		fmt.Println("Sorted strings: [bear tiger whale]")
		return
	}

	ctx := context.Background()

	dsn := cmp.Or(
		os.Getenv("TEST_MYSQL_URL"),
		"root@tcp(localhost:3306)/?parseTime=true&multiStatements=true&loc=UTC&time_zone=%27%2B00%3A00%27",
	)

	dbPool, err := sql.Open("mysql", dsn)
	if err != nil {
		panic(err)
	}
	defer dbPool.Close()

	// Create a temporary database for the example.
	const exampleDB = "river_example_mysql"
	if _, err := dbPool.ExecContext(ctx, "CREATE DATABASE IF NOT EXISTS "+exampleDB); err != nil {
		panic(err)
	}
	defer func() {
		_, _ = dbPool.ExecContext(ctx, "DROP DATABASE IF EXISTS "+exampleDB)
	}()

	// Run River's migrations to prepare the schema.
	migrator, err := rivermigrate.New(rivermysql.New(dbPool), &rivermigrate.Config{
		Logger: slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelWarn, ReplaceAttr: slogutil.NoLevelTime})),
		Schema: exampleDB,
	})
	if err != nil {
		panic(err)
	}
	if _, err := migrator.Migrate(ctx, rivermigrate.DirectionUp, nil); err != nil {
		panic(err)
	}

	workers := river.NewWorkers()
	river.AddWorker(workers, &MySQLSortWorker{})

	riverClient, err := river.NewClient(rivermysql.New(dbPool), &river.Config{
		Logger: slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelWarn, ReplaceAttr: slogutil.NoLevelTime})),
		Queues: map[string]river.QueueConfig{
			river.QueueDefault: {MaxWorkers: 100},
		},
		Schema:   exampleDB,
		TestOnly: true, // suitable only for use in tests; remove for live environments
		Workers:  workers,
	})
	if err != nil {
		panic(err)
	}

	// Out of example scope, but used to wait until a job is worked.
	subscribeChan, subscribeCancel := riverClient.Subscribe(river.EventKindJobCompleted)
	defer subscribeCancel()

	if err := riverClient.Start(ctx); err != nil {
		panic(err)
	}

	_, err = riverClient.Insert(ctx, MySQLSortArgs{
		Strings: []string{
			"whale", "tiger", "bear",
		},
	}, nil)
	if err != nil {
		panic(err)
	}

	// Wait for jobs to complete. Only needed for purposes of the example test.
	riversharedtest.WaitOrTimeoutN(testutil.PanicTB(), subscribeChan, 1)

	if err := riverClient.Stop(ctx); err != nil {
		panic(err)
	}

}
Output:
Sorted strings: [bear tiger whale]

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Driver

type Driver struct {
	// contains filtered or unexported fields
}

Driver is an implementation of riverdriver.Driver for MySQL.

func New

func New(dbPool *sql.DB) *Driver

New returns a new MySQL driver for use with River.

It takes an sql.DB to use with River. The DSN should include `parseTime=true&loc=UTC&multiStatements=true`; see the package documentation for details. The pool must not be closed while associated River objects are running.

func (*Driver) ArgPlaceholder

func (d *Driver) ArgPlaceholder() string

func (*Driver) DatabaseName

func (d *Driver) DatabaseName() string

func (*Driver) GetExecutor

func (d *Driver) GetExecutor() riverdriver.Executor

func (*Driver) GetListener

func (d *Driver) GetListener(params *riverdriver.GetListenenerParams) riverdriver.Listener

func (*Driver) GetMigrationDefaultLines

func (d *Driver) GetMigrationDefaultLines() []string

func (*Driver) GetMigrationFS

func (d *Driver) GetMigrationFS(line string) fs.FS

func (*Driver) GetMigrationLines

func (d *Driver) GetMigrationLines() []string

func (*Driver) GetMigrationTruncateTables

func (d *Driver) GetMigrationTruncateTables(line string, version int) []string

func (*Driver) PoolIsSet

func (d *Driver) PoolIsSet() bool

func (*Driver) PoolSet

func (d *Driver) PoolSet(dbPool any) error

func (*Driver) SQLFragmentColumnContainsAll

func (d *Driver) SQLFragmentColumnContainsAll(column, namedArg string, values []string) (string, any, error)

func (*Driver) SQLFragmentColumnContainsAny

func (d *Driver) SQLFragmentColumnContainsAny(column, namedArg string, values []string) (string, any, error)

func (*Driver) SQLFragmentColumnContainsJSON

func (d *Driver) SQLFragmentColumnContainsJSON(column, namedArg, fragment string) (string, map[string]any, error)

func (*Driver) SQLFragmentColumnIn

func (d *Driver) SQLFragmentColumnIn(column string, values any) (string, any, error)

func (*Driver) SafeIdentifier

func (d *Driver) SafeIdentifier(ident string) string

func (*Driver) SupportsListenNotify

func (d *Driver) SupportsListenNotify() bool

func (*Driver) SupportsListener

func (d *Driver) SupportsListener() bool

func (*Driver) TimePrecision

func (d *Driver) TimePrecision() time.Duration

func (*Driver) UnwrapExecutor

func (d *Driver) UnwrapExecutor(tx *sql.Tx) riverdriver.ExecutorTx

func (*Driver) UnwrapTx

func (d *Driver) UnwrapTx(execTx riverdriver.ExecutorTx) *sql.Tx

type Executor

type Executor struct {
	// contains filtered or unexported fields
}

func (*Executor) Begin

func (*Executor) ColumnExists

func (e *Executor) ColumnExists(ctx context.Context, params *riverdriver.ColumnExistsParams) (bool, error)

func (*Executor) Exec

func (e *Executor) Exec(ctx context.Context, sql string, args ...any) error

func (*Executor) IndexDropIfExists

func (e *Executor) IndexDropIfExists(ctx context.Context, params *riverdriver.IndexDropIfExistsParams) error

func (*Executor) IndexExists

func (e *Executor) IndexExists(ctx context.Context, params *riverdriver.IndexExistsParams) (bool, error)

func (*Executor) IndexReindex

func (e *Executor) IndexReindex(ctx context.Context, params *riverdriver.IndexReindexParams) error

func (*Executor) IndexReindexArtifacts

func (e *Executor) IndexReindexArtifacts(ctx context.Context, params *riverdriver.IndexReindexArtifactsParams) ([]string, error)

func (*Executor) IndexesExist

func (e *Executor) IndexesExist(ctx context.Context, params *riverdriver.IndexesExistParams) (map[string]bool, error)

func (*Executor) InitDriver

func (e *Executor) InitDriver(ctx context.Context) error

func (*Executor) JobCancel

func (e *Executor) JobCancel(ctx context.Context, params *riverdriver.JobCancelParams) (*rivertype.JobRow, error)

func (*Executor) JobCountByAllStates

func (e *Executor) JobCountByAllStates(ctx context.Context, params *riverdriver.JobCountByAllStatesParams) (map[rivertype.JobState]int, error)

func (*Executor) JobCountByState

func (e *Executor) JobCountByState(ctx context.Context, params *riverdriver.JobCountByStateParams) (int, error)

func (*Executor) JobDelete

func (e *Executor) JobDelete(ctx context.Context, params *riverdriver.JobDeleteParams) (*rivertype.JobRow, error)

func (*Executor) JobDeleteBefore

func (e *Executor) JobDeleteBefore(ctx context.Context, params *riverdriver.JobDeleteBeforeParams) (int, error)

func (*Executor) JobDeleteMany

func (e *Executor) JobDeleteMany(ctx context.Context, params *riverdriver.JobDeleteManyParams) ([]*rivertype.JobRow, error)

func (*Executor) JobGetAvailable

func (*Executor) JobGetByID

func (e *Executor) JobGetByID(ctx context.Context, params *riverdriver.JobGetByIDParams) (*rivertype.JobRow, error)

func (*Executor) JobGetByIDMany

func (e *Executor) JobGetByIDMany(ctx context.Context, params *riverdriver.JobGetByIDManyParams) ([]*rivertype.JobRow, error)

func (*Executor) JobGetByKindMany

func (e *Executor) JobGetByKindMany(ctx context.Context, params *riverdriver.JobGetByKindManyParams) ([]*rivertype.JobRow, error)

func (*Executor) JobGetCancelRequested

func (e *Executor) JobGetCancelRequested(ctx context.Context, params *riverdriver.JobGetCancelRequestedParams) ([]int64, error)

func (*Executor) JobGetStuck

func (e *Executor) JobGetStuck(ctx context.Context, params *riverdriver.JobGetStuckParams) ([]*rivertype.JobRow, error)

func (*Executor) JobInsertFastMany

func (*Executor) JobInsertFastManyNoReturning

func (e *Executor) JobInsertFastManyNoReturning(ctx context.Context, params *riverdriver.JobInsertFastManyParams) (int, error)

func (*Executor) JobInsertFull

func (e *Executor) JobInsertFull(ctx context.Context, params *riverdriver.JobInsertFullParams) (*rivertype.JobRow, error)

func (*Executor) JobInsertFullMany

func (e *Executor) JobInsertFullMany(ctx context.Context, params *riverdriver.JobInsertFullManyParams) ([]*rivertype.JobRow, error)

func (*Executor) JobKindList

func (e *Executor) JobKindList(ctx context.Context, params *riverdriver.JobKindListParams) ([]string, error)

func (*Executor) JobList

func (e *Executor) JobList(ctx context.Context, params *riverdriver.JobListParams) ([]*rivertype.JobRow, error)

func (*Executor) JobRescueMany

func (e *Executor) JobRescueMany(ctx context.Context, params *riverdriver.JobRescueManyParams) (*struct{}, error)

func (*Executor) JobRetry

func (e *Executor) JobRetry(ctx context.Context, params *riverdriver.JobRetryParams) (*rivertype.JobRow, error)

func (*Executor) JobSchedule

func (*Executor) JobSetStateIfRunningMany

func (e *Executor) JobSetStateIfRunningMany(ctx context.Context, params *riverdriver.JobSetStateIfRunningManyParams) ([]*rivertype.JobRow, error)

func (*Executor) JobUpdate

func (e *Executor) JobUpdate(ctx context.Context, params *riverdriver.JobUpdateParams) (*rivertype.JobRow, error)

func (*Executor) JobUpdateFull

func (e *Executor) JobUpdateFull(ctx context.Context, params *riverdriver.JobUpdateFullParams) (*rivertype.JobRow, error)

func (*Executor) LeaderAttemptElect

func (e *Executor) LeaderAttemptElect(ctx context.Context, params *riverdriver.LeaderElectParams) (*riverdriver.Leader, error)

func (*Executor) LeaderAttemptReelect

func (e *Executor) LeaderAttemptReelect(ctx context.Context, params *riverdriver.LeaderReelectParams) (*riverdriver.Leader, error)

func (*Executor) LeaderDeleteExpired

func (e *Executor) LeaderDeleteExpired(ctx context.Context, params *riverdriver.LeaderDeleteExpiredParams) (int, error)

func (*Executor) LeaderGetElectedLeader

func (e *Executor) LeaderGetElectedLeader(ctx context.Context, params *riverdriver.LeaderGetElectedLeaderParams) (*riverdriver.Leader, error)

func (*Executor) LeaderInsert

func (e *Executor) LeaderInsert(ctx context.Context, params *riverdriver.LeaderInsertParams) (*riverdriver.Leader, error)

func (*Executor) LeaderResign

func (e *Executor) LeaderResign(ctx context.Context, params *riverdriver.LeaderResignParams) (bool, error)

func (*Executor) MigrationDeleteAssumingMainMany

func (e *Executor) MigrationDeleteAssumingMainMany(ctx context.Context, params *riverdriver.MigrationDeleteAssumingMainManyParams) ([]*riverdriver.Migration, error)

func (*Executor) MigrationDeleteByLineAndVersionMany

func (e *Executor) MigrationDeleteByLineAndVersionMany(ctx context.Context, params *riverdriver.MigrationDeleteByLineAndVersionManyParams) ([]*riverdriver.Migration, error)

func (*Executor) MigrationGetAllAssumingMain

func (e *Executor) MigrationGetAllAssumingMain(ctx context.Context, params *riverdriver.MigrationGetAllAssumingMainParams) ([]*riverdriver.Migration, error)

func (*Executor) MigrationGetByLine

func (e *Executor) MigrationGetByLine(ctx context.Context, params *riverdriver.MigrationGetByLineParams) ([]*riverdriver.Migration, error)

func (*Executor) MigrationInsertMany

func (e *Executor) MigrationInsertMany(ctx context.Context, params *riverdriver.MigrationInsertManyParams) ([]*riverdriver.Migration, error)

func (*Executor) MigrationInsertManyAssumingMain

func (e *Executor) MigrationInsertManyAssumingMain(ctx context.Context, params *riverdriver.MigrationInsertManyAssumingMainParams) ([]*riverdriver.Migration, error)

func (*Executor) NotificationDeleteBefore

func (e *Executor) NotificationDeleteBefore(ctx context.Context, params *riverdriver.NotificationDeleteBeforeParams) (int, error)

func (*Executor) NotifyMany

func (e *Executor) NotifyMany(ctx context.Context, params *riverdriver.NotifyManyParams) error

func (*Executor) PGAdvisoryXactLock

func (e *Executor) PGAdvisoryXactLock(ctx context.Context, key int64) (*struct{}, error)

func (*Executor) Ping

func (e *Executor) Ping(ctx context.Context) error

func (*Executor) QueryRow

func (e *Executor) QueryRow(ctx context.Context, sql string, args ...any) riverdriver.Row

func (*Executor) QueueCreateOrSetUpdatedAt

func (e *Executor) QueueCreateOrSetUpdatedAt(ctx context.Context, params *riverdriver.QueueCreateOrSetUpdatedAtParams) (*rivertype.Queue, error)

func (*Executor) QueueDeleteExpired

func (e *Executor) QueueDeleteExpired(ctx context.Context, params *riverdriver.QueueDeleteExpiredParams) ([]string, error)

func (*Executor) QueueGet

func (e *Executor) QueueGet(ctx context.Context, params *riverdriver.QueueGetParams) (*rivertype.Queue, error)

func (*Executor) QueueList

func (e *Executor) QueueList(ctx context.Context, params *riverdriver.QueueListParams) ([]*rivertype.Queue, error)

func (*Executor) QueueNameList

func (e *Executor) QueueNameList(ctx context.Context, params *riverdriver.QueueNameListParams) ([]string, error)

func (*Executor) QueuePause

func (e *Executor) QueuePause(ctx context.Context, params *riverdriver.QueuePauseParams) error

func (*Executor) QueueResume

func (e *Executor) QueueResume(ctx context.Context, params *riverdriver.QueueResumeParams) error

func (*Executor) QueueUpdate

func (e *Executor) QueueUpdate(ctx context.Context, params *riverdriver.QueueUpdateParams) (*rivertype.Queue, error)

func (*Executor) SchemaCreate

func (e *Executor) SchemaCreate(ctx context.Context, params *riverdriver.SchemaCreateParams) error

func (*Executor) SchemaDrop

func (e *Executor) SchemaDrop(ctx context.Context, params *riverdriver.SchemaDropParams) error

func (*Executor) SchemaGetExpired

func (e *Executor) SchemaGetExpired(ctx context.Context, params *riverdriver.SchemaGetExpiredParams) ([]string, error)

func (*Executor) TableExists

func (e *Executor) TableExists(ctx context.Context, params *riverdriver.TableExistsParams) (bool, error)

func (*Executor) TableTruncate

func (e *Executor) TableTruncate(ctx context.Context, params *riverdriver.TableTruncateParams) error

type ExecutorSubTx

type ExecutorSubTx struct {
	Executor
	// contains filtered or unexported fields
}

func (*ExecutorSubTx) Begin

func (*ExecutorSubTx) Commit

func (t *ExecutorSubTx) Commit(ctx context.Context) error

func (*ExecutorSubTx) Rollback

func (t *ExecutorSubTx) Rollback(ctx context.Context) error

type ExecutorTx

type ExecutorTx struct {
	Executor
	// contains filtered or unexported fields
}

func (*ExecutorTx) Begin

func (*ExecutorTx) Commit

func (t *ExecutorTx) Commit(ctx context.Context) error

func (*ExecutorTx) Rollback

func (t *ExecutorTx) Rollback(ctx context.Context) error

type Listener

type Listener struct {
	// contains filtered or unexported fields
}

Listener receives MySQL notifications from the river_notification outbox table. MySQL doesn't have a native LISTEN/NOTIFY equivalent, so NotifyMany appends rows to river_notification and this listener polls for rows with IDs greater than its remembered lastID. Polls use a locking read because InnoDB may commit auto-increment IDs out of order across concurrent transactions; a normal consistent read could otherwise skip a lower uncommitted notification.

func (*Listener) Close

func (l *Listener) Close(context.Context) error

func (*Listener) Connect

func (l *Listener) Connect(ctx context.Context) error

func (*Listener) Listen

func (l *Listener) Listen(ctx context.Context, topic string) error

func (*Listener) Ping

func (l *Listener) Ping(ctx context.Context) error

func (*Listener) Schema

func (l *Listener) Schema() string

func (*Listener) SetAfterConnectExec

func (l *Listener) SetAfterConnectExec(sql string)

func (*Listener) Unlisten

func (l *Listener) Unlisten(_ context.Context, topic string) error

func (*Listener) WaitForNotification

func (l *Listener) WaitForNotification(ctx context.Context) (*riverdriver.Notification, error)

Directories

Path Synopsis
internal

Jump to

Keyboard shortcuts

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