xpg

README

xpg

Обёртка для PostgreSQL в стиле ActiveRecords

Это не ORM, этот пакет, просто помогает упорядочить структуру и упрощает типовые задачи.

Установка

go get -u github.com/PavelVershinin/xpg/...

Тестирование

$ go test -v

Использование

	ctx := context.TODO()

	// Создание конфигурации подключения к БД
	config, err := pgxpool.ParseConfig("postgres://postgres:123456@localhost:5432/test")
	if err != nil {
		log.Fatal(err)
	}

	// Создание нового пула подключений, с именем test, и директорией с миграциями migrations
	if err := xpg.NewConnectionPool(ctx, "test", config, "migrations"); err != nil {
		log.Fatal(err)
	}

	// Отложенное закрытие всех подключений
	defer xpg.Close()

	// Проверка новых файлов миграций, для подключения main
	// Все миграции складываются в одну директорию, для main это будет migrations, с именами #SERIAL#_up.sql для поднятия
	// и #SERIAL#_down.sql для отката
	// #SERIAL# порядковый номер миграции
	// Для работы системы миграций будет создана таблица xpg_migrations её нельзя ни удалять ни изменять
	if err := migrations.Up(ctx, "test", -1); err != nil {
		log.Fatal(err)
	}

	// Создание таблицы в БД из модели
	// В структуре модели, у каждого поля должен быть прописан тег xpg, с описанием этого поля в SQL
	// Например:
	// type Role struct {
	//	 xpg.Model
	//	 Name string `xpg:"name VARCHAR(50) NOT NULL DEFAULT ''"`
	// }
	if err := migrations.Restore(ctx, &test.Role{}); err != nil {
		log.Fatal(err)
	}
	if err := migrations.Restore(ctx, &test.User{}); err != nil {
		log.Fatal(err)
	}

	// Запись в БД (INSERT)
	role := &test.Role{}
	role.Name = "user"
	if err := role.Save(ctx); err != nil {
		log.Fatal(err)
	}
	log.Printf("Запись сохранена в таблице %s, ей присвоен ID %d", role.Table(), role.ID)

	user := &test.User{}
	user.FirstName = "Ivan"
	user.SecondName = "Ivanovich"
	user.LastName = "Ivanov"
	user.Email = "ivan@mail.ru"
	user.Role = role
	if err := user.Save(ctx); err != nil {
		log.Fatal(err)
	}
	log.Printf("Запись сохранена в таблице %s, ей присвоен ID %d", user.Table(), user.ID)

	// Обновление (UPDATE)
	user.Phone = "+7 999 999-99-99"
	if err := user.Save(ctx); err != nil {
		log.Fatal(err)
	}
	log.Printf("Запись c ID %d, обновлена", user.ID)

	// Выборка (SELECT)
	users := []*test.User{}
	query := xpg.New(&test.User{}).
		WhereBetween("id", 1, 15).
		OrderBy("id", "DESC")
	rows, err := query.Select(ctx)
	if err != nil {
		log.Fatal(err)
	}
	for row := range rows.Fetch() {
		users = append(users, row.(*test.User))
	}
	rows.Close()

Автогенерация кода модели

• В файле где будет жить модель, создать структуру модели, с встроеным в неё xpg.Model
• У каждого поля структуры, желательно, прописать тег xpg, с описанием этого поля в SQL

Пример структуры:

type User struct {
	xpg.Model
	FirstName  string `xpg:"first_name VARCHAR(50) NOT NULL DEFAULT ''"`
	SecondName string `xpg:"second_name VARCHAR(50) NOT NULL DEFAULT ''"`
	LastName   string `xpg:"last_name VARCHAR(50) NOT NULL DEFAULT ''"`
	Email      string `xpg:"email VARCHAR(254) NOT NULL DEFAULT ''"`
	Phone      string `xpg:"phone VARCHAR(18) NOT NULL DEFAULT ''"`
	Role       int64  `xpg:"role BIGINT NOT NULL DEFAULT 0"`
	Balance    int64  `xpg:"balance BIGINT NOT NULL DEFAULT 0"`
}

Вызвать команду:

$ xpgen -path=/absolute/path/model.go -connect=main

Полученым кодом, дополнить файл с моделью.

Documentation

Index

• func AddConnectionsPool(poolName string, pool *pgxpool.Pool, migrationsPath string) error
• func Close()
• func DB(poolName string) *pgxpool.Pool
• func MigrationsPath(poolName string) string
• func NewConnectionPool(ctx context.Context, poolName string, connConfig *pgxpool.Config, ...) error
• func SetTimezone(ctx context.Context, poolName string, location *time.Location) error
• type Column
• type Model
  • func (Model) Columns() string
  • func (m *Model) Delete(ctx context.Context) error
  • func (Model) PoolName() (name string)
  • func (m *Model) Save(ctx context.Context) (err error)
  • func (m *Model) Scan(src interface{}) error
  • func (Model) ScanRow(rows pgx.Rows) (Modeler, error)
  • func (Model) Table() string
  • func (m Model) Value() (driver.Value, error)
• type Modeler
• type Pool
  • func New(model Modeler) *Pool
  • func (p *Pool) BuildCount() (string, []interface{})
  • func (p *Pool) BuildSelect() (string, []interface{})
  • func (p *Pool) BuildSum(column string) (string, []interface{})
  • func (p *Pool) Close()
  • func (p *Pool) Columns(ctx context.Context) ([]Column, error)
  • func (p *Pool) Count(ctx context.Context) (int64, error)
  • func (p *Pool) Databases(ctx context.Context) ([]string, error)
  • func (p *Pool) Delete(ctx context.Context) error
  • func (p *Pool) Distinct(on ...string) *Pool
  • func (p *Pool) EnumValues(ctx context.Context, name string) ([]string, error)
  • func (p *Pool) Enums(ctx context.Context) (map[string][]string, error)
  • func (p *Pool) Exists(ctx context.Context) (bool, error)
  • func (p *Pool) First(ctx context.Context) (Modeler, error)
  • func (p *Pool) FullJoin(table, alias, condition string) *Pool
  • func (p *Pool) GroupBy(column string, columns ...string) *Pool
  • func (p *Pool) GroupWhere(f func(p *Pool)) *Pool
  • func (p *Pool) Insert(ctx context.Context, data map[string]interface{}) (id int64, err error)
  • func (p *Pool) Join(table, alias, condition string) *Pool
  • func (p *Pool) LeftJoin(table, alias, condition string) *Pool
  • func (p *Pool) Limit(limit int) *Pool
  • func (p *Pool) Offset(offset int) *Pool
  • func (p *Pool) OrGroupWhere(f func(p *Pool)) *Pool
  • func (p *Pool) OrWhere(column, operator string, value interface{}) *Pool
  • func (p *Pool) OrWhereBetween(column string, from, to interface{}) *Pool
  • func (p *Pool) OrWhereIn(column string, values *WhereInValues) *Pool
  • func (p *Pool) OrWhereNotIn(column string, values *WhereInValues) *Pool
  • func (p *Pool) OrWhereRaw(sql string, bindings ...interface{}) *Pool
  • func (p *Pool) OrderBy(column, order string) *Pool
  • func (p *Pool) OrderByRand() *Pool
  • func (p *Pool) OrderByRaw(orderRaw string) *Pool
  • func (p *Pool) Query(ctx context.Context, query string, args ...interface{}) (*Rows, error)
  • func (p *Pool) RightJoin(table, alias, condition string) *Pool
  • func (p *Pool) Select(ctx context.Context) (*Rows, error)
  • func (p *Pool) Sum(ctx context.Context, column string) (float64, error)
  • func (p *Pool) Tables(ctx context.Context) ([]string, error)
  • func (p *Pool) Union(all bool, queries ...*Pool) *Pool
  • func (p *Pool) Update(ctx context.Context, data map[string]interface{}) error
  • func (p *Pool) Validation(ctx context.Context, data map[string]interface{}) (validData map[string]interface{}, err error)
  • func (p *Pool) Where(column, operator string, value interface{}) *Pool
  • func (p *Pool) WhereBetween(column string, from, to interface{}) *Pool
  • func (p *Pool) WhereIn(column string, values *WhereInValues) *Pool
  • func (p *Pool) WhereNotIn(column string, values *WhereInValues) *Pool
  • func (p *Pool) WhereRaw(sql string, bindings ...interface{}) *Pool
  • func (p *Pool) Write(ctx context.Context, data map[string]interface{}) (int64, error)
• type Rows
  • func (r *Rows) Fetch() <-chan Modeler
  • func (r *Rows) Get() (Modeler, error)
• type WhereInValues
  • func (w *WhereInValues) Int(in ...int) *WhereInValues
  • func (w *WhereInValues) Int64(in ...int64) *WhereInValues
  • func (w *WhereInValues) Interface(in ...interface{}) *WhereInValues
  • func (w *WhereInValues) Sql(args []interface{}) (string, []interface{})
  • func (w *WhereInValues) String(in ...string) *WhereInValues

Functions

func AddConnectionsPool

func AddConnectionsPool(poolName string, pool *pgxpool.Pool, migrationsPath string) error

AddConnectionsPool Добавит существующее подключение в коллекцию

func Close

func Close()

Close Закроет все подключения к БД

func DB

func DB(poolName string) *pgxpool.Pool

DB Вернёт нативное подключение к БД

func MigrationsPath

func MigrationsPath(poolName string) string

MigrationsPath Вернёт путь к директории с миграциями

func NewConnectionPool

func NewConnectionPool(ctx context.Context, poolName string, connConfig *pgxpool.Config, migrationsPath string) error

NewConnectionPool Создаст новое подключение к БД

func SetTimezone

func SetTimezone(ctx context.Context, poolName string, location *time.Location) error

SetTimezone Задаст часовой пояс

Types

type Column

type Column struct {
	Name    string
	Type    string
	NotNull bool
	HasDef  bool
	Num     int
}

Column Свойства колонки таблицы

type Model

type Model struct {
	ID int64
	//...
	CreatedAt xpgtypes.NullTime
	UpdatedAt xpgtypes.NullTime
}

Model базовая модель соответствующая минимально требуемой структуре Modeler

func (Model) Columns

func (Model) Columns() string

Columns Список полей, которые необходимо получать запросом SELECT

func (*Model) Delete

func (m *Model) Delete(ctx context.Context) error

Delete Удаление записи из БД

func (Model) PoolName

func (Model) PoolName() (name string)

PoolName Возвращает название подключения к БД

func (*Model) Save

func (m *Model) Save(ctx context.Context) (err error)

Save Сохранение новой/измененной структуры в БД

func (*Model) Scan

func (m *Model) Scan(src interface{}) error

Scan Реализация интерфейса sql.Scanner

func (Model) ScanRow

func (Model) ScanRow(rows pgx.Rows) (Modeler, error)

ScanRow Реализация чтения строки из результата запроса

func (Model) Table

func (Model) Table() string

Table Возвращает название таблицы в базе данных

func (Model) Value

func (m Model) Value() (driver.Value, error)

Value Реализация интерфейса driver.Valuer

type Modeler

type Modeler interface {
	sql.Scanner
	driver.Valuer
	Table() string
	Columns() string
	PoolName() string
	ScanRow(rows pgx.Rows) (Modeler, error)
	Save(context.Context) error
	Delete(context.Context) error
}

Modeler интерфейс модели

type Pool

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

Pool пул соединений

func New

func New(model Modeler) *Pool

New Вернёт подключение для работы с моделью

func (*Pool) BuildCount

func (p *Pool) BuildCount() (string, []interface{})

BuildCount Вернёт строку запроса и аргументы

func (*Pool) BuildSelect

func (p *Pool) BuildSelect() (string, []interface{})

BuildSelect Вернёт строку запроса и аргументы

func (*Pool) BuildSum

func (p *Pool) BuildSum(column string) (string, []interface{})

BuildSum Вернёт строку запроса и аргументы

func (*Pool) Close

func (p *Pool) Close()

Close Закроет подключение к БД

func (*Pool) Columns

func (p *Pool) Columns(ctx context.Context) ([]Column, error)

Columns Вернёт список колонок текущей таблицы

func (*Pool) Count

func (p *Pool) Count(ctx context.Context) (int64, error)

Count Получить количество записей

func (*Pool) Databases

func (p *Pool) Databases(ctx context.Context) ([]string, error)

Databases Список баз данных

func (*Pool) Delete

func (p *Pool) Delete(ctx context.Context) error

Delete Удаление записи из БД

func (*Pool) Distinct

func (p *Pool) Distinct(on ...string) *Pool

Distinct Удаление дублей

func (*Pool) EnumValues

func (p *Pool) EnumValues(ctx context.Context, name string) ([]string, error)

EnumValues Вернёт доступные значения для типа ENUM

func (*Pool) Enums

func (p *Pool) Enums(ctx context.Context) (map[string][]string, error)

Enums Вернёт доступные перечисления

func (*Pool) Exists

func (p *Pool) Exists(ctx context.Context) (bool, error)

Exists Проверка наличия записи в базе

func (*Pool) First

func (p *Pool) First(ctx context.Context) (Modeler, error)

First Получить первую запись

func (*Pool) FullJoin

func (p *Pool) FullJoin(table, alias, condition string) *Pool

FullJoin Присоединит таблицу FULL OUTER JOIN

func (*Pool) GroupBy

func (p *Pool) GroupBy(column string, columns ...string) *Pool

GroupBy Группировка по колонкам

func (*Pool) GroupWhere

func (p *Pool) GroupWhere(f func(p *Pool)) *Pool

GroupWhere Добавит групповое условие WHERE через AND

func (*Pool) Insert

func (p *Pool) Insert(ctx context.Context, data map[string]interface{}) (id int64, err error)

Insert Вставка записи в БД

func (*Pool) Join

func (p *Pool) Join(table, alias, condition string) *Pool

Join Присоединит таблицу INNER JOIN

func (*Pool) LeftJoin

func (p *Pool) LeftJoin(table, alias, condition string) *Pool

LeftJoin Присоединит таблицу LEFT OUTER JOIN

func (*Pool) Limit

func (p *Pool) Limit(limit int) *Pool

Limit Выбрать limit записей

func (*Pool) Offset

func (p *Pool) Offset(offset int) *Pool

Offset Пропустить offset записей

func (*Pool) OrGroupWhere

func (p *Pool) OrGroupWhere(f func(p *Pool)) *Pool

OrGroupWhere Добавит групповое условие WHERE через OR

func (*Pool) OrWhere

func (p *Pool) OrWhere(column, operator string, value interface{}) *Pool

OrWhere Добавит условие WHERE через OR

func (*Pool) OrWhereBetween

func (p *Pool) OrWhereBetween(column string, from, to interface{}) *Pool

OrWhereBetween Добавит условие WHERE BETWEEN через OR

func (*Pool) OrWhereIn

func (p *Pool) OrWhereIn(column string, values *WhereInValues) *Pool

OrWhereIn Добавит условие WHERE IN через OR

func (*Pool) OrWhereNotIn

func (p *Pool) OrWhereNotIn(column string, values *WhereInValues) *Pool

OrWhereNotIn Добавит условие WHERE NOT IN через OR

func (*Pool) OrWhereRaw

func (p *Pool) OrWhereRaw(sql string, bindings ...interface{}) *Pool

OrWhereRaw Произвольное условие WHERE через OR

func (*Pool) OrderBy

func (p *Pool) OrderBy(column, order string) *Pool

OrderBy Отсортировать по

func (*Pool) OrderByRand

func (p *Pool) OrderByRand() *Pool

OrderByRand Отсортировать в случайном порядке

func (*Pool) OrderByRaw

func (p *Pool) OrderByRaw(orderRaw string) *Pool

OrderByRaw Произвольная сортировка

func (*Pool) Query

func (p *Pool) Query(ctx context.Context, query string, args ...interface{}) (*Rows, error)

Query запрос к БД

func (*Pool) RightJoin

func (p *Pool) RightJoin(table, alias, condition string) *Pool

RightJoin Присоединит таблицу RIGHT OUTER JOIN

func (*Pool) Select

func (p *Pool) Select(ctx context.Context) (*Rows, error)

Select Получить записи

func (*Pool) Sum

func (p *Pool) Sum(ctx context.Context, column string) (float64, error)

Sum Получить сумму записей

func (*Pool) Tables

func (p *Pool) Tables(ctx context.Context) ([]string, error)

Tables Вернёт список таблиц в базе данных

func (*Pool) Union

func (p *Pool) Union(all bool, queries ...*Pool) *Pool

Union Объединение запросов

func (*Pool) Update

func (p *Pool) Update(ctx context.Context, data map[string]interface{}) error

Update Изменение записи в БД

func (*Pool) Validation

func (p *Pool) Validation(ctx context.Context, data map[string]interface{}) (validData map[string]interface{}, err error)

Validation Валидация данных перед записью

func (*Pool) Where

func (p *Pool) Where(column, operator string, value interface{}) *Pool

Where Добавит условие WHERE через AND

func (*Pool) WhereBetween

func (p *Pool) WhereBetween(column string, from, to interface{}) *Pool

WhereBetween Добавит условие WHERE BETWEEN через AND

func (*Pool) WhereIn

func (p *Pool) WhereIn(column string, values *WhereInValues) *Pool

WhereIn Добавит условие WHERE IN через AND

func (*Pool) WhereNotIn

func (p *Pool) WhereNotIn(column string, values *WhereInValues) *Pool

WhereNotIn Добавит условие WHERE NOT IN через AND

func (*Pool) WhereRaw

func (p *Pool) WhereRaw(sql string, bindings ...interface{}) *Pool

WhereRaw Произвольное условие WHERE через AND

func (*Pool) Write

func (p *Pool) Write(ctx context.Context, data map[string]interface{}) (int64, error)

Write Запись в БД

type Rows

type Rows struct {
	pgx.Rows
	// contains filtered or unexported fields
}

Rows Интерфейс для хранения результата запроса к БД

func (*Rows) Fetch

func (r *Rows) Fetch() <-chan Modeler

Fetch Метод для перебора for row := range res.Fetch() {

func (*Rows) Get

func (r *Rows) Get() (Modeler, error)

Get Получение очередной строки

type WhereInValues

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

WhereInValues Адаптор для передачи слайсов, в запрос WHERE IN

func (*WhereInValues) Int

func (w *WhereInValues) Int(in ...int) *WhereInValues

Int Загрузка ...int

func (*WhereInValues) Int64

func (w *WhereInValues) Int64(in ...int64) *WhereInValues

Int64 Загрузка ...int64

func (*WhereInValues) Interface

func (w *WhereInValues) Interface(in ...interface{}) *WhereInValues

Interface Загрузка ...interface{}

func (*WhereInValues) Sql

func (w *WhereInValues) Sql(args []interface{}) (string, []interface{})

Sql Вернёт подготовленную строку запроса и дополненный слайс аргументов

func (*WhereInValues) String

func (w *WhereInValues) String(in ...string) *WhereInValues

String Загрузка ...string