db

func BaseXCreateDB ¶ added in v0.0.6

func BaseXCreateDB(dbName string) error

BaseXCreateDB creates a new database in BaseX with the specified name. It sends a batch of commands to the BaseX REST endpoint including database creation and info retrieval.

The function requires the following environment variables:

• BASEX_URL: The BaseX server URL (e.g., "http://localhost:8984")
• BASEX_USERNAME: Authentication username
• BASEX_PASSWORD: Authentication password

Parameters:

• dbName: The name of the database to create

Returns:

• error: Any error encountered during database creation

Example:

err := BaseXCreateDB("mydb")
if err != nil {
    log.Fatal(err)
}

func BaseXQuery ¶ added in v0.0.6

func BaseXQuery(db, doc, query string) ([]byte, error)

BaseXQuery executes an XQuery query against a specific document in a BaseX database. The query is sent as a POST request to the document endpoint with Content-Type "application/query+xml".

The function requires the following environment variables:

• BASEX_URL: The BaseX server URL
• BASEX_USERNAME: Authentication username
• BASEX_PASSWORD: Authentication password

Parameters:

• db: The database name
• doc: The document identifier (without .xml extension)
• query: The XQuery expression to execute

Returns:

• []byte: The query results as bytes
• error: Any error encountered during query execution

Example:

query := "//book[@year > 2020]"
results, err := BaseXQuery("mydb", "book1", query)
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(results))

func BaseXSaveDocument ¶ added in v0.0.6

func BaseXSaveDocument(dbName, docID string, xmlData []byte) error

BaseXSaveDocument saves an XML document to a BaseX database. The document is stored with the specified ID and ".xml" extension.

The function requires the following environment variables:

• BASEX_URL: The BaseX server URL
• BASEX_USERNAME: Authentication username
• BASEX_PASSWORD: Authentication password

Parameters:

• dbName: The name of the target database
• docID: The document identifier (without .xml extension)
• xmlData: The XML document content as bytes

Returns:

• error: Any error encountered during document save

Example:

xmlContent := []byte("<book><title>Go Programming</title></book>")
err := BaseXSaveDocument("mydb", "book1", xmlContent)

func BulkGet ¶ added in v0.0.7

func BulkGet[T any](c *CouchDBService, ids []string) (map[string]*T, map[string]error, error)

BulkGet retrieves multiple documents in a single database operation. This is more efficient than individual get operations for batch retrieval.

Type Parameter:

• T: Expected document type

Parameters:

• ids: Slice of document IDs to retrieve

Returns:

• map[string]*T: Map of document ID to document pointer
• map[string]error: Map of document ID to error (for failures)
• error: Request execution errors

Result Handling:

• Successfully retrieved documents appear in the first map
• Failed retrievals (not found, etc.) appear in the error map
• Request-level errors returned as error parameter

Example Usage:

ids := []string{"c1", "c2", "c3", "missing"}
docs, errors, err := BulkGet[Container](service, ids)
if err != nil {
    log.Printf("Bulk get failed: %v", err)
    return
}

fmt.Printf("Retrieved %d documents\n", len(docs))
for id, doc := range docs {
    fmt.Printf("  %s: %s (%s)\n", id, doc.Name, doc.Status)
}

if len(errors) > 0 {
    fmt.Println("Errors:")
    for id, err := range errors {
        fmt.Printf("  %s: %v\n", id, err)
    }
}

func BulkUpdate ¶ added in v0.0.7

func BulkUpdate[T any](c *CouchDBService, selector map[string]interface{}, updateFunc func(*T) error) (int, error)

BulkUpdate performs a bulk update operation on documents matching a selector. This applies an update function to all documents matching the criteria.

Type Parameter:

• T: Document type to update

Parameters:

• selector: Mango selector for finding documents to update
• updateFunc: Function to apply to each document

Returns:

• int: Number of documents successfully updated
• error: Query or update errors

Update Process:

1. Query documents matching selector
2. Apply updateFunc to each document
3. Bulk save all modified documents
4. Return count of successful updates

Example Usage:

// Stop all running containers in us-east
selector := map[string]interface{}{
    "status":   "running",
    "location": map[string]interface{}{"$regex": "^us-east"},
}

count, err := BulkUpdate[Container](service, selector, func(doc *Container) error {
    doc.Status = "stopped"
    return nil
})

if err != nil {
    log.Printf("Bulk update failed: %v", err)
    return
}
fmt.Printf("Stopped %d containers\n", count)

func CompactJSONLD ¶ added in v0.0.7

func CompactJSONLD(doc interface{}, context string) (map[string]interface{}, error)

CompactJSONLD performs basic JSON-LD compaction. This converts expanded JSON-LD to a more compact form using a context.

Parameters:

• doc: Expanded document to compact
• context: Context to use for compaction

Returns:

• map[string]interface{}: Compacted document
• error: Compaction errors

Compaction Process:

Converts expanded form back to compact:
- Replaces full IRIs with short terms
- Uses context for term mapping
- Simplifies value objects to simple values
- Converts arrays to single values where appropriate

Example Usage:

expanded := map[string]interface{}{
    "@type":                              []interface{}{"https://schema.org/SoftwareApplication"},
    "https://schema.org/name":            "nginx",
    "https://schema.org/applicationCategory": "web-server",
}

compacted, err := CompactJSONLD(expanded, "https://schema.org")
if err != nil {
    log.Printf("Compaction failed: %v", err)
    return
}

// compacted uses short terms:
// {"@context": "https://schema.org", "@type": "SoftwareApplication", "name": "nginx", ...}

func CouchDBAnimals ¶

func CouchDBAnimals(url string)

CouchDBAnimals demonstrates basic CouchDB operations with a simple animal document. This function serves as an example of fundamental CouchDB operations including database creation, document insertion, and revision management.

Operation Workflow:

1. Establishes connection to CouchDB server
2. Creates "animals" database if it doesn't exist
3. Inserts a sample document with predefined ID
4. Reports successful insertion with revision information

Parameters:

• url: CouchDB server URL (e.g., "http://admin:password@localhost:5984/")

Example Document:

The function creates a document with:
- _id: "cow" (document identifier)
- feet: 4 (integer field)
- greeting: "moo" (string field)

Error Handling:

• Connection failures cause panic for immediate feedback
• Database creation errors are logged but don't halt execution
• Document insertion failures cause panic to indicate critical errors

Educational Value:

This function demonstrates:
- Basic CouchDB connection establishment
- Database existence checking and creation
- Document insertion with explicit ID
- Revision handling and success confirmation

Example Usage:

CouchDBAnimals("http://admin:password@localhost:5984/")

Production Considerations:

This function is intended for demonstration and testing purposes.
Production code should implement proper error handling instead of panic.

func CouchDBDocGet ¶

func CouchDBDocGet(url, db, docId string) *kivik.Document

CouchDBDocGet retrieves a document from the specified database by document ID. This function provides direct document access with automatic database creation and returns a Kivik document handle for flexible data extraction.

Document Retrieval Process:

1. Establishes connection to CouchDB server
2. Creates database if it doesn't exist (for development convenience)
3. Retrieves document by ID from the specified database
4. Returns Kivik document handle for data access

Parameters:

• url: CouchDB server URL with authentication
• db: Database name containing the document
• docId: Document identifier to retrieve

Returns:

• *kivik.Document: Document handle for data extraction and metadata access

Document Handle Usage:

The returned kivik.Document provides methods for:
- ScanDoc(): Extract document data into Go structures
- Rev(): Access document revision information
- Err(): Check for retrieval errors

Error Handling:

• Connection failures cause panic for immediate feedback
• Database creation errors are logged but don't prevent retrieval
• Document not found errors are returned via the document's Err() method

Example Usage:

doc := CouchDBDocGet("http://admin:pass@localhost:5984/", "users", "user123")
if doc.Err() != nil {
    if kivik.HTTPStatus(doc.Err()) == 404 {
        fmt.Println("Document not found")
    } else {
        fmt.Printf("Error: %v\n", doc.Err())
    }
    return
}

var userData map[string]interface{}
if err := doc.ScanDoc(&userData); err != nil {
    fmt.Printf("Scan error: %v\n", err)
    return
}

fmt.Printf("Retrieved user: %v\n", userData)

Database Auto-Creation:

The function creates the database if it doesn't exist, which is convenient
for development but may not be desired in production environments where
database creation should be explicit and controlled.

Document Metadata:

The document handle provides access to CouchDB metadata including
revision information, which is essential for subsequent update operations.

func CouchDBDocNew ¶

func CouchDBDocNew(url, db string, doc interface{}) (string, string)

CouchDBDocNew creates a new document in the specified database with automatic ID generation. This function provides a simplified interface for document creation with automatic database setup and unique document ID assignment by CouchDB.

Document Creation Process:

1. Establishes connection to CouchDB server
2. Creates database if it doesn't exist
3. Inserts document with CouchDB-generated unique ID
4. Returns both document ID and initial revision

Parameters:

• url: CouchDB server URL with authentication
• db: Database name for document storage
• doc: Document data as interface{} (typically map[string]interface{})

Returns:

• string: Document ID assigned by CouchDB (UUID format)
• string: Initial revision ID for subsequent updates

Automatic ID Generation:

CouchDB generates UUIDs for document IDs when not explicitly provided,
ensuring uniqueness across the database and enabling distributed scenarios
without coordination overhead.

Database Auto-Creation:

The function automatically creates the target database if it doesn't exist,
enabling rapid development and deployment without manual database setup.

Error Handling:

• Connection failures cause panic for immediate feedback
• Database creation errors are logged but don't prevent document creation
• Document creation failures cause panic to indicate data operation issues

Example Usage:

docData := map[string]interface{}{
    "name": "John Doe",
    "email": "john@example.com",
    "created": time.Now(),
}
docId, revId := CouchDBDocNew("http://admin:pass@localhost:5984/", "users", docData)
fmt.Printf("Created document %s with revision %s\n", docId, revId)

Document Structure:

The doc parameter should be JSON-serializable data typically represented
as map[string]interface{} for maximum flexibility with CouchDB's schema-free nature.

Revision Management:

The returned revision ID is essential for subsequent document updates and
should be stored with application state for conflict resolution.

func CreateDatabaseFromURL ¶ added in v0.0.7

func CreateDatabaseFromURL(url, dbName string) error

CreateDatabaseFromURL creates a new CouchDB database with the given name. This is a standalone function that doesn't require a service instance.

Parameters:

• url: CouchDB server URL with authentication
• dbName: Name of the database to create

Returns:

• error: Database creation or connection errors

Error Handling:

• Returns error if database already exists
• Returns error if insufficient permissions
• Returns error on connection failures

Example Usage:

err := CreateDatabaseFromURL(
    "http://admin:password@localhost:5984",
    "my_new_database")
if err != nil {
    log.Printf("Failed to create database: %v", err)
}

func CreateLMDBRepository ¶ added in v0.0.3

func CreateLMDBRepository(serverURL, repositoryID, username, password string) error

CreateLMDBRepository creates a new LMDB-based RDF4J repository. This function creates a high-performance persistent repository using Lightning Memory-Mapped Database (LMDB) as the storage backend.

LMDB Storage Benefits:

• High-performance read and write operations
• Memory-mapped file access for efficiency
• ACID transaction support with durability
• Crash-safe persistence with automatic recovery
• Excellent scalability for large datasets

Repository Configuration:

Creates an LMDB repository with the following characteristics:
- File-based persistent storage
- Standard query evaluation mode
- Automatic indexing and optimization
- Full SPARQL 1.1 support

Parameters:

• serverURL: Base URL of the RDF4J server
• repositoryID: Unique identifier for the new repository
• username: Username for HTTP Basic Authentication
• password: Password for HTTP Basic Authentication

Returns:

• error: Repository creation, authentication, or configuration errors

LMDB Characteristics:

• Memory-mapped files for efficient access
• Copy-on-write semantics for consistent reads
• No write-ahead logging overhead
• Automatic file growth and management
• Operating system page cache integration

Performance Profile:

• Excellent read performance through memory mapping
• Good write performance with batch operations
• Efficient range queries and indexing
• Low memory overhead for large datasets
• Scales well with available system memory

Success Conditions:

Repository creation is successful when the server returns:
- HTTP 200 OK (creation successful)
- HTTP 201 Created (alternative success response)
- HTTP 204 No Content (creation without response body)

Error Conditions:

• Repository ID already exists on the server
• Authentication failures or insufficient permissions
• Invalid LMDB configuration parameters
• Insufficient disk space for database files
• File system permission errors
• Server-side LMDB initialization failures

Example Usage:

err := CreateLMDBRepository(
    "http://localhost:8080/rdf4j-server",
    "production-lmdb-repo",
    "admin",
    "password",
)
if err != nil {
    log.Fatal("LMDB repository creation failed:", err)
}

log.Println("LMDB repository created successfully")

Use Cases:

LMDB repositories are ideal for:
- Production systems requiring persistence
- Large-scale data processing and analytics
- High-throughput read-heavy workloads
- Systems requiring fast startup times
- Applications with strict consistency requirements

Configuration Details:

The function uses RDF4J's modern configuration vocabulary
(tag:rdf4j.org,2023:config/) rather than legacy OpenRDF namespaces
for future compatibility and enhanced functionality.

Storage Considerations:

• Database files created in RDF4J server data directory
• Automatic file size management and growth
• Backup requires file system level copying
• Consider disk I/O performance for optimal results

func CreateRepository ¶ added in v0.0.3

func CreateRepository(serverURL, repositoryID, username, password string) error

CreateRepository creates a new in-memory RDF4J repository. This function dynamically creates a repository configuration using Turtle syntax and deploys it to the RDF4J server for immediate use.

Repository Configuration:

Creates an in-memory repository with the following characteristics:
- Memory-based storage (non-persistent)
- Fast read/write operations
- Automatic cleanup on server restart
- Suitable for temporary data processing and testing

Parameters:

• serverURL: Base URL of the RDF4J server
• repositoryID: Unique identifier for the new repository
• username: Username for HTTP Basic Authentication
• password: Password for HTTP Basic Authentication

Returns:

• error: Repository creation, authentication, or configuration errors

Configuration Format:

The function generates a Turtle configuration that defines:
- Repository type as SailRepository with MemoryStore
- Repository ID and human-readable label
- Storage backend configuration and parameters

Memory Store Characteristics:

• All data stored in server memory (RAM)
• No persistence across server restarts
• Excellent performance for read/write operations
• Limited by available server memory
• Immediate data loss on server failure

Success Conditions:

Repository creation is successful when the server returns:
- HTTP 204 No Content (creation successful)
- HTTP 200 OK (alternative success response)

Error Conditions:

• Repository ID already exists on the server
• Authentication failures or insufficient permissions
• Invalid repository configuration syntax
• Server-side errors during repository initialization
• Network connectivity issues

Example Usage:

err := CreateRepository(
    "http://localhost:8080/rdf4j-server",
    "test-memory-repo",
    "admin",
    "password",
)
if err != nil {
    log.Fatal("Repository creation failed:", err)
}

log.Println("Memory repository created successfully")

Use Cases:

Memory repositories are ideal for:
- Unit testing and integration testing
- Temporary data processing and analysis
- Development and prototyping
- Cache-like storage for computed results
- Session-based data storage

Repository Lifecycle:

• Created empty and ready for data import
• Destroyed automatically on server restart
• Can be explicitly deleted using DeleteRepository
• Performance degrades as data size approaches memory limits

func DatabaseExistsFromURL ¶ added in v0.0.7

func DatabaseExistsFromURL(url, dbName string) (bool, error)

DatabaseExistsFromURL checks if a database exists. This is a standalone function that doesn't require a service instance.

Parameters:

• url: CouchDB server URL with authentication
• dbName: Name of the database to check

Returns:

• bool: true if database exists, false otherwise
• error: Connection or query errors

Example Usage:

exists, err := DatabaseExistsFromURL(
    "http://admin:password@localhost:5984",
    "my_database")
if err != nil {
    log.Printf("Error checking database: %v", err)
    return
}

if exists {
    fmt.Println("Database exists")
} else {
    fmt.Println("Database does not exist")
}

func DeleteDatabaseFromURL ¶ added in v0.0.7

func DeleteDatabaseFromURL(url, dbName string) error

DeleteDatabaseFromURL deletes a CouchDB database. This permanently removes the database and all its documents.

Parameters:

• url: CouchDB server URL with authentication
• dbName: Name of the database to delete

Returns:

• error: Database deletion or connection errors

WARNING:

This operation is irreversible and deletes all data in the database.
Use with extreme caution in production environments.

Example Usage:

err := DeleteDatabaseFromURL(
    "http://admin:password@localhost:5984",
    "old_database")
if err != nil {
    log.Printf("Failed to delete database: %v", err)
}

func DeleteGenericDocument ¶ added in v0.0.7

func DeleteGenericDocument(c *CouchDBService, id, rev string) error

DeleteGenericDocument deletes a generic document from CouchDB. Requires both document ID and current revision for conflict detection.

Parameters:

• c: CouchDBService instance
• id: Document identifier to delete
• rev: Current document revision (for MVCC conflict detection)

Returns:

• error: Deletion failures or conflicts

MVCC Conflict Handling:

If revision doesn't match current document:
- Returns CouchDBError with status 409
- Application should retrieve latest revision and retry

Example Usage:

err := DeleteGenericDocument(service, "container-123", "2-abc123")
if err != nil {
    if couchErr, ok := err.(*CouchDBError); ok && couchErr.IsConflict() {
        fmt.Println("Conflict - document was modified")
        // Retrieve latest and retry
        return
    }
    log.Printf("Delete failed: %v", err)
}

func DeleteRepository ¶ added in v0.0.2

func DeleteRepository(serverURL, repositoryID, username, password string) error

DeleteRepository removes a repository and all its data from an RDF4J server. This function permanently deletes a repository configuration and all stored RDF data, providing a clean removal mechanism for repository management.

Deletion Process:

1. Sends HTTP DELETE request to the repository endpoint
2. Authenticates using provided credentials
3. Verifies successful deletion via HTTP status codes
4. Returns error information for failed deletions

Parameters:

• serverURL: Base URL of the RDF4J server
• repositoryID: Identifier of the repository to delete
• username: Username for HTTP Basic Authentication
• password: Password for HTTP Basic Authentication

Returns:

• error: Authentication, permission, or deletion errors

Data Loss Warning:

This operation is irreversible and will permanently destroy:
- All RDF triples stored in the repository
- Repository configuration and metadata
- Any custom indexes or optimization data
- Transaction logs and backup information

Success Conditions:

The function considers deletion successful when the server returns:
- HTTP 204 No Content (standard success response)
- HTTP 200 OK (alternative success response)

Security Considerations:

• Requires appropriate authentication credentials
• User must have repository deletion permissions
• Consider implementing confirmation mechanisms in applications
• Audit logging recommended for deletion operations

Error Conditions:

• Repository not found (may already be deleted)
• Authentication failures or insufficient permissions
• Server-side errors during deletion process
• Network connectivity issues
• Repository currently in use by other operations

Example Usage:

err := DeleteRepository(
    "http://localhost:8080/rdf4j-server",
    "temporary-repository",
    "admin",
    "password",
)
if err != nil {
    log.Fatal("Deletion failed:", err)
}

log.Println("Repository deleted successfully")

Repository Management:

Use this function as part of:
- Automated testing cleanup procedures
- Repository lifecycle management
- Data migration and reorganization
- Administrative maintenance tasks

Best Practices:

• Always backup important data before deletion
• Verify repository ID to prevent accidental deletions
• Implement proper access controls and audit logs
• Consider soft deletion patterns for critical systems

func DownloadAllDocuments ¶ added in v0.0.3

func DownloadAllDocuments(url, db, outputDir string) error

DownloadAllDocuments exports all documents from a CouchDB database to the filesystem. This function provides comprehensive database backup and export capabilities with organized file structure and progress monitoring for large datasets.

Export Process:

1. Connects to CouchDB server with provided credentials
2. Creates organized directory structure for exported data
3. Iterates through all documents in the specified database
4. Saves each document as individual JSON file
5. Provides progress feedback for large datasets

Parameters:

• url: CouchDB server URL with authentication
• db: Database name to export documents from
• outputDir: Base directory for exported document files

Returns:

• error: Connection, permission, or file system errors

File Organization:

Creates directory structure: outputDir/database/document_id.json
- Each document saved as separate JSON file
- Document IDs sanitized for filesystem compatibility
- Pretty-printed JSON for human readability
- Preserves all document fields and metadata

Progress Monitoring:

• Reports progress every 100 documents for large datasets
• Displays total document count upon completion
• Provides feedback for long-running export operations
• Logs errors for individual document processing failures

Error Handling:

• Individual document errors don't halt the entire export
• Connection errors are reported and terminate the operation
• File system errors are logged with appropriate context
• Design document (_design/) are automatically skipped

Example Usage:

err := DownloadAllDocuments(
    "http://admin:password@localhost:5984",
    "flow_processes",
    "/backup/couchdb_export")
if err != nil {
    log.Printf("Export failed: %v", err)
    return
}

fmt.Println("Database export completed successfully")

File Naming:

Document IDs are sanitized for filesystem compatibility:
- Invalid characters replaced with underscores
- Length limited to prevent filesystem issues
- Maintains uniqueness while ensuring compatibility

Use Cases:

• Database backup and disaster recovery
• Data migration between CouchDB instances
• Offline analysis and data processing
• Compliance and audit data archival
• Development data seeding and testing

Performance Considerations:

• Memory usage remains constant regardless of dataset size
• Network bandwidth depends on document sizes and count
• Disk I/O performance affects export speed
• Large datasets benefit from progress monitoring

func DragonflyDBGetKey ¶ added in v0.0.6

func DragonflyDBGetKey(key string) ([]byte, error)

DragonflyDBGetKey retrieves a value from DragonflyDB by key. DragonflyDB is compatible with Redis protocol, so this function uses the go-redis client. The function prints the key and connection status for debugging purposes.

The function requires the following environment variables:

• DRAGONFLYDB_HOST: DragonflyDB server address (e.g., "localhost:6379")
• DRAGONFLYDB_PASSWORD: Authentication password (use empty string if no password)

Parameters:

• key: The key to retrieve

Returns:

• []byte: The value stored at the key
• error: Any error encountered (including redis.Nil if key doesn't exist)

Example:

data, err := DragonflyDBGetKey("user:1234")
if err == redis.Nil {
    fmt.Println("Key does not exist")
} else if err != nil {
    log.Fatal(err)
} else {
    fmt.Printf("Value: %s\n", data)
}

func DragonflyDBGetKeyWithDialer ¶ added in v0.0.13

func DragonflyDBGetKeyWithDialer(key string, dialer func(ctx context.Context, network, addr string) (net.Conn, error)) ([]byte, error)

DragonflyDBGetKeyWithDialer retrieves a value from DragonflyDB by key using a custom dialer. This function supports Ziti zero-trust networking by accepting a custom dialer for connection setup. DragonflyDB is compatible with Redis protocol, so this function uses the go-redis client.

The function requires the following environment variables:

• DRAGONFLYDB_HOST: DragonflyDB server address (e.g., "localhost:6379" or Ziti service name)
• DRAGONFLYDB_PASSWORD: Authentication password (use empty string if no password)

Parameters:

• key: The key to retrieve
• dialer: Custom dialer function for creating connections (e.g., Ziti dialer)

Returns:

• []byte: The value stored at the key
• error: Any error encountered (including redis.Nil if key doesn't exist)

Example with Ziti:

import (
    "eve.evalgo.org/db"
    "eve.evalgo.org/network"
    "github.com/openziti/sdk-golang/ziti"
)

// Setup Ziti context
cfg, _ := ziti.NewConfigFromFile("/path/to/identity.json")
zitiCtx, _ := ziti.NewContext(cfg)

// Create Ziti dialer
dialer := func(ctx context.Context, network, addr string) (net.Conn, error) {
    return zitiCtx.Dial("dragonflydb-service")
}

// Get key through Ziti
data, err := db.DragonflyDBGetKeyWithDialer("user:1234", dialer)
if err != nil {
    log.Fatal(err)
}

func DragonflyDBSaveKeyValue ¶ added in v0.0.6

func DragonflyDBSaveKeyValue(key string, value []byte) error

DragonflyDBSaveKeyValue stores a key-value pair in DragonflyDB. DragonflyDB is compatible with Redis protocol, so this function uses the go-redis client. The value is stored with no expiration (TTL = 0).

The function requires the following environment variables:

• DRAGONFLYDB_HOST: DragonflyDB server address (e.g., "localhost:6379")
• DRAGONFLYDB_PASSWORD: Authentication password (use empty string if no password)

Parameters:

• key: The key under which to store the value
• value: The value to store as bytes

Returns:

• error: Any error encountered during storage operation

Example:

data := []byte("user profile data")
err := DragonflyDBSaveKeyValue("user:1234", data)
if err != nil {
    log.Fatal(err)
}

func DragonflyDBSaveKeyValueWithDialer ¶ added in v0.0.13

func DragonflyDBSaveKeyValueWithDialer(key string, value []byte, dialer func(ctx context.Context, network, addr string) (net.Conn, error)) error

DragonflyDBSaveKeyValueWithDialer stores a key-value pair in DragonflyDB using a custom dialer. This function supports Ziti zero-trust networking by accepting a custom dialer for connection setup. DragonflyDB is compatible with Redis protocol, so this function uses the go-redis client. The value is stored with no expiration (TTL = 0).

The function requires the following environment variables:

• DRAGONFLYDB_HOST: DragonflyDB server address (e.g., "localhost:6379" or Ziti service name)
• DRAGONFLYDB_PASSWORD: Authentication password (use empty string if no password)

Parameters:

• key: The key under which to store the value
• value: The value to store as bytes
• dialer: Custom dialer function for creating connections (e.g., Ziti dialer)

Returns:

• error: Any error encountered during storage operation

Example with Ziti:

import (
    "eve.evalgo.org/db"
    "eve.evalgo.org/network"
    "github.com/openziti/sdk-golang/ziti"
)

// Setup Ziti context
cfg, _ := ziti.NewConfigFromFile("/path/to/identity.json")
zitiCtx, _ := ziti.NewContext(cfg)

// Create Ziti dialer
dialer := func(ctx context.Context, network, addr string) (net.Conn, error) {
    return zitiCtx.Dial("dragonflydb-service")
}

// Save key through Ziti
data := []byte("user profile data")
err := db.DragonflyDBSaveKeyValueWithDialer("user:1234", data, dialer)
if err != nil {
    log.Fatal(err)
}

func ExpandJSONLD ¶ added in v0.0.7

func ExpandJSONLD(doc interface{}) (map[string]interface{}, error)

ExpandJSONLD performs basic JSON-LD expansion. This is a simplified implementation that handles common expansion patterns without requiring a full JSON-LD processor.

Parameters:

• doc: Document to expand

Returns:

• map[string]interface{}: Expanded document
• error: Expansion errors

Expansion Process:

JSON-LD expansion converts compact representation to explicit form:
- Resolves all terms to full IRIs
- Converts values to explicit object format
- Expands @type to @type array
- Converts single values to arrays

Limitations:

This is a basic implementation:
- Does not fetch remote contexts
- Limited to simple context resolution
- For full expansion, use a dedicated JSON-LD library

Example Usage:

doc := map[string]interface{}{
    "@context": "https://schema.org",
    "@type":    "SoftwareApplication",
    "name":     "nginx",
}

expanded, err := ExpandJSONLD(doc)
if err != nil {
    log.Printf("Expansion failed: %v", err)
    return
}

// expanded now has full IRIs
fmt.Printf("Expanded: %+v\n", expanded)

func ExportRDFXml ¶

func ExportRDFXml(serverURL, repositoryID, username, password, outputFilePath, contentType string) error

ExportRDFXml exports all RDF data from a repository to a file. This function retrieves complete repository contents and saves them in the specified RDF serialization format for backup, transfer, or analysis.

Export Process:

1. Connects to the repository statements endpoint
2. Requests data in the specified serialization format
3. Downloads all triples from the repository
4. Writes the data to the specified output file

Parameters:

• serverURL: Base URL of the RDF4J server
• repositoryID: Source repository identifier
• username: Username for HTTP Basic Authentication
• password: Password for HTTP Basic Authentication
• outputFilePath: File system path for the exported data
• contentType: MIME type for the desired output format

Returns:

• error: Network, authentication, or file writing errors

Supported Export Formats:

• "application/rdf+xml": Standard RDF/XML serialization
• "text/turtle": Turtle format (human-readable)
• "application/ld+json": JSON-LD format (web-friendly)
• "application/n-triples": N-Triples format (streaming-friendly)
• "text/plain": N-Triples in plain text format

Data Scope:

The export includes all triples stored in the repository across
all named graphs, providing a complete dump of repository contents.
Named graph information is preserved in formats that support it.

File Handling:

The exported file is written with standard permissions (0644),
making it readable by the owner and group while preventing
unauthorized modifications.

Error Conditions:

• Repository not found or access denied
• Network connectivity issues during download
• Authentication failures
• Insufficient disk space for export file
• File system permission errors
• Server-side errors during data serialization

Example Usage:

err := ExportRDFXml(
    "http://localhost:8080/rdf4j-server",
    "my-repository",
    "admin",
    "password",
    "/backup/repository-export.rdf",
    "application/rdf+xml",
)
if err != nil {
    log.Fatal("Export failed:", err)
}

Backup and Recovery:

Exported files can be used for:
- Repository backup and disaster recovery
- Data migration between different RDF stores
- Data analysis and processing with external tools
- Version control and change tracking

Performance Considerations:

• Large repositories may take significant time to export
• Memory usage depends on repository size and export format
• Network bandwidth affects download time
• Consider compression for large export files

func ExtractJSONLDType ¶ added in v0.0.7

func ExtractJSONLDType(doc interface{}) (string, error)

ExtractJSONLDType extracts the @type value from a JSON-LD document. This is a convenience function for type checking.

Parameters:

• doc: JSON-LD document

Returns:

• string: The @type value
• error: Error if @type not found

Example Usage:

docType, err := ExtractJSONLDType(doc)
if err != nil {
    log.Printf("No type found: %v", err)
    return
}

switch docType {
case "SoftwareApplication":
    // Handle container
case "ComputerServer":
    // Handle host
}

func FindTyped ¶ added in v0.0.7

func FindTyped[T any](c *CouchDBService, query MangoQuery) ([]T, error)

FindTyped executes a Mango query with typed results using generics. This provides compile-time type safety for query results.

Type Parameter:

• T: Expected document type

Parameters:

• query: MangoQuery structure with filtering and options

Returns:

• []T: Slice of documents matching type T
• error: Query execution or parsing errors

Example Usage:

type Container struct {
    ID       string `json:"_id"`
    Name     string `json:"name"`
    Status   string `json:"status"`
    HostedOn string `json:"hostedOn"`
}

query := MangoQuery{
    Selector: map[string]interface{}{
        "status": "running",
        "@type": "SoftwareApplication",
    },
    Limit: 50,
}

containers, err := FindTyped[Container](service, query)
if err != nil {
    log.Printf("Query failed: %v", err)
    return
}

for _, container := range containers {
    fmt.Printf("Container %s is %s\n", container.Name, container.Status)
}

func GetAllDocuments ¶ added in v0.0.7

func GetAllDocuments[T any](c *CouchDBService, docType string) ([]T, error)

GetAllDocuments retrieves all documents from the database with optional type filtering. This function uses Go generics to return strongly-typed document results.

Type Parameter:

• T: Expected document type (will skip documents that don't match)

Parameters:

• docType: Optional document type filter (e.g., "@type" field value) Pass empty string to retrieve all documents

Returns:

• []T: Slice of documents of type T
• error: Query execution or parsing errors

Type Filtering:

If docType is provided, only returns documents with matching "@type" field.
Documents without "@type" field or with different type are skipped.

Performance Considerations:

• Retrieves all documents using _all_docs view
• Memory usage scales with database size
• Consider pagination for very large databases

Example Usage:

// Get all documents of any type
allDocs, err := GetAllDocuments[map[string]interface{}](service, "")

// Get only Container documents
containers, err := GetAllDocuments[Container](service, "SoftwareApplication")
for _, container := range containers {
    fmt.Printf("Container: %s (%s)\n", container.Name, container.Status)
}

func GetDocument ¶ added in v0.0.7

func GetDocument[T any](c *CouchDBService, id string) (*T, error)

GetDocument retrieves a generic document from CouchDB by ID. This function uses Go generics to return strongly-typed document results.

Type Parameter:

• T: Expected document type (must match stored document structure)

Parameters:

• id: Document identifier to retrieve

Returns:

• *T: Pointer to the retrieved document of type T
• error: Document not found, access, or parsing errors

Error Handling:

• Returns CouchDBError for HTTP errors (404, 401, etc.)
• Returns parsing error if document structure doesn't match type T

Example Usage:

type Container struct {
    ID       string `json:"_id"`
    Rev      string `json:"_rev"`
    Name     string `json:"name"`
    Status   string `json:"status"`
}

container, err := GetDocument[Container](service, "container-123")
if err != nil {
    if couchErr, ok := err.(*CouchDBError); ok && couchErr.IsNotFound() {
        fmt.Println("Container not found")
        return
    }
    log.Printf("Error: %v", err)
    return
}
fmt.Printf("Container %s is %s\n", container.Name, container.Status)

func GetDocumentsByType ¶ added in v0.0.7

func GetDocumentsByType[T any](c *CouchDBService, docType string) ([]T, error)

GetDocumentsByType retrieves documents filtered by @type field using Mango query. This is more efficient than GetAllDocuments for type-filtered queries on large databases.

Type Parameter:

• T: Expected document type

Parameters:

• docType: Value of the "@type" field to filter by

Returns:

• []T: Slice of matching documents
• error: Query execution or parsing errors

Index Recommendation:

For optimal performance, create an index on the @type field:
index := Index{Name: "type-index", Fields: []string{"@type"}, Type: "json"}
service.CreateIndex(index)

Example Usage:

containers, err := GetDocumentsByType[Container](service, "SoftwareApplication")
if err != nil {
    log.Printf("Query failed: %v", err)
    return
}

for _, container := range containers {
    fmt.Printf("Found container: %s\n", container.Name)
}

func GraphDBDeleteGraph ¶

func GraphDBDeleteGraph(URL, user, pass, repo, graph string) error

GraphDBDeleteGraph removes a specific named graph from a repository using SPARQL UPDATE. This function executes a DROP GRAPH operation to permanently delete all triples in the specified named graph while preserving other graphs in the repository.

Named Graph Deletion:

Uses SPARQL UPDATE "DROP GRAPH" command to:
- Remove all triples from the specified named graph
- Preserve other named graphs and default graph content
- Execute atomic deletion operation
- Update graph metadata and indexes

Parameters:

• URL: Base URL of the GraphDB server
• user: Username for HTTP Basic Authentication
• pass: Password for HTTP Basic Authentication
• repo: Repository identifier containing the graph
• graph: Named graph URI to delete

Returns:

• error: Authentication, execution, or server errors

SPARQL Operation:

Constructs and executes: DROP GRAPH <graph-uri>
This standard SPARQL UPDATE operation removes all triples where
the named graph matches the specified URI.

Graph URI Format:

The graph parameter should be a valid IRI (Internationalized Resource
Identifier) that uniquely identifies the named graph within the repository.

Success Conditions:

Graph deletion is successful when the server returns:
- HTTP 204 No Content status code
- Empty response body indicating successful execution

Error Conditions:

• Named graph does not exist (may be silent success)
• Invalid graph URI format
• Authentication failures or insufficient permissions
• Repository not found or inaccessible
• SPARQL syntax or execution errors

Data Impact:

• Only affects triples in the specified named graph
• Default graph and other named graphs remain unchanged
• Graph metadata and context information is removed
• Indexes are updated to reflect graph deletion

Example Usage:

err := GraphDBDeleteGraph(
    "http://localhost:7200", "admin", "password",
    "knowledge-base", "http://example.org/graph/outdated-data")
if err != nil {
    log.Fatal("Graph deletion failed:", err)
}
log.Println("Named graph deleted successfully")

Safety Considerations:

• Verify graph URI to prevent accidental deletions
• Backup important graph data before deletion
• Check for applications depending on the graph
• Consider graph dependencies and relationships

func GraphDBDeleteRepository ¶ added in v0.0.3

func GraphDBDeleteRepository(URL, user, pass, repo string) error

GraphDBDeleteRepository removes a repository and all its data from GraphDB server. This function permanently deletes a repository configuration and all stored RDF data, providing a clean removal mechanism for repository lifecycle management.

Repository Deletion:

Sends a DELETE request to GraphDB's REST repository endpoint to:
- Remove repository configuration and metadata
- Delete all stored RDF triples and named graphs
- Clean up associated indexes and cached data
- Free storage space and system resources

Parameters:

• URL: Base URL of the GraphDB server
• user: Username for HTTP Basic Authentication
• pass: Password for HTTP Basic Authentication
• repo: Repository identifier to delete

Returns:

• error: Authentication, permission, or deletion errors

Data Loss Warning:

This operation is irreversible and will permanently destroy:
- All RDF triples and named graphs in the repository
- Repository configuration and settings
- Custom indexes and optimization data
- Query result caches and temporary data

Success Conditions:

Repository deletion is successful when the server returns:
- HTTP 200 OK (deletion completed successfully)
- HTTP 204 No Content (deletion completed without response body)

Authentication Requirements:

• Valid credentials with repository deletion permissions
• Administrative access to the GraphDB server
• Appropriate role-based access controls

Error Conditions:

• Repository not found (may already be deleted)
• Authentication failures or insufficient permissions
• Repository currently in use by active connections
• Server-side errors during deletion process
• Network connectivity issues

Example Usage:

err := GraphDBDeleteRepository("http://localhost:7200", "admin", "password", "test-repository")
if err != nil {
    log.Fatal("Repository deletion failed:", err)
}
log.Println("Repository deleted successfully")

Safety Recommendations:

• Always backup important repositories before deletion
• Verify repository name to prevent accidental deletions
• Check for dependent applications or integrations
• Implement proper access controls and audit logging
• Consider soft deletion patterns for critical systems

Administrative Use:

This function is typically used for:
- Development environment cleanup
- Automated testing teardown procedures
- Repository lifecycle management
- Data migration and reorganization

func GraphDBExportGraphRdf ¶

func GraphDBExportGraphRdf(url, user, pass, repo, graph, exportFile string) error

GraphDBExportGraphRdf exports a specific named graph from a repository to an RDF/XML file. This function retrieves all triples from a named graph and saves them in RDF/XML format for backup, analysis, or data transfer purposes.

Named Graph Export:

Downloads all RDF triples from the specified named graph using
GraphDB's RDF graphs service endpoint, providing:
- Graph-specific data extraction
- Complete triple preservation with context
- Standard RDF/XML serialization format
- File-based output for external processing

Parameters:

• url: Base URL of the GraphDB server
• user: Username for HTTP Basic Authentication
• pass: Password for HTTP Basic Authentication
• repo: Repository identifier containing the graph
• graph: Named graph URI to export
• exportFile: Output filename for the exported RDF/XML data

Returns:

• error: File creation, network, or server errors

Export Process:

1. Constructs request URL with graph parameter
2. Requests RDF/XML representation of the named graph
3. Downloads all triples from the specified graph context
4. Writes RDF/XML data to the specified output file

RDF/XML Output:

The exported file contains standard RDF/XML with:
- All triples from the named graph
- Proper namespace declarations
- XML structure following RDF/XML specification
- UTF-8 encoding for international character support

Graph Context Preservation:

While the exported RDF/XML doesn't explicitly contain graph context
information, all triples that belonged to the named graph are
preserved for reimport into the same or different graph contexts.

Success Conditions:

Export is successful when the server returns:
- HTTP 200 OK status code
- Valid RDF/XML content in response body
- Successful file creation and writing

Error Conditions:

• Named graph does not exist or is empty
• Authentication failures or insufficient permissions
• File creation or writing permissions errors
• Network connectivity issues during download
• Server errors during RDF serialization

Example Usage:

err := GraphDBExportGraphRdf(
    "http://localhost:7200", "admin", "password",
    "knowledge-base", "http://example.org/graph/publications",
    "/backup/publications-export.rdf")
if err != nil {
    log.Fatal("Graph export failed:", err)
}
log.Println("Named graph exported successfully")

Use Cases:

• Graph-specific backup and archival
• Data migration between repositories
• Selective data analysis and processing
• Graph-based data distribution and sharing
• Integration with external RDF tools and systems

func GraphDBImportGraphRdf ¶

func GraphDBImportGraphRdf(url, user, pass, repo, graph, restoreFile string) error

GraphDBImportGraphRdf imports RDF data into a specific named graph within a repository. This function enables graph-level data management by importing RDF/XML content into designated named graphs for organized data storage and querying.

Named Graph Import:

Loads RDF data into a specific named graph context within the repository,
enabling:
- Data organization by source, domain, or purpose
- Graph-level access control and permissions
- Selective querying and data management
- Logical separation of different datasets

Parameters:

• url: Base URL of the GraphDB server
• user: Username for HTTP Basic Authentication
• pass: Password for HTTP Basic Authentication
• repo: Repository identifier for data import
• graph: Named graph URI for data context
• restoreFile: Path to RDF/XML file containing data

Returns:

• error: File reading, upload, or server errors

Graph Context Management:

The graph parameter specifies the named graph URI where data will be
stored, enabling graph-aware operations and queries. The URI typically
follows standard IRI format for global uniqueness.

RDF/XML Format:

The function expects RDF/XML formatted data files containing:
- Valid RDF triples with subject, predicate, object
- Namespace declarations for vocabulary terms
- Proper XML structure and RDF syntax
- Compatible encoding (UTF-8 recommended)

Import Process:

1. Reads RDF/XML file from filesystem
2. Constructs URL with graph parameter
3. Uploads data via HTTP PUT to RDF graphs service
4. Validates successful import response

Success Conditions:

Data import is successful when the server returns:
- HTTP 204 No Content status code
- Empty response body indicating successful processing

Error Conditions:

• RDF file not found or unreadable
• Invalid RDF/XML syntax or structure
• Repository does not exist
• Graph URI format errors
• Authentication failures or insufficient permissions

Example Usage:

err := GraphDBImportGraphRdf(
    "http://localhost:7200", "admin", "password",
    "knowledge-base", "http://example.org/graph/publications",
    "/data/publications.rdf")
if err != nil {
    log.Fatal("Graph import failed:", err)
}

Graph Organization Strategies:

• Domain-based: separate graphs for different knowledge domains
• Source-based: separate graphs for different data sources
• Time-based: separate graphs for different time periods
• Access-based: separate graphs for different security levels

func GraphDBRepositoryBrf ¶

func GraphDBRepositoryBrf(url string, user string, pass string, repo string) (string, error)

GraphDBRepositoryBrf exports all RDF data from a repository in Binary RDF format. This function downloads the complete repository content in GraphDB's efficient Binary RDF (BRF) format for high-performance backup and data transfer operations.

Binary RDF Format:

BRF is GraphDB's proprietary binary serialization that provides:
- Compact data representation with reduced file sizes
- Fast serialization and deserialization performance
- Preservation of all RDF data including named graphs
- Optimized format for large dataset operations

Parameters:

• url: Base URL of the GraphDB server
• user: Username for HTTP Basic Authentication
• pass: Password for HTTP Basic Authentication
• repo: Repository identifier to export data from

Returns:

• string: Filename of the exported data file (repo.brf)

Export Process:

1. Connects to the repository statements endpoint
2. Requests data in Binary RDF format
3. Downloads all triples and named graphs
4. Saves to a .brf file for future restoration

File Output:

Creates a file named "{repo}.brf" containing all repository data
in binary format, suitable for:
- High-performance backup operations
- Data migration between GraphDB instances
- Bulk data transfer for analytics
- Repository cloning and replication

Performance Benefits:

• Significantly smaller file sizes compared to RDF/XML or Turtle
• Faster download and upload operations
• Reduced network bandwidth usage
• Optimized for GraphDB's internal data structures

Error Handling:

• Network errors are logged and may cause termination
• HTTP errors result in fatal logging and program exit
• File creation errors are logged as informational

Example Usage:

backupFile := GraphDBRepositoryBrf("http://localhost:7200", "admin", "password", "production-data")
fmt.Printf("Repository backup saved to: %s\n", backupFile)

Restore Compatibility:

The exported BRF file can be restored using GraphDBRestoreBrf()
function to recreate the repository with identical data content.

func GraphDBRepositoryConf ¶

func GraphDBRepositoryConf(url string, user string, pass string, repo string) (string, error)

GraphDBRepositoryConf downloads the configuration of a GraphDB repository in Turtle format. This function retrieves the complete repository configuration for backup, analysis, or recreation purposes in a human-readable Turtle serialization.

Configuration Export:

Downloads the repository configuration from GraphDB's REST API endpoint,
saving it as a Turtle (.ttl) file that contains:
- Repository type and storage backend settings
- Index configurations and performance tuning
- Security and access control settings
- Plugin and extension configurations

Parameters:

• url: Base URL of the GraphDB server
• user: Username for HTTP Basic Authentication
• pass: Password for HTTP Basic Authentication
• repo: Repository identifier to download configuration for

Returns:

• string: Filename of the downloaded configuration file (repo.ttl)

File Output:

Creates a file named "{repo}.ttl" in the current directory containing
the complete repository configuration in Turtle format, suitable for:
- Repository backup and disaster recovery
- Configuration analysis and documentation
- Repository recreation on different servers
- Version control of repository settings

Error Handling:

• Network errors are logged via eve.Logger.Error
• HTTP errors cause fatal logging and program termination
• File creation errors are logged but don't terminate execution

Example Usage:

configFile := GraphDBRepositoryConf("http://localhost:7200", "admin", "password", "my-repo")
fmt.Printf("Repository configuration saved to: %s\n", configFile)

Turtle Format Benefits:

• Human-readable RDF configuration
• Easy editing and version control
• Standard RDF serialization format
• Compatible with RDF tools and editors

func GraphDBRestoreBrf ¶

func GraphDBRestoreBrf(url string, user string, pass string, restoreFile string) error

GraphDBRestoreBrf restores RDF data from a Binary RDF file into a repository. This function uploads BRF data to recreate repository content with high performance and complete data fidelity preservation.

Binary RDF Restoration:

Uploads Binary RDF data directly to the repository statements endpoint,
restoring all triples and named graphs with:
- High-performance data upload using binary format
- Complete preservation of graph structure and content
- Efficient processing of large datasets
- Atomic restoration operation

Parameters:

• url: Base URL of the GraphDB server
• user: Username for HTTP Basic Authentication
• pass: Password for HTTP Basic Authentication
• restoreFile: Path to the Binary RDF file (.brf)

Returns:

• error: File reading, upload, or server errors

Repository Inference:

The target repository name is automatically inferred from the BRF
filename (excluding the .brf extension), enabling automated
restoration workflows with consistent naming patterns.

Data Upload Process:

1. Reads the complete BRF file into memory
2. Extracts repository name from filename
3. Uploads data to the repository statements endpoint
4. Validates successful data import response

Performance Characteristics:

• Binary format provides fastest upload speeds
• Single HTTP request for complete data transfer
• Minimal CPU overhead during upload
• Efficient memory usage for large datasets

Success Conditions:

Data restoration is successful when the server returns:
- HTTP 204 No Content status code
- Empty response body (data loaded successfully)

Error Conditions:

• BRF file not found or unreadable
• Repository does not exist (must be created first)
• Authentication failures or insufficient permissions
• Server-side data processing errors
• Memory limitations with very large datasets

Example Usage:

err := GraphDBRestoreBrf("http://localhost:7200", "admin", "password", "production-data.brf")
if err != nil {
    log.Fatal("Data restore failed:", err)
}
log.Println("Repository data restored successfully")

Workflow Integration:

Typically used after GraphDBRestoreConf() to complete repository restoration:
1. Restore repository configuration
2. Restore repository data from BRF file
3. Verify data integrity and accessibility

func GraphDBRestoreConf ¶

func GraphDBRestoreConf(url string, user string, pass string, restoreFile string) error

GraphDBRestoreConf restores a repository configuration from a Turtle file. This function uploads a repository configuration file to create a new repository with the settings defined in the Turtle configuration.

Configuration Restoration:

Uses multipart form upload to send the Turtle configuration file
to GraphDB's repository creation endpoint, enabling:
- Repository recreation from backup configurations
- Deployment automation with predefined settings
- Configuration migration between environments
- Template-based repository creation

Parameters:

• url: Base URL of the GraphDB server
• user: Username for HTTP Basic Authentication
• pass: Password for HTTP Basic Authentication
• restoreFile: Path to the Turtle configuration file (.ttl)

Returns:

• error: File reading, upload, or server errors

Upload Process:

1. Reads the Turtle configuration file from disk
2. Creates multipart form data with the file content
3. Uploads to GraphDB's REST repositories endpoint
4. Validates successful repository creation response

File Format Requirements:

The restore file must be a valid Turtle configuration containing:
- Repository type and identifier
- Storage backend configuration
- Index and performance settings
- Security and access control definitions

Success Conditions:

Repository creation is successful when the server returns:
- HTTP 201 Created status code
- Confirmation message in response body

Error Conditions:

• Configuration file not found or unreadable
• Invalid Turtle syntax in configuration
• Repository ID conflicts with existing repositories
• Authentication failures or insufficient permissions
• Server-side configuration validation errors

Example Usage:

err := GraphDBRestoreConf("http://localhost:7200", "admin", "password", "backup-repo.ttl")
if err != nil {
    log.Fatal("Configuration restore failed:", err)
}
log.Println("Repository restored successfully")

Best Practices:

• Validate configuration files before restoration
• Ensure repository IDs don't conflict with existing ones
• Test configurations in development before production use
• Backup existing repositories before restoration operations

func GraphDBZitiClient ¶ added in v0.0.3

func GraphDBZitiClient(identityFile, serviceName string) (*http.Client, error)

GraphDBZitiClient creates an HTTP client configured for Ziti zero-trust networking. This function enables secure GraphDB access through Ziti overlay networks, providing network invisibility and strong identity-based authentication.

Ziti Integration:

Uses the ZitiSetup function to create a transport that routes all
GraphDB traffic through the Ziti network overlay, ensuring:
- End-to-end encryption for all database communications
- Network invisibility (no exposed ports or network discovery)
- Identity-based access control and policy enforcement
- Automatic service discovery within the Ziti network

Parameters:

• identityFile: Path to Ziti identity file for authentication
• serviceName: Name of the Ziti service for GraphDB access

Returns:

• *http.Client: HTTP client configured with Ziti transport
• error: Ziti setup or configuration errors

Client Configuration:

The returned client includes:
- Custom transport for Ziti network routing
- 30-second timeout for database operations
- Standard HTTP client features for GraphDB API calls

Error Conditions:

• Invalid Ziti identity file or credentials
• Ziti service not found or accessible
• Network connectivity issues to Ziti controllers
• Invalid service name or configuration

Example Usage:

client, err := GraphDBZitiClient("/path/to/identity.json", "graphdb-service")
if err != nil {
    log.Fatal("Failed to create Ziti client:", err)
}
HttpClient = client // Use Ziti client for all GraphDB operations

Security Benefits:

• GraphDB server becomes invisible to traditional networks
• Strong cryptographic identity for all connections
• Dynamic policy enforcement and access control
• Protection against network-based attacks and reconnaissance

func ImportRDF ¶

func ImportRDF(serverURL, repositoryID, username, password, rdfFilePath, contentType string) ([]byte, error)

ImportRDF imports RDF data from a file into an RDF4J repository. This function uploads RDF data in various serialization formats to a specified repository, handling encoding validation and content negotiation.

Import Process:

1. Reads RDF data from the specified file path
2. Removes UTF-8 BOM if present to ensure parser compatibility
3. Validates UTF-8 encoding to prevent parser errors
4. Uploads data to the repository via HTTP POST
5. Returns server response for status verification

Parameters:

• serverURL: Base URL of the RDF4J server
• repositoryID: Target repository identifier
• username: Username for HTTP Basic Authentication
• password: Password for HTTP Basic Authentication
• rdfFilePath: File system path to the RDF data file
• contentType: MIME type for the RDF serialization format

Returns:

• []byte: Raw response body from the server
• error: File reading, encoding validation, or HTTP errors

Supported Content Types:

• "application/rdf+xml": RDF/XML format
• "text/turtle": Turtle format
• "application/ld+json": JSON-LD format
• "application/n-triples": N-Triples format
• "application/n-quads": N-Quads format

File Validation:

The function performs UTF-8 validation to ensure the RDF file
contains valid Unicode text. Invalid UTF-8 sequences will cause
the function to return an error before attempting upload.

Error Conditions:

• File not found or permission denied
• Invalid UTF-8 encoding in the file
• Network connectivity issues
• Authentication failures
• Repository not found or access denied
• Invalid RDF syntax (server-side validation)

Example Usage:

response, err := ImportRDF(
    "http://localhost:8080/rdf4j-server",
    "my-repository",
    "admin",
    "password",
    "/path/to/data.rdf",
    "application/rdf+xml",
)
if err != nil {
    log.Fatal("Import failed:", err)
}

fmt.Printf("Server response: %s\n", string(response))

Transaction Behavior:

The import operation is typically atomic at the repository level,
meaning either all triples are imported successfully or none are
added in case of errors during processing.

Performance Considerations:

• Large files are uploaded entirely into memory before sending
• Consider chunking or streaming for very large datasets
• Server timeout settings may affect large imports
• Repository performance depends on storage backend type

func NormalizeJSONLD ¶ added in v0.0.7

func NormalizeJSONLD(doc interface{}) (string, error)

NormalizeJSONLD performs basic JSON-LD normalization (canonicalization). This produces a deterministic representation for comparison and hashing.

Parameters:

• doc: Document to normalize

Returns:

• string: Normalized JSON-LD as string
• error: Normalization errors

Normalization Process:

Creates canonical form:
- Sorts all keys alphabetically
- Removes whitespace
- Ensures consistent formatting
- Produces deterministic output

Use Cases:

• Document comparison and deduplication
• Cryptographic signing of JSON-LD
• Cache key generation
• Content-addressed storage

Example Usage:

doc := map[string]interface{}{
    "@context": "https://schema.org",
    "name":     "nginx",
    "@type":    "SoftwareApplication",
}

normalized, err := NormalizeJSONLD(doc)
if err != nil {
    log.Printf("Normalization failed: %v", err)
    return
}

// normalized is deterministic string representation
fmt.Printf("Hash: %x\n", sha256.Sum256([]byte(normalized)))

func PGInfo ¶

func PGInfo(pgUrl string)

PGInfo establishes a PostgreSQL connection and displays database information. This function provides database connectivity testing and metadata discovery, including connection pool configuration and table listing for administrative purposes.

Connection Pool Configuration:

The function configures PostgreSQL connection pooling with production-ready settings:
- MaxIdleConns: 10 connections in idle pool for efficiency
- MaxOpenConns: 100 maximum concurrent connections for load management
- ConnMaxLifetime: 1 hour maximum connection reuse for stability

Database Discovery:

Queries the information_schema to discover existing tables in the public schema,
providing visibility into the current database structure for debugging and
administrative purposes.

Parameters:

• pgUrl: PostgreSQL connection string (format: "host=localhost user=username dbname=mydb sslmode=disable")

Connection String Format:

Standard PostgreSQL connection strings with parameters:
- host: Database server hostname or IP
- port: Database server port (default 5432)
- user: Database username
- password: Database password
- dbname: Database name
- sslmode: SSL connection mode (disable, require, verify-ca, verify-full)

Error Handling:

Uses panic for unrecoverable errors, indicating this function is intended
for initialization and administrative scenarios where database connectivity
is essential for application operation.

Output Information:

• Database connection object details
• List of existing tables in the public schema
• Success confirmation message

Example Usage:

PGInfo("host=localhost user=admin password=secret dbname=rabbitlogs sslmode=disable")

Security Considerations:

• Connection strings may contain sensitive credentials
• Use environment variables or secure configuration for production
• Consider connection encryption for sensitive environments
• Implement proper access controls and authentication

Performance Impact:

• Connection pool settings affect resource usage and performance
• Table discovery query may be slow with many tables
• Connection lifetime affects memory usage and stability

func PGMigrations ¶

func PGMigrations(pgUrl string)

PGMigrations performs database schema migrations for RabbitMQ logging tables. This function ensures the database schema is up-to-date with the current model definitions, creating or updating tables as needed for proper operation.

Migration Process:

Uses GORM's AutoMigrate functionality to:
- Create tables if they don't exist
- Add new columns to existing tables
- Update column types when compatible
- Create indexes defined in model tags
- Handle foreign key relationships

Parameters:

• pgUrl: PostgreSQL connection string for database access

Migration Safety:

GORM AutoMigrate is designed to be safe for production use:
- Only adds new columns, never removes existing ones
- Preserves existing data during schema changes
- Creates tables and indexes if they don't exist
- Does not modify existing column types incompatibly

Schema Evolution:

• New fields added to RabbitLog model will create new columns
• Index changes in model tags will be applied
• Foreign key relationships will be established
• Constraints defined in tags will be applied

Error Handling:

Uses panic for migration failures, indicating that database schema
issues are critical and prevent application startup. This ensures
that schema problems are addressed before the application runs.

Best Practices:

• Run migrations during application startup
• Test migrations in development environment first
• Backup database before running migrations in production
• Monitor migration performance for large tables

Example Usage:

PGMigrations("host=localhost user=admin password=secret dbname=rabbitlogs sslmode=disable")

Production Considerations:

• Migrations may take time with large existing tables
• Consider maintenance windows for significant schema changes
• Monitor application logs for migration success/failure
• Implement rollback procedures for critical schema changes

func PGRabbitLogFormatList ¶

func PGRabbitLogFormatList(pgUrl string, format string) interface{}

PGRabbitLogFormatList retrieves RabbitMQ log entries with configurable output formats. This function provides flexible data access with multiple serialization options for different consumption patterns and integration requirements.

Format Support:

• "application/json": JSON serialization for API responses and web clients
• "struct": Raw Go structs for internal application processing
• Other formats: Returns error for unsupported format requests

Parameters:

• pgUrl: PostgreSQL connection string for database access
• format: Desired output format ("application/json" or "struct")

Returns:

• interface{}: Data in requested format ([]byte for JSON, []RabbitLog for struct)
• nil: On errors or unsupported formats

JSON Serialization:

When format is "application/json", the function:
- Marshals all log records to JSON byte array
- Includes all fields from RabbitLog struct and embedded GORM model
- Provides timestamp formatting according to JSON standards
- Binary log data is automatically base64-encoded by JSON marshaler

Struct Format:

When format is "struct", returns raw []RabbitLog slice for:
- Direct access to typed data without serialization overhead
- Internal application processing with full type safety
- Further processing or filtering by calling code

Error Handling:

• Database connection errors are logged and return nil
• Query errors are logged and return nil
• JSON marshaling errors are logged and return nil
• Unsupported formats are logged and return nil

Use Cases:

• REST API endpoints serving log data
• Internal microservice communication
• Data export and backup operations
• Integration with monitoring and analytics systems

Example Usage:

// For API response
jsonData := PGRabbitLogFormatList(connectionString, "application/json")

// For internal processing
logs := PGRabbitLogFormatList(connectionString, "struct").([]RabbitLog)

Performance Considerations:

• JSON serialization adds CPU overhead for large datasets
• Memory usage depends on number of records and serialization format
• Network transfer size varies significantly between formats
• Consider pagination for large result sets

Return Type Handling:

Callers must type assert the interface{} return value:
- JSON format returns []byte
- Struct format returns []RabbitLog
- Check for nil before type assertion

func PGRabbitLogList ¶

func PGRabbitLogList(pgUrl string)

PGRabbitLogList retrieves and displays all RabbitMQ log entries from the database. This function provides a complete listing of log records with formatted output for debugging, monitoring, and administrative purposes.

Data Retrieval:

Uses GORM's Find method to retrieve all RabbitLog records from the database,
including all fields and automatically populated timestamps from the
embedded GORM model.

Parameters:

• pgUrl: PostgreSQL connection string for database access

Output Format:

Each log entry is displayed with:
- Complete RabbitLog struct information (ID, timestamps, DocumentID, State, Version)
- Decoded log data as string (converted from byte array)
- Structured format suitable for console output and debugging

Error Handling:

• Database connection errors cause panic for immediate feedback
• Query errors are logged via eve.Logger.Error but don't halt execution
• Graceful handling allows partial results even with some errors

Log Data Display:

The Log field contains raw binary data which is displayed as a string
for human readability, enabling inspection of log content. Binary data
that is not valid UTF-8 may display with special characters.

Performance Considerations:

• Retrieves all records without pagination (may be slow with large datasets)
• Memory usage grows with number of log entries
• Consider adding LIMIT clauses for production use with large tables
• Network bandwidth usage increases with log data size

Use Cases:

• Development debugging and log inspection
• Administrative monitoring of processing status
• Troubleshooting document processing issues
• Audit trail review for compliance purposes

Example Output:

{1 2024-01-15 10:30:00 2024-01-15 10:35:00 <nil> doc-12345 completed v1.0.0 [log data]}  =>  Processing completed successfully

Production Alternatives:

For production environments, consider:
- Pagination support for large datasets
- Filtering options by DocumentID, State, or date ranges
- Export to file formats for offline analysis
- Integration with log aggregation systems

func PGRabbitLogNew ¶

func PGRabbitLogNew(pgUrl, documentId, state, version string)

PGRabbitLogNew creates a new RabbitMQ log entry in the database. This function inserts a new log record with document identification, processing state, and version information for message tracking purposes.

Record Creation:

Creates a new RabbitLog record with:
- Automatic ID assignment by database
- Automatic CreatedAt timestamp from GORM
- Provided DocumentID, State, and Version values
- Empty Log field (to be populated later via updates)

Parameters:

• pgUrl: PostgreSQL connection string
• documentId: Unique identifier for the document being processed
• state: Initial processing state (e.g., "started", "initialized")
• version: Document or processing version identifier

Database Transaction:

Uses GORM's Create method which automatically handles:
- SQL generation and parameter binding
- Transaction management for single record insertion
- Primary key assignment and return
- Timestamp population for CreatedAt and UpdatedAt

Error Handling:

Uses panic for database errors, indicating that log creation failures
are critical and should halt processing to prevent data loss or
inconsistent state tracking.

Usage Pattern:

Typically called at the beginning of document processing to establish
a log entry that will be updated throughout the processing lifecycle:

1. Create initial log entry with "started" state
2. Update log entry with progress and intermediate states
3. Final update with "completed" or "failed" state and full log data

Example Usage:

PGRabbitLogNew(connectionString, "doc-12345", "started", "v1.0.0")

Data Validation:

Consider adding validation for:
- DocumentID format and uniqueness constraints
- State values against allowed enumeration
- Version format according to versioning scheme

Performance Considerations:

• Single record insertion is efficient
• Consider batch operations for high-volume scenarios
• Database indexes on DocumentID improve lookup performance

func PGRabbitLogUpdate ¶

func PGRabbitLogUpdate(pgUrl, documentId, state string, logText []byte)

PGRabbitLogUpdate updates an existing RabbitMQ log entry with new state and log data. This function modifies log records to reflect processing progress and capture detailed log information throughout the document processing lifecycle.

Update Operations:

Updates existing RabbitLog records by DocumentID with:
- New processing state to track progress
- Raw binary log data stored directly in bytea field
- Automatic UpdatedAt timestamp via GORM

Parameters:

• pgUrl: PostgreSQL connection string
• documentId: Document identifier to locate the record for update
• state: New processing state (e.g., "running", "completed", "failed")
• logText: Binary log data to be stored directly

Database Operation:

Uses GORM's Model().Where().Updates() pattern for:
- Efficient conditional updates by DocumentID
- Multiple field updates in single database transaction
- Automatic timestamp management for UpdatedAt field
- Safe parameter binding to prevent SQL injection

Data Storage:

Binary log data is stored directly in PostgreSQL's bytea field:
- No encoding overhead, saving CPU and storage space
- Handles arbitrary binary content including null bytes
- Maintains data integrity without encoding/decoding steps
- Optimal performance for binary data storage

Error Handling:

Uses panic for database errors, indicating that log update failures
are critical for maintaining processing state consistency and should
halt execution to prevent data loss or inconsistent tracking.

Update Pattern:

Typically used to track processing progress:
1. Initial record created with basic information
2. Intermediate updates with progress states and partial logs
3. Final update with completion state and full log data

Example Usage:

logData := []byte("Processing completed successfully with result: {...}")
PGRabbitLogUpdate(connectionString, "doc-12345", "completed", logData)

Concurrency Considerations:

• Multiple updates to same DocumentID are handled by database locking
• Last update wins for conflicting simultaneous updates
• Consider optimistic locking for critical update scenarios

Performance Impact:

• Direct binary storage without encoding overhead
• Index on DocumentID ensures efficient record location
• Single transaction minimizes database round trips
• Large log data may impact update performance

Storage Optimization:

For production environments with large log data, consider:
- Compression before storage for space efficiency
- Separate blob storage for very large log files
- Log rotation and archival strategies
- Database partitioning for time-based queries

func PoolPartyProjects ¶ added in v0.0.6

func PoolPartyProjects(baseURL, username, password, templateDir string)

PoolPartyProjects is a convenience function that creates a PoolParty client, fetches all projects, and prints them with troubleshooting tips if the operation fails. This is useful for quick CLI tools and debugging connection issues.

Parameters:

• baseURL: The PoolParty server base URL
• username: Authentication username
• password: Authentication password
• templateDir: Directory for SPARQL query templates (can be empty string)

Example:

PoolPartyProjects("https://poolparty.example.com", "admin", "password", "./templates")

func PrintProjects ¶ added in v0.0.6

func PrintProjects(projects []Project)

PrintProjects prints a list of PoolParty projects in a human-readable format. Each project is displayed with its ID, title, description, URI, type, status, creation date, and modification date. This is useful for debugging and CLI output.

Parameters:

• projects: List of projects to print

Example:

projects, _ := client.ListProjects()
PrintProjects(projects)

func RunSparQLFromFile ¶ added in v0.0.6

func RunSparQLFromFile(baseURL, username, password, projectID, templateDir, tmplFileName, contentType string, params interface{}) ([]byte, error)

RunSparQLFromFile is a convenience function that creates a PoolParty client and executes a SPARQL query from a template file in a single call. This is useful for one-off queries where you don't need to maintain a persistent client.

Parameters:

• baseURL: The PoolParty server base URL
• username: Authentication username
• password: Authentication password
• projectID: The PoolParty project/thesaurus ID
• templateDir: Directory containing template files
• tmplFileName: Name of the template file
• contentType: Desired response format
• params: Parameters to pass to the template

Returns:

• []byte: Query results in the requested format
• error: Any error encountered during execution

Example:

params := map[string]string{"limit": "100"}
results, err := RunSparQLFromFile("https://poolparty.example.com", "admin", "pass",
    "myproject", "./templates", "concepts.sparql", "application/json", params)

func SetJSONLDContext ¶ added in v0.0.7

func SetJSONLDContext(doc interface{}, context string) map[string]interface{}

SetJSONLDContext adds or updates the @context field in a document. This is a convenience function for adding JSON-LD context.

Parameters:

• doc: Document to modify
• context: Context URL or object

Returns:

• map[string]interface{}: Document with updated context

Example Usage:

doc := map[string]interface{}{
    "name": "nginx",
    "status": "running",
}

doc = SetJSONLDContext(doc, "https://schema.org")
// Now doc has @context field

func TraverseTyped ¶ added in v0.0.7

func TraverseTyped[T any](c *CouchDBService, opts TraversalOptions) ([]T, error)

TraverseTyped performs typed graph traversal using generics. This provides compile-time type safety for traversal results.

Type Parameter:

• T: Expected document type

Parameters:

• opts: TraversalOptions configuration

Returns:

• []T: Slice of traversed documents of type T
• error: Traversal or parsing errors

Example Usage:

type Container struct {
    ID       string `json:"_id"`
    Name     string `json:"name"`
    HostedOn string `json:"hostedOn"`
}

opts := TraversalOptions{
    StartID:       "host-123",
    Depth:         1,
    RelationField: "hostedOn",
    Direction:     "reverse",
}

containers, err := TraverseTyped[Container](service, opts)
for _, container := range containers {
    fmt.Printf("Container: %s on %s\n", container.Name, container.HostedOn)
}

func ValidateJSONLD ¶ added in v0.0.7

func ValidateJSONLD(doc interface{}, context string) error

ValidateJSONLD performs basic JSON-LD validation on a document. This checks for required JSON-LD fields and structure without full RDF processing.

Parameters:

• doc: Document to validate (map or struct)
• context: Expected @context value (empty string to skip context check)

Returns:

• error: Validation errors if document is invalid

Validation Checks:

• Document must have @context field (if context parameter provided)
• Document should have @type field for semantic typing
• @id field should be present for linked data
• Context must match expected value (if specified)

JSON-LD Requirements:

Minimum valid JSON-LD document:
{
    "@context": "https://schema.org",
    "@type": "Thing",
    "@id": "https://example.com/thing/123"
}

Example Usage:

doc := map[string]interface{}{
    "@context": "https://schema.org",
    "@type":    "SoftwareApplication",
    "@id":      "urn:container:nginx-1",
    "name":     "nginx",
}

err := ValidateJSONLD(doc, "https://schema.org")
if err != nil {
    log.Printf("Invalid JSON-LD: %v", err)
    return
}