postgres

README

postgres

Postgres provides a driver for the gorm-multitenancy package, allowing for easy multitenancy setup in PostgreSQL databases.

Installation

go get -u github.com/bartventer/gorm-multitenancy/postgres/v8

Getting Started

Check out the pkg.go.dev documentation for comprehensive guides and API references.

For PostgreSQL-specific documentation, refer to pkg.go.dev.

Running the Example Application

For a practical demonstration, you can run the example application. It showcases various configurations and usage scenarios.

Contributing

All contributions are welcome! See the Contributing Guide for more details.

License

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

Documentation

Overview

Package postgres provides a gorm.Dialector implementation for PostgreSQL databases to support multitenancy in GORM applications, enabling tenant-specific operations and shared resources management. It includes utilities for registering models, migrating shared and tenant-specific models, and configuring the database for tenant-specific operations.

This package follows the "shared database, separate schemas" approach for multitenancy, which allows for data isolation and schema customization per tenant within a single PostgreSQL database instance. This approach facilitates efficient resource utilization and simplifies maintenance, making it ideal for applications that require flexible data isolation without the overhead of managing multiple database instances.

URL Format

The URL format for PostgreSQL databases is as follows:

postgres://user:password@localhost:5432/dbname?sslmode=disable

See the PostgreSQL connection strings documentation for more information.

Model Registration

To register models for multitenancy support, use RegisterModels. This should be done before running any migrations or tenant-specific operations.

Migration Strategy

To ensure data integrity and schema isolation across tenants,gorm.DB.AutoMigrate has been disabled. Instead, use the provided shared and tenant-specific migration methods. driver.ErrInvalidMigration is returned if the `AutoMigrate` method is called directly.

Concurrent Migrations

To ensure tenant isolation and facilitate concurrent migrations, this package uses PostgreSQL transaction advisory locks. This mechanism prevents concurrent migrations from interfering with each other and ensures that only one migration can run at a time.

Retry Configuration

Exponential backoff retry logic is enabled by default for migrations. To disable retry or customize the retry behavior, either provide options to New or specify options in the DSN connection string of Open. The following options are available:

• `gmt_disable_retry`: Whether to disable retry. Default is false.
• `gmt_max_retries`: The maximum number of retry attempts. Default is 6.
• `gmt_retry_interval`: The initial interval between retry attempts. Default is 2 seconds.
• `gmt_retry_max_interval`: The maximum interval between retry attempts. Default is 30 seconds.

Shared Model Migrations

To migrate shared models, use MigratePublicSchema.

Tenant Model Migrations

To migrate tenant-specific models, use MigrateTenantModels.

Tenant Offboarding

To clean up the database for a removed tenant, use DropSchemaForTenant.

Tenant Context Configuration

To configure the database for operations specific to a tenant, use schema.SetSearchPath.

Current Tenant Context

To retrieve the identifier for the current tenant context, use schema.CurrentSearchPath.

Index

• Constants
• func DropSchemaForTenant(db *gorm.DB, schemaName string) error
• func MigratePublicSchema(db *gorm.DB) error
• func MigrateTenantModels(db *gorm.DB, schemaName string) error
• func New(config Config, opts ...Option) gorm.Dialector
• func Open(dsn string) gorm.Dialector
• func RegisterModels(db *gorm.DB, models ...driver.TenantTabler) error
• type Config
• type Dialector
  • func (dialector Dialector) Migrator(db *gorm.DB) gorm.Migrator
  • func (dialector *Dialector) RegisterModels(models ...driver.TenantTabler) error
• type Migrator
  • func (m Migrator) AutoMigrate(values ...interface{}) error
  • func (m Migrator) DropSchemaForTenant(tenant string) error
  • func (m Migrator) MigrateSharedModels() error
  • func (m Migrator) MigrateTenantModels(tenantID string) error
• type Option
• type Options

Constants

const DriverName = "postgres"

DriverName is the name of the PostgreSQL driver.

Functions

func DropSchemaForTenant

func DropSchemaForTenant(db *gorm.DB, schemaName string) error

DropSchemaForTenant drops the schema for a specific tenant in the PostgreSQL database (CASCADE).

func MigratePublicSchema

func MigratePublicSchema(db *gorm.DB) error

MigratePublicSchema migrates the public schema in the database.

func MigrateTenantModels

func MigrateTenantModels(db *gorm.DB, schemaName string) error

MigrateTenantModels creates a new schema for a specific tenant in the PostgreSQL database.

func New

func New(config Config, opts ...Option) gorm.Dialector

New creates a new PostgreSQL dialector with multitenancy support.

func Open

func Open(dsn string) gorm.Dialector

Open creates a new PostgreSQL dialector with multitenancy support.

func RegisterModels

func RegisterModels(db *gorm.DB, models ...driver.TenantTabler) error

RegisterModels registers the given models with the provided gorm.DB instance for multitenancy support. Not safe for concurrent use by multiple goroutines.

Types

type Config

type Config struct {
	postgres.Config
}

Config provides configuration with multitenancy support.

type Dialector

type Dialector struct {
	*postgres.Dialector
	// contains filtered or unexported fields
}

Dialector provides a dialector with multitenancy support.

func (Dialector) Migrator

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

Migrator returns a gorm.Migrator implementation for the Dialector.

func (*Dialector) RegisterModels

func (dialector *Dialector) RegisterModels(models ...driver.TenantTabler) error

RegisterModels registers the given models with the dialector for multitenancy support.

type Migrator

type Migrator struct {
	postgres.Migrator
	Dialector
}

Migrator provides a migrator with multitenancy support.

func (Migrator) AutoMigrate

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

func (Migrator) DropSchemaForTenant

func (m Migrator) DropSchemaForTenant(tenant string) error

DropSchemaForTenant drops the schema for a specific tenant.

func (Migrator) MigrateSharedModels

func (m Migrator) MigrateSharedModels() error

MigrateSharedModels migrates the public tables in the database.

func (Migrator) MigrateTenantModels

func (m Migrator) MigrateTenantModels(tenantID string) error

MigrateTenantModels creates a schema for a specific tenant and migrates the private tables.

type Option

type Option func(*Options)

Option is a function that modifies an Options instance.

type Options

type Options struct {
	DisableRetry bool            `json:"gmt_disable_retry" mapstructure:"gmt_disable_retry"` // Whether to disable retry.
	Retry        backoff.Options `json:",inline"       mapstructure:",squash"`               // Retry options.
}

Options provides configuration options with multitenancy support. By default, retry is enabled. To disable retry, set DisableRetry to true. Note that the retry logic is only applied to migrations.