Connection String Reference
Connection String Reference
This document provides information about Stoolap connection string formats and their usage.
Connection String Basics
Stoolap connection strings follow a URL-like format:
scheme://[path]
Where:
scheme
specifies the storage engine typepath
provides location information for persistent storage (optional for memory storage)
MVCC Storage Engine
Stoolap uses a single MVCC (Multi-Version Concurrency Control) storage engine that supports two modes:
In-Memory Mode (memory://)
memory://
MVCC engine with in-memory storage:
- All data stored in RAM for maximum performance
- Full MVCC transaction isolation and concurrency control
- Data is lost when the process terminates
- No persistence between sessions
Example:
memory://
Persistent Mode (file://)
file:///path/to/data
MVCC engine with disk persistence:
- Same MVCC features as memory mode
- Data persisted to disk for durability
- Snapshot-based persistence for analytical workloads
- WAL (Write-Ahead Logging) for crash recovery
- Transaction isolation with optimistic concurrency control
Examples:
file:///data/mydb
file:///Users/username/stoolap/data
file:///C:/stoolap/data
Configuration Options
The persistent mode supports additional configuration through query parameters:
file:///path/to/data?sync_mode=full&snapshot_interval=60
Available options:
sync_mode
: WAL synchronization mode (none, normal, full)snapshot_interval
: Time between snapshots in secondskeep_snapshots
: Number of snapshots to keep per table
Usage Examples
Using the New Simplified API (Recommended)
Stoolap now provides a simplified API that doesn’t require the database/sql
package:
package main
import (
"context"
"log"
"github.com/stoolap/stoolap"
)
func main() {
// Open database using the simplified API
db, err := stoolap.Open("memory://")
if err != nil {
log.Fatal(err)
}
defer db.Close()
// Execute queries directly
ctx := context.Background()
_, err = db.Exec(ctx, "CREATE TABLE users (id INT, name TEXT)")
if err != nil {
log.Fatal(err)
}
// Query data with parameters
rows, err := db.Query(ctx, "SELECT * FROM users WHERE id = ?", 1)
if err != nil {
log.Fatal(err)
}
defer rows.Close()
// Use transactions
tx, err := db.Begin()
if err != nil {
log.Fatal(err)
}
_, err = tx.ExecContext(ctx, "INSERT INTO users VALUES (?, ?)", 1, "Alice")
if err != nil {
tx.Rollback()
log.Fatal(err)
}
err = tx.Commit()
if err != nil {
log.Fatal(err)
}
}
Command Line Example
# Start CLI with in-memory database
stoolap -db memory://
# Start with file-based persistent storage
stoolap -db file:///data/mydb
# Start with persistent MVCC engine
stoolap -db file:///data/mydb
Using Standard database/sql Package
You can also use Stoolap with Go’s standard database/sql
package:
In-Memory Database
package main
import (
"database/sql"
"log"
_ "github.com/stoolap/stoolap/pkg/driver"
)
func main() {
// Connect to an in-memory database
db, err := sql.Open("stoolap", "memory://")
if err != nil {
log.Fatal(err)
}
defer db.Close()
// Use the database...
}
File-Based Persistent Database
package main
import (
"database/sql"
"log"
_ "github.com/stoolap/stoolap/pkg/driver"
)
func main() {
// Connect to a file-based database
db, err := sql.Open("stoolap", "file:///path/to/database")
if err != nil {
log.Fatal(err)
}
defer db.Close()
// Use the database...
}
Persistent MVCC Database with Configuration
package main
import (
"database/sql"
"log"
_ "github.com/stoolap/stoolap/pkg/driver"
)
func main() {
// Connect with persistence and custom configuration
connStr := "file:///path/to/database?sync_mode=full&snapshot_interval=30"
db, err := sql.Open("stoolap", connStr)
if err != nil {
log.Fatal(err)
}
defer db.Close()
// Use the database with full MVCC transaction support...
}
PRAGMA Configuration
You can also configure the database using PRAGMA commands after connection (alternative to query parameters):
// Open database
db, err := sql.Open("stoolap", "file:///data/mydb")
if err != nil {
log.Fatal(err)
}
// Configure database settings
_, err = db.Exec("PRAGMA snapshot_interval = 60")
if err != nil {
log.Fatal(err)
}
// Configure WAL synchronization mode
_, err = db.Exec("PRAGMA sync_mode = 2")
if err != nil {
log.Fatal(err)
}
See the PRAGMA Commands documentation for more details on available configuration options.