profile

package
v0.3.2 Latest Latest
Warning

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

 Go to latest Published: Mar 26, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package profile provides pre-configured database profiles for different workload types. Each profile optimises SQLite settings for specific use cases like read-heavy operations, write-intensive workloads, or mixed scenarios.

Pre-configured profiles:

Use New to build a custom profile from scratch.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AutoVacuum 

type AutoVacuum string

AutoVacuum defines available auto_vacuum modes 

const (
	AutoVacuumNone        AutoVacuum = "NONE"
	AutoVacuumFull        AutoVacuum = "FULL"
	AutoVacuumIncremental AutoVacuum = "INCREMENTAL"
)

type JournalMode 

type JournalMode string

JournalMode defines available journal modes for SQLite 

const (
	JournalDelete   JournalMode = "DELETE"
	JournalTruncate JournalMode = "TRUNCATE"
	JournalPersist  JournalMode = "PERSIST"
	JournalMemory   JournalMode = "MEMORY"
	JournalWal      JournalMode = "WAL"
	JournalOff      JournalMode = "OFF"
)

type LockingMode 

type LockingMode string

LockingMode defines available locking modes 

const (
	LockingNormal    LockingMode = "NORMAL"
	LockingExclusive LockingMode = "EXCLUSIVE"
)

type Pragma added in v0.3.0 

type Pragma string

Pragma identifies a SQLite PRAGMA by name. 

const (
	PragmaJournalMode       Pragma = "journal_mode"
	PragmaSynchronous       Pragma = "synchronous"
	PragmaForeignKeys       Pragma = "foreign_keys"
	PragmaCacheSize         Pragma = "cache_size"
	PragmaMMapSize          Pragma = "mmap_size"
	PragmaTempStore         Pragma = "temp_store"
	PragmaAutoVacuum        Pragma = "auto_vacuum"
	PragmaPageSize          Pragma = "page_size"
	PragmaBusyTimeout       Pragma = "busy_timeout"
	PragmaLockingMode       Pragma = "locking_mode"
	PragmaRecursiveTriggers Pragma = "recursive_triggers"
	PragmaSecureDelete      Pragma = "secure_delete"
	PragmaQueryOnly         Pragma = "query_only"
)

Known pragma names for use with the typed With* methods. Use Profile.Custom to set pragmas not listed here.

type Profile 

type Profile struct {
	MaxOpenConns    int
	MaxIdleConns    int
	ConnMaxLifetime time.Duration
	// contains filtered or unexported fields
}

Profile holds configuration for database connections

func Attached added in v0.3.0 

func Attached() *Profile

Attached creates a profile for an attached database. Only PRAGMA settings are meaningful for attached databases - connection pool parameters (MaxOpenConns, MaxIdleConns, ConnMaxLifetime) are ignored because attached databases share the main connection pool.

Use the With* methods to configure per-schema PRAGMAs: 

profile.Attached().
	WithJournalMode(profile.JournalWal).
	WithCacheSize(-30720)

func New 

func New() *Profile

New creates a new empty profile with initialised pragmas map

func ReadBalanced 

func ReadBalanced() *Profile

ReadBalanced is the recommended default for most applications. 10 connections with a 75MB cache handles moderate concurrency without excessive memory use.

func ReadHeavy 

func ReadHeavy() *Profile

ReadHeavy targets high-concurrency workloads where many goroutines read simultaneously. 25 connections and a 150MB cache reduce contention at the cost of higher memory use. Only worthwhile when read concurrency is the bottleneck.

func ReadLight 

func ReadLight() *Profile

ReadLight targets low-memory environments or applications with infrequent reads. 5 connections and a 30MB cache keep the footprint small at the cost of reduced concurrency under load.

func WriteBalanced 

func WriteBalanced() *Profile

WriteBalanced is the recommended default for most applications. Uses 8192 page size for better write throughput and disables auto-vacuum to avoid write amplification. The larger page size is the primary performance differentiator over WriteLight.

func WriteHeavy 

func WriteHeavy() *Profile

WriteHeavy targets high-volume write workloads. Uses the same 8192 page size as Balanced but doubles the cache and mmap sizes, and increases busy_timeout. The extra memory helps when the working set exceeds Balanced's cache - otherwise performance is identical.

func WriteLight 

func WriteLight() *Profile

WriteLight targets low-memory environments or applications with infrequent writes. Uses 4096 page size and incremental auto-vacuum, trading write throughput for a smaller on-disk footprint.

func (*Profile) Apply 

func (p *Profile) Apply(db *sql.DB) error

Apply configures a database connection with this profile. Sets pool parameters and runs PRAGMAs via db.Exec. Note that PRAGMAs applied this way only reach one connection in the pool. For reliable per-connection PRAGMAs, prefer DSNPragmas with a custom connector.

func (*Profile) ApplyPool added in v0.3.0 

func (p *Profile) ApplyPool(db *sql.DB)

ApplyPool sets connection pool parameters on the database handle without running any PRAGMAs. Use this with sql.OpenDB when PRAGMAs are handled by the DSN or a custom connector.

func (*Profile) Clone 

func (p *Profile) Clone() *Profile

Clone returns a deep copy of the profile

func (*Profile) Custom added in v0.3.0 

func (p *Profile) Custom(name Pragma, value any) *Profile

Custom sets a PRAGMA not covered by the typed With* methods. The name must be a valid SQLite identifier. Invalid names are rejected by the consumption methods (Apply, DSNPragmas, SchemaStatements).

Example: 

profile.New().Custom(profile.Pragma("wal_autocheckpoint"), 1000)

func (*Profile) DSNPragmas added in v0.3.0 

func (p *Profile) DSNPragmas() []string

DSNPragmas returns the profile's PRAGMAs formatted for the modernc.org/sqlite DSN query string. Each entry is a key=value pair like "_pragma=journal_mode(WAL)". The driver applies these on every new connection, solving the per-connection PRAGMA problem that Apply has with pooled connections.

func (*Profile) SchemaStatements added in v0.3.0 

func (p *Profile) SchemaStatements(schema string) []string

SchemaStatements returns the profile's PRAGMAs as schema-qualified SQL statements for an attached database. For example, with schema "analytics", a cache_size pragma becomes "PRAGMA analytics.cache_size = -30720".

func (*Profile) String 

func (p *Profile) String() string

String returns a string representation of the profile

func (*Profile) WithAutoVacuum 

func (p *Profile) WithAutoVacuum(mode AutoVacuum) *Profile

WithAutoVacuum sets the auto_vacuum pragma

func (*Profile) WithBusyTimeout 

func (p *Profile) WithBusyTimeout(ms int) *Profile

WithBusyTimeout sets the busy_timeout pragma for database lock retries. Specifies how long (in milliseconds) to wait for locks before returning SQLITE_BUSY. Higher values reduce lock contention errors but may increase latency. Common values: 5000 (5 seconds, default), 10000 (high contention), 1000 (low latency)

func (*Profile) WithCacheSize 

func (p *Profile) WithCacheSize(kibibytes int) *Profile

WithCacheSize sets the cache_size pragma for SQLite's page cache. Positive values specify cache size in KiB, negative values specify number of pages. Larger cache improves read performance but uses more memory. Example: -102400 = 100MB cache (recommended for most applications)

func (*Profile) WithConnMaxLifetime 

func (p *Profile) WithConnMaxLifetime(d time.Duration) *Profile

WithConnMaxLifetime sets the maximum amount of time a connection may be reused. Prevents accumulation of connection-specific state and handles server restarts. Common values: time.Hour (default), time.Minute*30 (high churn), 0 (unlimited)

func (*Profile) WithForeignKeys 

func (p *Profile) WithForeignKeys(enabled bool) *Profile

WithForeignKeys sets the foreign_keys pragma

func (*Profile) WithJournalMode 

func (p *Profile) WithJournalMode(mode JournalMode) *Profile

WithJournalMode sets the journal_mode pragma

func (*Profile) WithLockingMode 

func (p *Profile) WithLockingMode(mode LockingMode) *Profile

WithLockingMode sets the locking_mode pragma

func (*Profile) WithMMapSize 

func (p *Profile) WithMMapSize(bytes int64) *Profile

WithMMapSize sets the mmap_size pragma for memory-mapped I/O. Specifies the maximum size in bytes that SQLite will use for memory-mapped files. Larger values can improve performance for read-heavy workloads. Common values: 268435456 (256MB), 536870912 (512MB), 0 (disable mmap)

func (*Profile) WithMaxIdleConns 

func (p *Profile) WithMaxIdleConns(n int) *Profile

WithMaxIdleConns sets the maximum number of idle connections in the pool. Should be less than or equal to MaxOpenConns. Higher values reduce connection overhead but use more resources. Typical values: 2-12 depending on workload.

func (*Profile) WithMaxOpenConns 

func (p *Profile) WithMaxOpenConns(n int) *Profile

WithMaxOpenConns sets the maximum number of open connections to the database. For read profiles: higher values allow more concurrent queries (5-25 typical). For write profiles: should be 1 due to SQLite's single-writer constraint.

func (*Profile) WithPageSize 

func (p *Profile) WithPageSize(bytes int) *Profile

WithPageSize sets the page_size pragma for database pages. Must be a power of 2 between 512 and 65536 bytes. Larger pages reduce overhead for large records but use more memory. Common values: 4096 (default), 8192 (good for write-heavy), 16384 (large records)

func (*Profile) WithQueryOnly 

func (p *Profile) WithQueryOnly(enabled bool) *Profile

WithQueryOnly sets the query_only pragma

func (*Profile) WithRecursiveTriggers 

func (p *Profile) WithRecursiveTriggers(enabled bool) *Profile

WithRecursiveTriggers sets the recursive_triggers pragma

func (*Profile) WithSecureDelete 

func (p *Profile) WithSecureDelete(enabled bool) *Profile

WithSecureDelete sets the secure_delete pragma

func (*Profile) WithSynchronous 

func (p *Profile) WithSynchronous(mode SynchronousMode) *Profile

WithSynchronous sets the synchronous pragma

func (*Profile) WithTempStore 

func (p *Profile) WithTempStore(store TempStore) *Profile

WithTempStore sets the temp_store pragma

type SynchronousMode 

type SynchronousMode string

SynchronousMode defines available synchronous levels for SQLite 

const (
	SyncOff    SynchronousMode = "0"
	SyncNormal SynchronousMode = "1"
	SyncFull   SynchronousMode = "2"
	SyncExtra  SynchronousMode = "3"
)

type TempStore 

type TempStore string

TempStore defines available temp_store modes 

const (
	TempStoreDefault TempStore = "DEFAULT"
	TempStoreFile    TempStore = "FILE"
	TempStoreMemory  TempStore = "MEMORY"
)

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.