postgres

Documentation

Overview

Package postgres provides a PostgreSQL driver for GORM, offering tools to facilitate the construction and management of multi-tenant applications.

It enables the isolation of tenant data in separate PostgreSQL schemas.

Example:

import (

	"github.com/bartventer/gorm-multitenancy/v5"
	"github.com/bartventer/gorm-multitenancy/v5/drivers/postgres"
	"gorm.io/gorm"

)

func main() {
	db, err := gorm.Open(postgres.Open("your connection string"), &gorm.Config{})
	if err != nil {
		panic(err)
	}

	// Register your tenant model
	if err := postgres.RegisterModels(db, &Tenant{}); err != nil {
		panic(err)
	}

	// Create public schema
	if err := postgres.MigratePublicSchema(db); err != nil {
		panic(err)
	}

	// Create a new tenant
	tenant := Tenant{
		TenantModel: postgres.TenantModel{
			DomainURL:  "tenant1.example.com",
			SchemaName: "tenant1",
		},
	}
	if err := db.Create(&tenant).Error; err != nil {
		panic(err)
	}

	// Create schema for the new tenant
	postgres.CreateSchemaForTenant(db, tenant.SchemaName)

	// Drop schema for the tenant
	postgres.DropSchemaForTenant(db, tenant.SchemaName)
}

Index

• Constants
• func CreateSchemaForTenant(db *gorm.DB, schemaName string) error
• func DropSchemaForTenant(db *gorm.DB, schemaName string) error
• func MigratePublicSchema(db *gorm.DB) error
• func New(config Config, models ...interface{}) gorm.Dialector
• func Open(dsn string, models ...interface{}) gorm.Dialector
• func RegisterModels(db *gorm.DB, models ...interface{}) error
• type Config
• type Dialector
  • func (dialector Dialector) Migrator(db *gorm.DB) gorm.Migrator
• type Migrator
  • func (m Migrator) AutoMigrate(values ...interface{}) error
  • func (m *Migrator) CreateSchemaForTenant(tenant string) error
  • func (m *Migrator) DropSchemaForTenant(tenant string) error
  • func (m *Migrator) MigratePublicSchema() error
• type MultitenancyMigrator
• type TenantModel

Constants

const (
	// PublicSchemaName is the name of the public schema.
	PublicSchemaName = "public"
)

Functions

func CreateSchemaForTenant

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

CreateSchemaForTenant creates a new schema for a specific tenant in the PostgreSQL database, and migrates the private tables for the tenant. It takes a gorm.DB instance and the name of the schema as parameters. Returns an error if the schema creation fails.

func DropSchemaForTenant

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

DropSchemaForTenant drops the schema for a specific tenant in the PostgreSQL database (CASCADING all objects in the schema). It takes a *gorm.DB instance and the name of the schema as parameters. Returns an error if there was a problem dropping the schema.

func MigratePublicSchema

func MigratePublicSchema(db *gorm.DB) error

MigratePublicSchema migrates the public schema in the database. It takes a *gorm.DB as input and returns an error if any.

func New

func New(config Config, models ...interface{}) gorm.Dialector

New creates a new PostgreSQL dialector with multitenancy support. It takes a Config struct as the first parameter and variadic models as the second parameter. The Config struct contains the necessary configuration for connecting to the PostgreSQL database. The models parameter is a list of GORM models that will be used for multitenancy configuration. It returns a gorm.Dialector that can be used with GORM. If there is an error during the creation of the multitenancy configuration, it will panic.

func Open

func Open(dsn string, models ...interface{}) gorm.Dialector

Open opens a connection to a PostgreSQL database using the provided DSN (Data Source Name) and models. It returns a gorm.Dialector that can be used to interact with the database. The models parameter is optional and can be used to specify the database models that should be registered. If an error occurs while creating the multitenancy configuration, it panics.

func RegisterModels

func RegisterModels(db *gorm.DB, models ...interface{}) error

RegisterModels registers the given models with the provided gorm.DB instance for multitenancy support. It initializes the multitenancy configuration for the database dialector. The models parameter should be a variadic list of model structs. Returns an error if there is a failure in registering the models or initializing the multitenancy configuration.

Types

type Config

type Config = postgres.Config

Config is the configuration for the postgres driver.

type Dialector

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

Dialector is the postgres 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. It creates a new instance of Migrator with the provided database connection and dialector. It also includes a multitenancyConfig that contains information about public models, tenant models, and all models. The Migrator is thread-safe and uses a sync.RWMutex for synchronization.

type Migrator

type Migrator struct {
	postgres.Migrator // gorm postgres migrator
	// contains filtered or unexported fields
}

Migrator is the struct that implements the MultitenancyMigrator interface.

func (Migrator) AutoMigrate

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

AutoMigrate migrates the specified values to the database. It checks for migration options in the context and performs the migration accordingly. If no migration options are found or if the migration options are invalid, an error is returned. The supported migration options are migrationOptionPublicTables and migrationOptionTenantTables. For any other migration option, an error is returned.

func (*Migrator) CreateSchemaForTenant

func (m *Migrator) CreateSchemaForTenant(tenant string) error

CreateSchemaForTenant creates a schema for a specific tenant in the database. It first checks if the schema already exists, and if not, it creates the schema. Then, it sets the search path to the newly created schema. After that, it migrates the private tables for the specified tenant. If there are no private tables to migrate, it returns an error. The function returns an error if any of the steps fail.

func (*Migrator) DropSchemaForTenant

func (m *Migrator) DropSchemaForTenant(tenant string) error

DropSchemaForTenant drops the schema for a specific tenant. It executes a transaction and drops the schema using the provided tenant name. If an error occurs during the transaction or while dropping the schema, it returns an error. Otherwise, it returns nil.

func (*Migrator) MigratePublicSchema

func (m *Migrator) MigratePublicSchema() error

MigratePublicSchema migrates the public tables in the database. It checks if there are any public tables to migrate and then performs the migration. If an error occurs during the migration, it logs the error. This function returns an error if there are no public tables to migrate or if an error occurs during the migration.

type MultitenancyMigrator

type MultitenancyMigrator interface {
	multitenancy.Migrator

	// CreateSchemaForTenant creates the schema for the tenant, and migrates the private tables
	//
	// Parameters:
	// 	- tenant: the tenant's schema name
	//
	// Returns:
	// 	- error: the error if any
	CreateSchemaForTenant(tenant string) error
	// DropSchemaForTenant drops the schema for the tenant (CASCADING tables)
	//
	// Parameters:
	// 	- tenant: the tenant's schema name
	//
	// Returns:
	// 	- error: the error if any
	DropSchemaForTenant(tenant string) error
	// MigratePublicSchema migrates the public tables
	MigratePublicSchema() error
}

MultitenancyMigrator is the interface for the postgres migrator with multitenancy support.

type TenantModel

type TenantModel struct {
	// DomainURL is the domain URL of the tenant
	DomainURL string `json:"domainURL" gorm:"column:domain_url;uniqueIndex;size:128"`

	// SchemaName is the schema name of the tenant.
	//
	// Field-level permissions are restricted to read and create.
	//
	// The following constraints are applied:
	// 	- unique index
	// 	- size: 63
	// 	- check: schema_name ~ '^[_a-zA-Z][_a-zA-Z0-9]{2,}$' AND schema_name !~ '^pg_' (to prevent invalid schema names)
	SchemaName string `` /* 152-byte string literal not displayed */
}

TenantModel a basic GoLang struct which includes the following fields: DomainURL, SchemaName. It's intended to be embedded into any public postgresql model that needs to be scoped to a tenant. It may be embedded into your model or you may build your own model without it.

For example:

type Tenant struct {
  postgres.TenantModel
}