utils

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 31, 2025 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package utils provides utility functions for pgcopy

Package utils provides internal utility functions for pgcopy.

This package contains common utility functions including:

  • SQL identifier quoting for injection prevention
  • Connection string parsing and masking
  • Logging infrastructure
  • Formatting helpers

SQL Injection Prevention

The quoting functions (QuoteIdent, QuoteTable, QuoteLiteral) implement PostgreSQL's identifier and literal quoting rules to prevent SQL injection. Always use these functions when constructing dynamic SQL with user-provided or database-provided identifiers.

Thread Safety

All functions in this package are stateless and safe for concurrent use.

Index

Constants

View Source 
const (
	ColorReset   = "\033[0m"
	ColorRed     = "\033[31m"
	ColorGreen   = "\033[32m"
	ColorYellow  = "\033[33m"
	ColorBlue    = "\033[34m"
	ColorMagenta = "\033[35m"
	ColorCyan    = "\033[36m"
	ColorWhite   = "\033[37m"
	ColorBold    = "\033[1m"
	ColorDim     = "\033[2m"
)

ANSI color codes

Variables

View Source 
var (
	// ErrCanceled indicates the operation was canceled (typically via context cancellation).
	// This is usually triggered by user interrupt (Ctrl+C) or programmatic shutdown.
	ErrCanceled = errors.New("operation canceled")

	// ErrDeadlineExceeded indicates the operation exceeded its deadline (context timeout).
	// Consider increasing timeouts or using config.NoTimeouts for large operations.
	ErrDeadlineExceeded = errors.New("deadline exceeded")

	// ErrInvalidConfig indicates invalid or inconsistent configuration values.
	// The wrapped message should identify the specific configuration problem.
	ErrInvalidConfig = errors.New("invalid configuration")

	// ErrCopyFailures aggregates one or more errors that occurred during copy operations.
	// Use errors.Join to combine this with individual table errors for full context.
	ErrCopyFailures = errors.New("one or more copy operations failed")

	// ErrFKBackupExists indicates an FK backup file exists from a previous run.
	// This suggests a previous run was interrupted. Manual review may be needed
	// to restore foreign keys before proceeding.
	ErrFKBackupExists = errors.New("foreign key backup file exists")

	// ErrFKRecoveryFailed indicates attempts to recover FKs from the backup file encountered errors.
	// Some foreign keys may be in an inconsistent state - manual database inspection recommended.
	ErrFKRecoveryFailed = errors.New("foreign key backup recovery failed")
)

Functions

func Colorize 

func Colorize(color, text string) string

Colorize adds color to text if output supports it

func ExtractConnectionDetails added in v0.3.0 

func ExtractConnectionDetails(connStr string) string

ExtractConnectionDetails extracts clean postgres://server:port/database information from a connection string Removes credentials for safe display

func FormatDuration 

func FormatDuration(d time.Duration) string

FormatDuration formats a duration without decimal parts

func FormatLogDuration 

func FormatLogDuration(d time.Duration) string

FormatLogDuration formats duration for log files with rounded values

func FormatLogLevel 

func FormatLogLevel(level string) string

FormatLogLevel formats log levels with colors and icons

func FormatNumber 

func FormatNumber(n int64) string

FormatNumber formats large numbers with K/M suffixes

func HighlightFKName 

func HighlightFKName(fkName string) string

HighlightFKName highlights foreign key constraint names

func HighlightNumber 

func HighlightNumber(number any) string

HighlightNumber highlights numbers in brackets and standalone numbers

func HighlightTableName 

func HighlightTableName(schema, table string) string

HighlightTableName highlights table names in log messages

func IsColorSupported 

func IsColorSupported() bool

IsColorSupported checks if the terminal supports colors

func MaskPassword added in v0.3.0 

func MaskPassword(connStr string) string

MaskPassword masks password in PostgreSQL connection strings for safe display

func MatchesAnyPattern 

func MatchesAnyPattern(text string, patterns []string) bool

MatchesAnyPattern checks if a string matches any of the given patterns

func MatchesAnyTablePattern added in v0.5.0 

func MatchesAnyTablePattern(schema, table string, patterns []string) bool

MatchesAnyTablePattern returns true if any pattern matches either table or schema.table.

func MatchesPattern 

func MatchesPattern(text, pattern string) bool

MatchesPattern checks if a string matches a wildcard pattern Supports * wildcard for matching any sequence of characters

func MatchesTablePattern added in v0.5.0 

func MatchesTablePattern(schema, table, pattern string) bool

MatchesTablePattern checks if a pattern matches either the simple table name or the fully-qualified name schema.table. Patterns support * wildcards. Examples: 

users          -> matches table name "users"
public.users   -> matches full name "public.users"
public.*       -> matches any table in schema public
*.users        -> matches table "users" in any schema

func QuoteIdent added in v0.5.0 

func QuoteIdent(s string) string

QuoteIdent returns a PostgreSQL-quoted identifier with embedded quotes escaped.

PostgreSQL identifiers are quoted by surrounding them with double quotes. Embedded double quotes are escaped by doubling them.

Examples: 

QuoteIdent("users")        -> "\"users\""
QuoteIdent("My\"Table")    -> "\"My\"\"Table\""
QuoteIdent("public.users") -> "\"public.users\"" (dot is literal, not schema separator)

Security: This function is critical for SQL injection prevention. Never construct SQL with unquoted identifiers from external sources.

func QuoteJoinIdents added in v0.5.0 

func QuoteJoinIdents(cols []string) string

QuoteJoinIdents quotes each identifier and joins them with comma+space.

This is useful for constructing column lists in SELECT, INSERT, or UPDATE statements.

Examples: 

QuoteJoinIdents([]string{"id", "name"})     -> "\"id\", \"name\""
QuoteJoinIdents([]string{"user\"id"})       -> "\"user\"\"id\""
QuoteJoinIdents(nil)                         -> ""

Security: Always use this function for column lists in dynamic SQL.

func QuoteLiteral added in v0.5.0 

func QuoteLiteral(s string) string

QuoteLiteral returns a single-quoted SQL string literal with embedded quotes escaped.

PostgreSQL string literals are quoted by surrounding them with single quotes. Embedded single quotes are escaped by doubling them.

Examples: 

QuoteLiteral("hello")       -> "'hello'"
QuoteLiteral("it's fine")   -> "'it''s fine'"
QuoteLiteral("")            -> "''"

Note: This function does NOT handle backslash escaping (standard_conforming_strings). PostgreSQL's default (standard_conforming_strings = on) treats backslashes literally.

Security: Use parameterized queries when possible. This function is for cases where dynamic SQL literals are unavoidable.

func QuoteTable added in v0.5.0 

func QuoteTable(schema, table string) string

QuoteTable returns a fully-qualified, quoted table name: "schema"."table".

This function properly handles schema and table names containing special characters, including dots, quotes, and spaces.

Examples: 

QuoteTable("public", "users")     -> "\"public\".\"users\""
QuoteTable("my schema", "my.tbl") -> "\"my schema\".\"my.tbl\""

Security: Always use this function when constructing table references in dynamic SQL to prevent SQL injection.

Types

type LogLevel added in v0.4.0 

type LogLevel int

LogLevel represents verbosity threshold. 

const (
	// LevelDebug enables verbose diagnostic logs.
	LevelDebug LogLevel = iota
	// LevelInfo standard informational logs.
	LevelInfo
	// LevelWarn warning conditions.
	LevelWarn
	// LevelError error conditions.
	LevelError
	// LevelSilent disables all logging.
	LevelSilent
)

type Logger 

type Logger interface {
	Debug(format string, args ...any)
	Info(format string, args ...any)
	Warn(format string, args ...any)
	Error(format string, args ...any)
}

Logger interface for colorized logging

type SimpleLogger 

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

SimpleLogger provides basic logging functionality with slog backend. It maintains the original API for backward compatibility while using structured logging internally.

func NewSilentLogger 

func NewSilentLogger() *SimpleLogger

NewSilentLogger creates a new silent logger that suppresses all output

func NewSimpleLogger 

func NewSimpleLogger(logger *log.Logger) *SimpleLogger

NewSimpleLogger creates a new simple logger with the specified level

func NewSimpleLoggerWithLevel added in v0.7.0 

func NewSimpleLoggerWithLevel(logger *log.Logger, level LogLevel) *SimpleLogger

NewSimpleLoggerWithLevel creates a new logger with explicit level control

func (*SimpleLogger) Debug added in v0.4.0 

func (l *SimpleLogger) Debug(format string, args ...any)

Debug logs verbose diagnostic information.

func (*SimpleLogger) Error added in v0.4.0 

func (l *SimpleLogger) Error(format string, args ...any)

Error logs errors.

func (*SimpleLogger) GetLevel added in v0.7.0 

func (l *SimpleLogger) GetLevel() LogLevel

GetLevel returns the current logging level

func (*SimpleLogger) Info added in v0.4.0 

func (l *SimpleLogger) Info(format string, args ...any)

Info logs informational messages (general progress).

func (*SimpleLogger) SetLevel added in v0.7.0 

func (l *SimpleLogger) SetLevel(level LogLevel)

SetLevel changes the logging level at runtime

func (*SimpleLogger) Warn added in v0.4.0 

func (l *SimpleLogger) Warn(format string, args ...any)

Warn logs warnings.

func (*SimpleLogger) With added in v0.7.0 

func (l *SimpleLogger) With(args ...any) *SimpleLogger

With returns a new logger with additional structured attributes. This is useful for adding context like table names, worker IDs, etc.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.