Паттерны управления трафиком к PostgreSQL в production

Один неудачный аналитический запрос способен положить весь checkout. PlanetScale предлагает решение — Database Traffic Control: ресурсные бюджеты для разных «слоёв» трафика к Postgres. Разбираем паттерны на Go, которые можно перенести на любой стек.

Перевод статьи Patterns for Postgres Traffic Control Джоша Брауна из блога PlanetScale.

Настройка: SQLCommenter и передача тегов через контекст

Большинство паттернов опираются на пользовательские теги, прикреплённые к запросам. Traffic Control читает их в формате SQLCommenter — это SQL-комментарий с URL-кодированными парами ключ=значение, добавляемый в конец запроса:

			SELECT * FROM orders WHERE user_id = $1
/*route='checkout',feature='new_order_flow'*/;
		

Эти теги затем доступны для правил Traffic Control. Вот минимальный хелпер на Go, который добавляет теги в этом формате:

			import (
	"fmt"
	"net/url"
	"sort"
	"strings"
)

// appendTags добавляет теги в формате SQLCommenter к SQL-запросу
func appendTags(query string, tags map[string]string) string {
	if len(tags) == 0 {
		return query
	}
	parts := make([]string, 0, len(tags))
	for k, v := range tags {
		parts = append(parts, fmt.Sprintf("%s='%s'", k, url.QueryEscape(v)))
	}
	sort.Strings(parts) // детерминированный порядок
	return query + " /*" + strings.Join(parts, ",") + "*/"
}
		

Если вы используете pgx с включённым PrepareThreshold, комментарий SQLCommenter станет частью ключа кэша prepared statement. Это может привести к разрастанию кэша планов. Решение — отключить PrepareThreshold для подключений с тегированием или использовать SimpleProtocol.

Примеры кода рассчитаны на Go 1.22+. В частности, r.Pattern (поле http.Request) и range по целому числу (for attempt := range maxRetries) появились именно в этой версии.

Также понадобится способ пробрасывать теги через стек вызовов без изменения каждой сигнатуры функции. Ключ контекста отлично подходит для этого:

			type contextKey string

const sqlTagsKey contextKey = "sql_tags"

func tagsFromContext(ctx context.Context) map[string]string {
	if tags, ok := ctx.Value(sqlTagsKey).(map[string]string); ok {
		// возвращаем копию, чтобы вызывающий код
		// не мог мутировать общее состояние
		out := make(map[string]string, len(tags))
		for k, v := range tags {
			out[k] = v
		}
		return out
	}
	return make(map[string]string)
}

func contextWithTags(ctx context.Context, tags map[string]string) context.Context {
	return context.WithValue(ctx, sqlTagsKey, tags)
}
		

С этими двумя хелперами паттерны ниже просто устанавливают ключи и значения в контексте. Тегирование происходит автоматически при выполнении запроса.

Изоляция сервисов через Postgres-роли

В микросервисной архитектуре один «взбесившийся» сервис не должен деградировать все остальные сервисы, использующие ту же базу данных. Простейший способ изолировать сервис — создать правило Traffic Control на основе уникальной строки подключения или application_name.

Бюджет на username='pscale_api_123abc' изолирует весь трафик от этой роли. Это также помогает при инцидентах — можно мгновенно ограничить долю ресурсов сервиса без передеплоя.

Имя пользователя — это внутреннее Postgres-имя роли, а не имя роли в дашборде. Также можно целиться в кастомные роли, созданные через CREATE ROLE, если ваши микросервисы строго разделяют права на таблицы.

Также можно использовать application_name, добавив его к строке подключения:

			postgresql://other@localhost/otherdb?application_name=myapp
		

Маркировка запросов по HTTP-роутам

Когда вы запускаете монолит или крупный API-сервис, проблема обычно не в целом сервисе — а в конкретных роутах. Эндпоинт /api/export, генерирующий CSV-отчёты, не должен убивать /api/checkout.

HTTP-middleware может инжектировать роут в контекст во время выполнения, до запуска любого обработчика:

			func SQLTagMiddleware(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		tags := tagsFromContext(r.Context())
		route := strings.ReplaceAll(
			strings.ReplaceAll(r.Pattern, "{", ":"), "}", ":")
		tags["route"] = route
		tags["app"] = "web"
		ctx := contextWithTags(r.Context(), tags)
		next.ServeHTTP(w, r.WithContext(ctx))
	})
}
		

Оберните вызовы к базе данных, чтобы они автоматически подхватывали теги:

			// QueryContext для SELECT-запросов
func (db *DB) QueryContext(ctx context.Context,
	query string, args ...any) (*sql.Rows, error) {
	return db.sql.QueryContext(
		ctx, appendTags(query, tagsFromContext(ctx)), args...)
}

// ExecContext для INSERT/UPDATE
func (db *DB) ExecContext(ctx context.Context,
	query string, args ...any) (sql.Result, error) {
	return db.sql.ExecContext(
		ctx, appendTags(query, tagsFromContext(ctx)), args...)
}
		

Теперь каждый запрос несёт информацию о роуте, из которого пришёл. Можно создать бюджет Traffic Control для route='/api-export' и задать ему консервативный лимит CPU.

Это также упрощает управление инцидентами. Если вы видите всплеск и не знаете, какой роут виноват — график нарушений в Traffic Control покажет, какой именно тег route достигает лимитов.

Фича-флаги и новые деплои

Выкатка новой фичи в production всегда несёт риск. Может, новый паттерн запросов нормально работает под тестовой нагрузкой, но становится дорогим на масштабе. Traffic Control позволяет ограничить радиус поражения до того, как ситуация превратится в инцидент.

Простейшая версия устанавливает тег из переменной окружения при старте:

			var deploymentTag = os.Getenv("DEPLOYMENT_TAG")
// например "new_checkout_v2" или git sha "96e350426"

func tagWithDeployment(ctx context.Context) context.Context {
	if deploymentTag == "" {
		return ctx
	}
	tags := tagsFromContext(ctx)
	tags["feature"] = deploymentTag
	return contextWithTags(ctx, tags)
}
		

Установите DEPLOYMENT_TAG=new_checkout_v2 при раскатке новых подов и оставьте переменную пустой на старых. Traffic Control может иметь бюджет на feature='new_checkout_v2' в режиме Warn с первого дня — так вы увидите, как новый код себя ведёт, прежде чем он вызовет проблемы.

Для фича-флагов, управляемых в рантайме, подход тот же, но определяется результатом проверки флага:

			func (h *OrderHandler) ServeHTTP(w http.ResponseWriter,
	r *http.Request) {
	ctx := r.Context()
	if flags.Enabled(ctx, "new_order_flow") {
		tags := tagsFromContext(ctx)
		tags["feature"] = "new_order_flow"
		ctx = contextWithTags(ctx, tags)
	}
	h.processOrder(ctx, w, r)
}
		

Tier-based лимиты для мультитенантных приложений

В SaaS-приложении пользователи бесплатного тарифа не должны деградировать работу enterprise-клиентов. Traffic Control позволяет обеспечить это на уровне базы данных, а не только на уровне приложения.

Инжектируйте тариф пользователя в SQL-теги сразу после аутентификации:

			type Tier string

const (
	TierFree       Tier = "FREE"
	TierPro        Tier = "PRO"
	TierEnterprise Tier = "ENTERPRISE"
)

func WithUserTier(ctx context.Context, tier Tier) context.Context {
	tags := tagsFromContext(ctx)
	tags["tier"] = string(tier)
	return contextWithTags(ctx, tags)
}
		

В middleware аутентификации:

			func AuthMiddleware(users *UserService,
	next http.Handler) http.Handler {
	return http.HandlerFunc(
		func(w http.ResponseWriter, r *http.Request) {
			user, err := users.Authenticate(r)
			if err != nil {
				http.Error(w, "unauthorized",
					http.StatusUnauthorized)
				return
			}
			ctx := WithUserTier(r.Context(), user.Tier)
			next.ServeHTTP(w, r.WithContext(ctx))
		})
}
		

Теперь создайте два бюджета Traffic Control:

• tier='free' — консервативные лимиты на долю сервера и максимальное число параллельных запросов
• tier='pro' — умеренные лимиты

Enterprise-трафик оставьте без бюджета или задайте высокий потолок. Когда пользователь бесплатного тарифа запускает тяжёлый дашборд или триггерит медленный запрос — бюджет сбросит этот трафик до того, как он затронет enterprise-нагрузки.

Паттерны можно комбинировать. Бюджет tier='free' AND route='api-export' будет строже, чем бюджет только на tier='free'. Enterprise-экспорты получат больше ресурсов, чем бесплатные.

Фоновые задачи и скрипты

Фоновые задачи — частая причина инцидентов с базой данных. Миграция, ночная синхронизация или одноразовый бэкфилл данных могут случайно насытить БД, если выполняются быстрее ожидаемого. Traffic Control — чистый способ задать потолок ресурсов без настройки таймаутов на уровне каждого запроса.

Для долгоживущих фоновых воркеров используйте выделенный пул подключений с отдельным application_name:

			func newJobDB(dsn string) (*sql.DB, error) {
	jobDSN, err := url.Parse(dsn)
	if err != nil {
		return nil, err
	}
	q := jobDSN.Query()
	q.Set("application_name", "background-jobs")
	jobDSN.RawQuery = q.Encode()

	db, err := sql.Open("pgx", jobDSN.String())
	if err != nil {
		return nil, err
	}
	db.SetMaxOpenConns(4) // Фоновым задачам не нужна
	                      // высокая конкурентность
	return db, nil
}
		

Функция newJobDB принимает DSN базы и устанавливает application_name в background-jobs перед подключением. Максимум подключений ограничен четырьмя, чтобы фоновая задача не занимала больше воркеров, чем положено.

Установка application_name на уровне строки подключения в коде гарантирует, что имя всегда задано для этого сервиса — независимо от конкретного запроса или переменных окружения. Это можно комбинировать с SQL-комментариями для ещё более гранулярного контроля.

Для одноразовых скриптов и миграций — аналогичный подход. Здесь идентичность скрипта кодируется прямо в строке подключения:

			func scriptDB(dsn, scriptName string) (*sql.DB, error) {
	u, _ := url.Parse(dsn)
	q := u.Query()
	q.Set("application_name",
		"script-"+scriptName) // "script-backfill-order-totals"
	u.RawQuery = q.Encode()
	return sql.Open("pgx", u.String())
}
		

Создайте бюджет Traffic Control для application_name='background-jobs' в режиме Warn. Понаблюдайте, сколько ресурсов базы обычно потребляет фоновая работа. Затем переключите на Enforce, чтобы ограничить её на уровне, при котором она не сможет вытеснить интерактивный трафик.

Обработка заблокированных запросов

Когда Traffic Control в режиме Enforce и запрос превышает бюджет, Postgres возвращает SQLSTATE 53000 с сообщением, начинающимся с [PGINSIGHTS] Traffic Control:. Приложение должно обрабатывать это без падения.

С pgx/v5:

			import (
	"errors"
	"github.com/jackc/pgx/v5/pgconn"
)

const sqlstateTrafficControl = "53000"

func isTrafficControlError(err error) bool {
	var pgErr *pgconn.PgError
	return errors.As(err, &pgErr) &&
		pgErr.Code == sqlstateTrafficControl
}
		

Правильная реакция зависит от роли запроса в приложении. Для некритичных нагрузок — аналитики, отчётов — возвращайте 503 или закэшированный результат:

			func (s *OrderService) GetUserOrders(ctx context.Context,
	userID int64) ([]Order, error) {
	rows, err := s.db.QueryContext(ctx,
		`SELECT id, total FROM orders
		 WHERE user_id = $1`, userID)
	if err != nil {
		if isTrafficControlError(err) {
			// Деградированный ответ вместо 500
			return nil, ErrServiceUnavailable
		}
		return nil, err
	}
	defer rows.Close()
	// ...
}
		

Для критичных путей можно реализовать короткий retry с экспоненциальным backoff:

			func queryWithBackoff(ctx context.Context, db *sql.DB,
	query string, args ...any) (*sql.Rows, error) {
	const maxRetries = 3
	backoff := 100 * time.Millisecond

	for attempt := range maxRetries {
		rows, err := db.QueryContext(ctx, query, args...)
		if err == nil {
			return rows, nil
		}
		if !isTrafficControlError(err) ||
			attempt == maxRetries-1 {
			return nil, err
		}
		select {
		case <-time.After(backoff):
			backoff *= 2
		case <-ctx.Done():
			return nil, ctx.Err()
		}
	}
	return nil, errors.New("overloaded")
}
		

Наблюдение за Warn-режимом

Прежде чем переключить бюджет в Enforce, запустите его в режиме Warn. В этом режиме запросы выполняются успешно, но драйвер получает Postgres-notice. С pgx/v5 можно логировать их, чтобы понять, что именно будет заблокировано:

			config, err := pgx.ParseConfig(dsn)
if err != nil {
	log.Fatal(err)
}

config.OnNotice = func(c *pgconn.PgConn,
	notice *pgconn.Notice) {
	if strings.Contains(notice.Message,
		"[PGINSIGHTS] Traffic Control:") {
		log.Printf(
			"traffic control warning: %s",
			notice.Message)
	}
}
		

Соберите логи за несколько часов репрезентативного трафика. Паттерн срабатываний подскажет, нужно ли корректировать лимиты.

Собираем всё вместе

Паттерны компонуются. В реальном приложении можно наслоить несколько из них:

			func (s *Server) setupMiddleware() http.Handler {
	mux := http.NewServeMux()
	// регистрация роутов...

	var handler http.Handler = mux
	handler = SQLTagMiddleware(handler)  // роут-теги
	handler = AuthMiddleware(s.users, handler) // тир-теги
	return handler
}

// При старте фоновый воркер использует отдельный пул
jobDB, _ := newJobDB(dsn)

// Новые фичи используют DEPLOYMENT_TAG
// DEPLOYMENT_TAG=new_checkout_v2 в манифесте деплоя
		

Traffic Control видит всё это как комбинацию тегов. Бюджет на tier='free' покрывает весь free-трафик независимо от роута. Бюджет на route='api-export' AND tier='free' — конкретную комбинацию. Несколько совпадающих бюджетов применяются одновременно, и запрос должен удовлетворять каждому из них.

Начните в режиме Warn, понаблюдайте, какие бюджеты срабатывают при нормальной нагрузке, ужесточайте лимиты, пока не будут триггериться только патологические случаи — затем переключите на Enforce.

Выводы

Разница между падением базы и деградированным опытом часто сводится к тому, решили ли вы заранее, какой трафик сбрасывать. Traffic Control делает это решение явным и конфигурируемым — вместо того чтобы оставлять его на милость гонки за ресурсы.

Полный текст оригинальной статьи — в блоге PlanetScale.