Docs

backup.go

@@ -69,10 +69,10 @@ func (b *Backup) Status() BackupStatus {
 }
 
 // Run starts the backup:
-//  - copying up to 'npage' pages between the source and destination at each step,
-//  - sleeping 'sleepNs' between steps,
-//  - notifying the caller of backup progress throw the channel 'c',
-//  - closing the backup when done or when an error happens.
+// - copying up to 'npage' pages between the source and destination at each step,
+// - sleeping 'sleepNs' between steps,
+// - notifying the caller of backup progress throw the channel 'c',
+// - closing the backup when done or when an error happens.
 // Sleeping is disabled if 'sleepNs' is zero or negative.
 // Notification is disabled if 'c' is null.
 // (See http://sqlite.org/c3ref/backup_finish.html#sqlite3backupstep, sqlite3_backup_remaining and sqlite3_backup_pagecount)

blob.go

@@ -33,7 +33,7 @@ type BlobReadWriter struct {
 // Zeroblobs are used to reserve space for a BLOB that is later written.
 type ZeroBlobLength int
 
-// NewBlobReader opens a BLOB for incremental I/O.
+// NewBlobReader opens a BLOB for incremental I/O in read-only mode.
 //
 // (See http://sqlite.org/c3ref/blob_open.html)
 func (c *Conn) NewBlobReader(db, table, column string, row int64) (*BlobReader, error) {
@@ -44,7 +44,7 @@ func (c *Conn) NewBlobReader(db, table, column string, row int64) (*BlobReader,
 	return &BlobReader{c, bl, -1, 0}, nil
 }
 
-// NewBlobReadWriter open a BLOB for incremental I/O.
+// NewBlobReadWriter opens a BLOB for incremental I/O.
 // (See http://sqlite.org/c3ref/blob_open.html)
 func (c *Conn) NewBlobReadWriter(db, table, column string, row int64) (*BlobReadWriter, error) {
 	bl, err := c.blob_open(db, table, column, row, true)

cache.go

@@ -87,7 +87,7 @@ func (c *cache) flush() {
 }
 
 // CacheSize returns (current, max) sizes.
-// Cache is turned off when max size is 0
+// Prepared statements cache is turned off when max size is 0
 func (c *Conn) CacheSize() (int, int) {
 	if c.stmtCache.maxSize <= 0 {
 		return 0, 0

driver.go

@@ -39,7 +39,7 @@ type rowsImpl struct {
 }
 
 // Open opens a new database connection.
-// ":memory:" for memory db
+// ":memory:" for memory db,
 // "" for temp file db
 // TODO How to specify open flags?
 func (d *Driver) Open(name string) (driver.Conn, error) {

meta.go

@@ -128,7 +128,7 @@ func (c *Conn) Columns(dbName, table string) ([]Column, error) {
 	return columns, nil
 }
 
-// Column extracts metadata about a column of a table
+// Column extracts metadata about a column of a table.
 // Column.Cid and Column.DfltValue are left unspecified.
 // (See http://sqlite.org/c3ref/table_column_metadata.html)
 func (c *Conn) Column(dbName, tableName, columnName string) (*Column, error) {

pragma.go

@@ -8,20 +8,20 @@ import (
 	"fmt"
 )
 
-// Check database integrity
-// Database name is optional
+// IntegrityCheck checks database integrity.
+// Database name is optional (default is 'main').
 // (See http://www.sqlite.org/pragma.html#pragma_integrity_check
 // and http://www.sqlite.org/pragma.html#pragma_quick_check)
-// TODO Make possible to specify the database-name (PRAGMA %Q.integrity_check(.))
 func (c *Conn) IntegrityCheck(dbName string, max int, quick bool) error {
-	var pragma string
+	var prefix string
 	if quick {
-		pragma = "quick"
+		prefix = "quick"
 	} else {
-		pragma = "integrity"
+		prefix = "integrity"
 	}
+	pragmaName = fmt.Sprintf("%s_check(%d)", prefix, max)
 	var msg string
-	err := c.OneValue(fmt.Sprintf("PRAGMA %s_check(%d)", pragma, max), &msg)
+	err := c.OneValue(pragma(dbName, pragmaName), &msg)
 	if err != nil {
 		return err
 	}
@@ -31,38 +31,40 @@ func (c *Conn) IntegrityCheck(dbName string, max int, quick bool) error {
 	return nil
 }
 
-// Database name is optional
-// Returns the text encoding used by the main database
+// Encoding returns the text encoding used by the specified database.
+// Database name is optional (default is 'main').
 // (See http://sqlite.org/pragma.html#pragma_encoding)
 func (c *Conn) Encoding(dbName string) (string, error) {
 	var encoding string
-	err := c.OneValue(pragma(dbName, "PRAGMA encoding", "PRAGMA %Q.encoding"), &encoding)
+	err := c.OneValue(pragma(dbName, "encoding"), &encoding)
 	if err != nil {
 		return "", err
 	}
 	return encoding, nil
 }
 
-// Database name is optional
+// SchemaVersion gets the value of the schema-version.
+// Database name is optional (default is 'main').
 // (See http://sqlite.org/pragma.html#pragma_schema_version)
 func (c *Conn) SchemaVersion(dbName string) (int, error) {
 	var version int
-	err := c.OneValue(pragma(dbName, "PRAGMA schema_version", "PRAGMA %Q.schema_version"), &version)
+	err := c.OneValue(pragma(dbName, "schema_version"), &version)
 	if err != nil {
 		return -1, err
 	}
 	return version, nil
 }
 
+// SetRecursiveTriggers sets or clears the recursive trigger capability.
+// Database name is optional (default is 'main').
 // (See http://sqlite.org/pragma.html#pragma_recursive_triggers)
-// TODO Make possible to specify the database-name (PRAGMA %Q.recursive_triggers=%)
-func (c *Conn) SetRecursiveTriggers(on bool) error {
-	return c.exec(fmt.Sprintf("PRAGMA recursive_triggers=%t", on))
+func (c *Conn) SetRecursiveTriggers(dbName string, on bool) error {
+	return c.exec(pragma(dbName, fmt.Sprintf("recursive_triggers=%t"), on))
 }
 
-func pragma(dbName, unqualified, qualified string) string {
+func pragma(dbName, pragmaName string) string {
 	if len(dbName) == 0 {
-		return unqualified
+		return "PRAGMA " + pragmaName
 	}
-	return Mprintf(qualified, dbName)
+	return Mprintf("PRAGMA %Q."+pragmaName, dbName)
 }

sqlite.go

@@ -36,12 +36,12 @@ func (e *ConnError) Code() Errno {
 	return e.code
 }
 
-// FIXME  it might be the case that a second error occurs on a separate thread in between the time of the first error and the call to this method.
+// FIXME it might be the case that a second error occurs on a separate thread in between the time of the first error and the call to this method.
 func (e *ConnError) ExtendedCode() int {
 	return int(C.sqlite3_extended_errcode(e.c.db))
 }
 
-// Return Database file name from which the error comes from.
+// Filename returns database file name from which the error comes from.
 func (e *ConnError) Filename() string {
 	return e.c.Filename("main")
 }
@@ -148,6 +148,8 @@ func (c *Conn) specificError(msg string, a ...interface{}) error {
 	return &ConnError{c: c, code: ErrSpecific, msg: fmt.Sprintf(msg, a...)}
 }
 
+// LastError returns the error for the most recent failed sqlite3_* API call associated with a database connection.
+// (See http://sqlite.org/c3ref/errcode.html)
 func (c *Conn) LastError() error {
 	if c == nil {
 		return errors.New("nil sqlite database")
@@ -192,7 +194,7 @@ const (
 )
 
 // Open opens a new database connection.
-// ":memory:" for memory db
+// ":memory:" for memory db,
 // "" for temp file db
 //
 // (See sqlite3_open_v2: http://sqlite.org/c3ref/open.html)
@@ -241,8 +243,8 @@ func (c *Conn) BusyTimeout(ms int) error { // TODO time.Duration ?
 	return c.error(C.sqlite3_busy_timeout(c.db, C.int(ms)))
 }
 
-// Enable or disable the enforcement of foreign key constraints
-// Calls sqlite3_db_config(db, SQLITE_DBCONFIG_ENABLE_FKEY, b)
+// EnableFKey enables or disables the enforcement of foreign key constraints.
+// Calls sqlite3_db_config(db, SQLITE_DBCONFIG_ENABLE_FKEY, b).
 // Another way is PRAGMA foreign_keys = boolean;
 //
 // (See http://sqlite.org/c3ref/c_dbconfig_enable_fkey.html)
@@ -250,7 +252,8 @@ func (c *Conn) EnableFKey(b bool) (bool, error) {
 	return c.queryOrSetEnableDbConfig(C.SQLITE_DBCONFIG_ENABLE_FKEY, btocint(b))
 }
 
-// Calls sqlite3_db_config(db, SQLITE_DBCONFIG_ENABLE_FKEY, -1)
+// IsFKeyEnabled reports if the enforcement of foreign key constraints is enabled or not.
+// Calls sqlite3_db_config(db, SQLITE_DBCONFIG_ENABLE_FKEY, -1).
 // Another way is PRAGMA foreign_keys;
 //
 // (See http://sqlite.org/c3ref/c_dbconfig_enable_fkey.html)
@@ -259,7 +262,7 @@ func (c *Conn) IsFKeyEnabled() (bool, error) {
 }
 
 // EnableTriggers enables or disables triggers.
-// Calls sqlite3_db_config(db, SQLITE_DBCONFIG_ENABLE_TRIGGER, b)
+// Calls sqlite3_db_config(db, SQLITE_DBCONFIG_ENABLE_TRIGGER, b).
 //
 // (See http://sqlite.org/c3ref/c_dbconfig_enable_fkey.html)
 func (c *Conn) EnableTriggers(b bool) (bool, error) {
@@ -283,12 +286,13 @@ func (c *Conn) queryOrSetEnableDbConfig(key, i C.int) (bool, error) {
 	return false, c.error(rv)
 }
 
-// Enable or disable the extended result codes feature of SQLite.
+// EnableExtendedResultCodes enables or disables the extended result codes feature of SQLite.
 // (See http://sqlite.org/c3ref/extended_result_codes.html)
 func (c *Conn) EnableExtendedResultCodes(b bool) error {
 	return c.error(C.sqlite3_extended_result_codes(c.db, btocint(b)))
 }
 
+// Readonly determines if a database is read-only.
 // (See http://sqlite.org/c3ref/db_readonly.html)
 func (c *Conn) Readonly(dbName string) (bool, error) {
 	cname := C.CString(dbName)
@@ -300,6 +304,7 @@ func (c *Conn) Readonly(dbName string) (bool, error) {
 	return rv == 1, nil
 }
 
+// Filename returns the filename for a database connection.
 // (See http://sqlite.org/c3ref/db_filename.html)
 func (c *Conn) Filename(dbName string) string {
 	cname := C.CString(dbName)
@@ -307,7 +312,7 @@ func (c *Conn) Filename(dbName string) string {
 	return C.GoString(C.sqlite3_db_filename(c.db, cname))
 }
 
-// Prepare and execute one parameterized statement or many statements (separated by semi-colon).
+// Exec prepares and executes one parameterized statement or many statements (separated by semi-colon).
 // Don't use it with SELECT or anything that returns data.
 func (c *Conn) Exec(cmd string, args ...interface{}) error {
 	for len(cmd) > 0 {
@@ -338,7 +343,7 @@ func (c *Conn) Exec(cmd string, args ...interface{}) error {
 	return nil
 }
 
-// Return true if the specified query returns at least one row.
+// Exists returns true if the specified query returns at least one row.
 func (c *Conn) Exists(query string, args ...interface{}) (bool, error) {
 	s, err := c.Prepare(query, args...)
 	if err != nil {
@@ -351,7 +356,7 @@ func (c *Conn) Exists(query string, args ...interface{}) (bool, error) {
 	return s.Next()
 }
 
-// Use it with SELECT that returns only one row with only one column.
+// OneValue is used with SELECT that returns only one row with only one column.
 // Returns io.EOF when there is no row.
 func (c *Conn) OneValue(query string, value interface{}, args ...interface{}) error {
 	s, err := c.Prepare(query, args...)
@@ -371,33 +376,33 @@ func (c *Conn) OneValue(query string, value interface{}, args ...interface{}) er
 	return s.Scan(value)
 }
 
-// Changes counts the number of rows modified.
+// Changes returns the number of database rows that were changed or inserted or deleted by the most recently completed SQL statement on the database connection.
 // If a separate thread makes changes on the same database connection while Changes() is running then the value returned is unpredictable and not meaningful.
 // (See http://sqlite.org/c3ref/changes.html)
 func (c *Conn) Changes() int {
 	return int(C.sqlite3_changes(c.db))
 }
 
-// Total number of rows Modified
+// TotalChanges returns the number of row changes caused by INSERT, UPDATE or DELETE statements since the database connection was opened.
 // (See http://sqlite.org/c3ref/total_changes.html)
 func (c *Conn) TotalChanges() int {
 	return int(C.sqlite3_total_changes(c.db))
 }
 
-// Return the rowid of the most recent successful INSERT into the database.
+// LastInsertRowid returns the rowid of the most recent successful INSERT into the database.
 // If a separate thread performs a new INSERT on the same database connection while the LastInsertRowid() function is running and thus changes the last insert rowid, then the value returned by LastInsertRowid() is unpredictable and might not equal either the old or the new last insert rowid.
 // (See http://sqlite.org/c3ref/last_insert_rowid.html)
 func (c *Conn) LastInsertRowid() int64 {
 	return int64(C.sqlite3_last_insert_rowid(c.db))
 }
 
-// Interrupt a long-running query
+// Interrupt interrupts a long-running query.
 // (See http://sqlite.org/c3ref/interrupt.html)
 func (c *Conn) Interrupt() {
 	C.sqlite3_interrupt(c.db)
 }
 
-// Test for auto-commit mode
+// GetAutocommit tests for auto-commit mode.
 // (See http://sqlite.org/c3ref/get_autocommit.html)
 func (c *Conn) GetAutocommit() bool {
 	return C.sqlite3_get_autocommit(c.db) != 0
@@ -444,16 +449,19 @@ func (c *Conn) Rollback() error {
 	return c.exec("ROLLBACK")
 }
 
+// Savepoint starts a new transaction with a name.
 // (See http://sqlite.org/lang_savepoint.html)
 func (c *Conn) Savepoint(name string) error {
 	return c.exec(Mprintf("SAVEPOINT %Q", name))
 }
 
+// ReleaseSavepoint causes all savepoints back to and including the most recent savepoint with a matching name to be removed from the transaction stack.
 // (See http://sqlite.org/lang_savepoint.html)
 func (c *Conn) ReleaseSavepoint(name string) error {
 	return c.exec(Mprintf("RELEASE %Q", name))
 }
 
+// RollbackSavepoint reverts the state of the database back to what it was just before the corresponding SAVEPOINT.
 // (See http://sqlite.org/lang_savepoint.html)
 func (c *Conn) RollbackSavepoint(name string) error {
 	return c.exec(Mprintf("ROLLBACK TO SAVEPOINT %Q", name))
@@ -505,13 +513,13 @@ func (c *Conn) Close() error {
 	return nil
 }
 
-// Enable or disable extension loading
+// EnableLoadExtension enables or disables extension loading.
 // (See http://sqlite.org/c3ref/enable_load_extension.html)
 func (c *Conn) EnableLoadExtension(b bool) {
 	C.sqlite3_enable_load_extension(c.db, btocint(b))
 }
 
-// Load an extension
+// LoadExtension loads an extension
 // (See http://sqlite.org/c3ref/load_extension.html)
 func (c *Conn) LoadExtension(file string, proc ...string) error {
 	cfile := C.CString(file)