github.com/haraldrudell/parl@v0.4.176/if-db.go (about)

     1  /*
     2  © 2022–present Harald Rudell <harald.rudell@gmail.com> (https://haraldrudell.github.io/haraldrudell/)
     3  ISC License
     4  */
     5  
     6  package parl
     7  
     8  import (
     9  	"context"
    10  	"database/sql"
    11  )
    12  
    13  // NoPartition interacts with a data source that is not partitioned by year or otherwise
    14  const NoPartition DBPartition = ""
    15  
    16  // DB is a parallel database connection
    17  //   - DB applies to any database implementation
    18  //   - psql provides implementation with caching of:
    19  //   - — DB objects and
    20  //   - — prepared statements
    21  //   - DB is obtained via new function like [DBFactory.NewDB].
    22  //     Such returned DB can use:
    23  //   - — its data-source namer to handle partitioning
    24  //   - — delegation to its underlying possibly partitioned DB implementation
    25  //   - — caching of DB implementation-objects and prepared statements
    26  //   - — its schema function to bootstrap and migrate databases
    27  type DB interface {
    28  	// Exec executes a query not returning any rows
    29  	//	- ExecResult contains last inserted ID if any and rows affected
    30  	Exec(partition DBPartition, query string, ctx context.Context,
    31  		args ...any) (execResult ExecResult, err error)
    32  	// Query executes a query returning zero or more rows
    33  	Query(partition DBPartition, query string, ctx context.Context,
    34  		args ...any) (sqlRows *sql.Rows, err error)
    35  	// Query executes a query known to return exactly one row
    36  	//	- zero rows returns error: sql: no rows in result set
    37  	QueryRow(partition DBPartition, query string, ctx context.Context,
    38  		args ...any) (sqlRow *sql.Row, err error)
    39  	// Query executes a query known to return exactly one row and first column a string value
    40  	QueryString(partition DBPartition, query string, ctx context.Context,
    41  		args ...any) (value string, err error)
    42  	// Query executes a query known to return exactly one row and first column an int value
    43  	QueryInt(partition DBPartition, query string, ctx context.Context,
    44  		args ...any) (value int, err error)
    45  	// Close closes the database connection
    46  	Close() (err error)
    47  }
    48  
    49  // ExecResult is the result from [DB.Exec], a query not returning rows
    50  type ExecResult interface {
    51  	// - ID is last inserted ID if any
    52  	// - rows is number of rows affected
    53  	Get() (ID int64, rows int64)
    54  	// “sql.Result: ID afe3… rows: 123”
    55  	String() (s string)
    56  }
    57  
    58  // DBPartition is partition reference for a partitioned database
    59  //   - partition is typically one table per year
    60  //   - DBPartition applies to any database implementation
    61  type DBPartition string
    62  
    63  // DBFactory is a standardized way to obtain DB objects
    64  //   - DBFactory applies to any database implementation
    65  type DBFactory interface {
    66  	// NewDB returns a DB object implementation.
    67  	// The schema function executes application-specific SQL initialization for
    68  	// a new datasource
    69  	//	- executes CREATE of tables and indexes
    70  	//	- configures database-specific referential integrity and journaling
    71  	NewDB(
    72  		dsnr DataSourceNamer,
    73  		schema func(dataSource DataSource, ctx context.Context) (err error),
    74  	) (db DB)
    75  }