pgxshard

README

go-pgxshard - PostgreSQL sharding for Golang

go-pgxshard is a Golang module that provides a simple and efficient way to manage and interact with multiple PostgreSQL database shards using the pgxpool library. It allows developers to distribute data across multiple shards and provides utility methods for shard management, connectivity, and querying.

Features

• Shard Management: Easily manage multiple PostgreSQL shards.
• Custom Shard Indexing: Define custom shard indexing logic based on your application's requirements.
• Connection Pooling: Leverages pgxpool for efficient connection pooling.

Installation

To install the module, use:

go get github.com/ruizu/go-pgxshard

Usage

Creating a ShardManager

package main

import (
	"context"
	"log"
	"github.com/ruizu/go-pgxshard"
)

func main() {
	ctx := context.Background()
	connectionStrings := []string{
		"postgres://user:password@localhost:5432/shard1",
		"postgres://user:password@localhost:5432/shard2",
	}

	shardManager, err := pgxshard.New(ctx, connectionStrings)
	if err != nil {
		log.Fatalf("Failed to create ShardManager: %v", err)
	}
	defer shardManager.Close(ctx)

	// Use shardManager to interact with shards
}

Setting a Custom Shard Index Function

shardManager.SetShardIndexFunc(ctx, func(key any, count int) (int, error) {
	// Custom logic to determine shard index
})

Accessing a Shard

shard, err := shardManager.Shard(ctx, "some-key")
if err != nil {
	log.Fatalf("Failed to get shard: %v", err)
}

// Use the shard (pgxpool.Pool) for database operations

Checking Connectivity

if err := shardManager.Ping(ctx); err != nil {
	log.Fatalf("Shard connectivity issue: %v", err)
}

License

This project is licensed under the MIT License. See the LICENSE.md file for details.

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.

Acknowledgments

• pgx - PostgreSQL driver and toolkit for Go.

Documentation

Index

• type ShardManager
  • func New(ctx context.Context, connectionStrings []string) (*ShardManager, error)
  • func (s *ShardManager) Close(ctx context.Context) error
  • func (s *ShardManager) Ping(ctx context.Context) error
  • func (s *ShardManager) SetShardIndexFunc(ctx context.Context, f func(key any, count int) (int, error))
  • func (s *ShardManager) Shard(ctx context.Context, key any) (*pgxpool.Pool, error)
  • func (s *ShardManager) Shards(ctx context.Context) ([]*pgxpool.Pool, error)

Types

type ShardManager

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

ShardManager manages a set of database shards and provides methods to interact with them.

func New

func New(ctx context.Context, connectionStrings []string) (*ShardManager, error)

New creates a new ShardManager instance by initializing connections to the provided database connection strings. It returns an error if any connection fails.

func (*ShardManager) Close

func (s *ShardManager) Close(ctx context.Context) error

Close closes all the database connections managed by the ShardManager.

func (*ShardManager) Ping

func (s *ShardManager) Ping(ctx context.Context) error

Ping checks the connectivity of all shards by pinging each one. It returns an error if any shard is unreachable.

func (*ShardManager) SetShardIndexFunc

func (s *ShardManager) SetShardIndexFunc(ctx context.Context, f func(key any, count int) (int, error))

SetShardIndexFunc sets a custom shard index function to determine which shard to use based on the provided key.

func (*ShardManager) Shard

func (s *ShardManager) Shard(ctx context.Context, key any) (*pgxpool.Pool, error)

Shard returns the database shard corresponding to the provided key. It uses the shard index function to determine the appropriate shard.

func (*ShardManager) Shards

func (s *ShardManager) Shards(ctx context.Context) ([]*pgxpool.Pool, error)

Shards returns all the database shards managed by the ShardManager.