Database - jasonisnthappy

The Database type represents a jasonisnthappy database connection.

Opening a database

Open

Opens a database at the specified path with default options.

func Open(path string) (*Database, error)

path

string

required

Path to the database file

*Database

Database instance

error

Error if the database could not be opened

Example:

db, err := jasonisnthappy.Open("./my_database.db")
if err != nil {
    log.Fatal(err)
}
defer db.Close()

OpenWithOptions

Opens a database with custom options.

func OpenWithOptions(path string, opts DatabaseOptions) (*Database, error)

path

string

required

Path to the database file

opts

DatabaseOptions

required

Custom database configuration options

*Database

Database instance

error

Error if the database could not be opened

Example:

opts := jasonisnthappy.DefaultDatabaseOptions()
opts.ReadOnly = true
opts.CacheSize = 2000

db, err := jasonisnthappy.OpenWithOptions("./my_database.db", opts)
if err != nil {
    log.Fatal(err)
}
defer db.Close()

DefaultDatabaseOptions

Returns the default database options.

func DefaultDatabaseOptions() DatabaseOptions

DatabaseOptions

Default database configuration

Database management

Close

Closes the database and frees associated resources.

func (d *Database) Close()

Example:

db.Close()

BeginTransaction

Starts a new transaction.

func (d *Database) BeginTransaction() (*Transaction, error)

*Transaction

Transaction instance

error

Error if the transaction could not be started

Example:

tx, err := db.BeginTransaction()
if err != nil {
    log.Fatal(err)
}
defer tx.Rollback()

// ... perform operations ...

err = tx.Commit()
if err != nil {
    log.Fatal(err)
}

RunTransaction

Runs a transaction with automatic retries on conflict.

func (d *Database) RunTransaction(fn func(*Transaction) error) error

func(*Transaction) error

required

Function containing transaction operations

error

Error if the transaction failed after retries

Example:

err := db.RunTransaction(func(tx *jasonisnthappy.Transaction) error {
    doc := map[string]interface{}{"name": "Alice", "age": 30}
    _, err := tx.Insert("users", doc)
    return err
})

Configuration

SetTransactionConfig

Sets the transaction retry configuration.

func (d *Database) SetTransactionConfig(config TransactionConfig) error

config

TransactionConfig

required

Transaction configuration with retry settings

error

Error if the configuration could not be set

Example:

config := jasonisnthappy.TransactionConfig{
    MaxRetries: 5,
    RetryBackoffBaseMs: 10,
    MaxRetryBackoffMs: 1000,
}
err := db.SetTransactionConfig(config)

GetTransactionConfig

Gets the current transaction configuration.

func (d *Database) GetTransactionConfig() (*TransactionConfig, error)

*TransactionConfig

Current transaction configuration

error

Error if the configuration could not be retrieved

SetAutoCheckpointThreshold

Sets the auto-checkpoint threshold in WAL frames.

func (d *Database) SetAutoCheckpointThreshold(threshold uint64) error

threshold

uint64

required

Number of WAL frames before automatic checkpoint

error

Error if the threshold could not be set

Database information

GetPath

Returns the database file path.

func (d *Database) GetPath() (string, error)

string

Database file path

error

Error if the path could not be retrieved

IsReadOnly

Returns whether the database is read-only.

func (d *Database) IsReadOnly() (bool, error)

bool

True if the database is read-only

error

Error if the status could not be checked

ListCollections

Returns a list of all collection names.

func (d *Database) ListCollections() ([]string, error)

[]string

List of collection names

error

Error if collections could not be listed

CollectionStats

Returns statistics for a collection.

func (d *Database) CollectionStats(collectionName string) (map[string]interface{}, error)

collectionName

string

required

Name of the collection

map[string]interface{}

Collection statistics as a map

error

Error if stats could not be retrieved

DatabaseInfo

Returns comprehensive database information.

func (d *Database) DatabaseInfo() (map[string]interface{}, error)

map[string]interface{}

Database information including path, size, collections, etc.

error

Error if info could not be retrieved

MaxBulkOperations

Returns the maximum number of bulk operations allowed.

func (d *Database) MaxBulkOperations() (uint, error)

uint

Maximum bulk operations limit

error

Error if limit could not be retrieved

MaxDocumentSize

Returns the maximum document size in bytes.

func (d *Database) MaxDocumentSize() (uint, error)

uint

Maximum document size in bytes

error

Error if size could not be retrieved

MaxRequestBodySize

Returns the maximum HTTP request body size in bytes.

func (d *Database) MaxRequestBodySize() (uint, error)

uint

Maximum request body size in bytes

error

Error if size could not be retrieved

Index management

CreateIndex

Creates a single-field index.

func (d *Database) CreateIndex(collectionName, indexName, field string, unique bool) error

collectionName

string

required

Name of the collection

indexName

string

required

Name for the index

field

string

required

Field to index

unique

bool

required

Whether the index should enforce uniqueness

error

Error if index could not be created

Example:

err := db.CreateIndex("users", "email_idx", "email", true)

CreateCompoundIndex

Creates a compound index on multiple fields.

func (d *Database) CreateCompoundIndex(collectionName, indexName string, fields []string, unique bool) error

collectionName

string

required

Name of the collection

indexName

string

required

Name for the index

fields

[]string

required

Fields to include in the compound index

unique

bool

required

Whether the index should enforce uniqueness

error

Error if index could not be created

Example:

err := db.CreateCompoundIndex("users", "name_age_idx", []string{"name", "age"}, false)

CreateTextIndex

Creates a full-text search index.

func (d *Database) CreateTextIndex(collectionName, indexName, field string) error

collectionName

string

required

Name of the collection

indexName

string

required

Name for the index

field

string

required

Text field to index

error

Error if index could not be created

Example:

err := db.CreateTextIndex("articles", "content_text_idx", "content")

DropIndex

Drops an index from a collection.

func (d *Database) DropIndex(collectionName, indexName string) error

collectionName

string

required

Name of the collection

indexName

string

required

Name of the index to drop

error

Error if index could not be dropped

Example:

err := db.DropIndex("users", "email_idx")

ListIndexes

Returns all indexes for a collection.

func (d *Database) ListIndexes(collectionName string) ([]IndexInfo, error)

collectionName

string

required

Name of the collection

[]IndexInfo

List of index metadata

error

Error if indexes could not be listed

Example:

indexes, err := db.ListIndexes("users")
for _, idx := range indexes {
    fmt.Printf("Index: %s, Fields: %v, Unique: %v\n", idx.Name, idx.Fields, idx.Unique)
}

Schema validation

SetSchema

Sets a JSON schema for a collection.

func (d *Database) SetSchema(collectionName string, schema map[string]interface{}) error

collectionName

string

required

Name of the collection

schema

map[string]interface{}

required

JSON schema for validation

error

Error if schema could not be set

Example:

schema := map[string]interface{}{
    "type": "object",
    "properties": map[string]interface{}{
        "name": map[string]interface{}{"type": "string"},
        "age": map[string]interface{}{"type": "number"},
    },
    "required": []string{"name"},
}
err := db.SetSchema("users", schema)

GetSchema

Gets the JSON schema for a collection.

func (d *Database) GetSchema(collectionName string) (map[string]interface{}, error)

collectionName

string

required

Name of the collection

map[string]interface{}

JSON schema, or nil if no schema is set

error

Error if schema could not be retrieved

RemoveSchema

Removes the JSON schema from a collection.

func (d *Database) RemoveSchema(collectionName string) error

collectionName

string

required

Name of the collection

error

Error if schema could not be removed

Maintenance

Checkpoint

Performs a manual WAL checkpoint.

func (d *Database) Checkpoint() error

error

Error if checkpoint failed

Backup

Creates a backup of the database.

func (d *Database) Backup(destPath string) error

destPath

string

required

Destination path for the backup file

error

Error if backup failed

Example:

err := db.Backup("/backups/my_database_backup.db")

VerifyBackup

Verifies a backup file.

func VerifyBackup(backupPath string) (map[string]interface{}, error)

backupPath

string

required

Path to the backup file

map[string]interface{}

Backup verification information

error

Error if verification failed

GarbageCollect

Performs garbage collection and returns statistics.

func (d *Database) GarbageCollect() (map[string]interface{}, error)

map[string]interface{}

Garbage collection statistics

error

Error if garbage collection failed

Metrics

Returns database metrics.

func (d *Database) Metrics() (map[string]interface{}, error)

map[string]interface{}

Database metrics including reads, writes, cache hits, etc.

error

Error if metrics could not be retrieved

FrameCount

Returns the current WAL frame count.

func (d *Database) FrameCount() (int64, error)

int64

Number of WAL frames

error

Error if frame count could not be retrieved

Collection access

GetCollection

Gets a collection handle for non-transactional operations.

func (d *Database) GetCollection(name string) (*Collection, error)

name

string

required

Name of the collection

*Collection

Collection handle

error

Error if collection could not be obtained

Example:

coll, err := db.GetCollection("users")
if err != nil {
    log.Fatal(err)
}
defer coll.Free()

doc := map[string]interface{}{"name": "Bob", "age": 25}
id, err := coll.Insert(doc)

Rust API

Go API

Python API

JavaScript API

​Opening a database

​Open

​OpenWithOptions

​DefaultDatabaseOptions

​Database management

​Close

​BeginTransaction

​RunTransaction

​Configuration

​SetTransactionConfig

​GetTransactionConfig

​SetAutoCheckpointThreshold

​Database information

​GetPath

​IsReadOnly

​ListCollections

​CollectionStats

​DatabaseInfo

​MaxBulkOperations

​MaxDocumentSize

​MaxRequestBodySize

​Index management

​CreateIndex

​CreateCompoundIndex

​CreateTextIndex

​DropIndex

​ListIndexes

​Schema validation

​SetSchema

​GetSchema

​RemoveSchema

​Maintenance

​Checkpoint

​Backup

​VerifyBackup

​GarbageCollect

​Metrics

​FrameCount

​Collection access

​GetCollection

Build docs developers (and LLMs) love

Opening a database

Open

OpenWithOptions

DefaultDatabaseOptions

Database management

Close

BeginTransaction

RunTransaction

Configuration

SetTransactionConfig

GetTransactionConfig

SetAutoCheckpointThreshold

Database information

GetPath

IsReadOnly

ListCollections

CollectionStats

DatabaseInfo

MaxBulkOperations

MaxDocumentSize

MaxRequestBodySize

Index management

CreateIndex

CreateCompoundIndex

CreateTextIndex

DropIndex

ListIndexes

Schema validation

SetSchema

GetSchema

RemoveSchema

Maintenance

Checkpoint

Backup

VerifyBackup

GarbageCollect

Metrics

FrameCount

Collection access

GetCollection