Core Interfaces

GoGraph's external API style draws inspiration from Go's standard library database/sql, aiming to provide an intuitive and native calling experience for Go developers.

All core structures and methods exposed to the outside are within the pkg/api package.

1. Database Instance (api.DB)

Open

Description: Opens and initializes a single-file graph database instance at the specified path. If the file does not exist, it is automatically created. Internally, Pebble DB's WAL is automatically configured and enabled to ensure crash recovery.

Interface Signature:

func Open(path string, opts ...DBOption) (*DB, error)

Parameters:

Parameter	Type	Required	Description	Default
path	string	Yes	Local directory path for the database file	None
opts	...DBOption	No	Functional options, such as configuring observability mechanisms	Default built-in options

Return Values:

• *api.DB: Database instance pointer.
• error: The specific error reason when initialization fails.

Usage Example:

// Enable Tracing and Logging option injection
obs := cypher.NewObservability(cypher.WithLogger(myLogger))
db, err := api.Open("./test.db", api.WithObservability(obs))
if err != nil {
    panic(err)
}
defer db.Close()

---

Exec

Description: Executes non-query data modification operations (such as: CREATE, SET, DELETE, REMOVE) and returns the count of nodes and relationships affected by the changes. Supports safe parameterized input.

Interface Signature:

func (db *DB) Exec(ctx context.Context, cypherQuery string, args ...interface{}) (Result, error)

Parameters:

Parameter	Type	Required	Description
ctx	context.Context	Yes	Request context, used for timeout control or链路追踪传递
cypherQuery	string	Yes	Core Cypher execution statement
args	...interface{}	No	Parameterized mapping or sequentially passed parameters. Can directly pass map[string]interface{} or aligned key-value pair variables

Return Values:

• api.Result: This is a type alias for cypher.Result, containing AffectedNodes (number of modified nodes) and AffectedRels (number of modified relationships). It also stores Rows and Columns for cascading execution clause consumption.
• error: Returns an error for read-only transactions or execution failures.

Usage Example:

// Parameterized creation (preventing Cypher injection)
result, err := db.Exec(ctx, "CREATE (n:User {name: $name})", map[string]interface{}{"name": "Alice"})

---

Query

Description: Executes query operations (such as: MATCH ... RETURN) and returns an iterable result set Rows.

Interface Signature:

func (db *DB) Query(ctx context.Context, cypherQuery string, args ...interface{}) (*Rows, error)

Return Values: - *api.Rows: Result set iterator pointer. - error: Error information returned when a query fails (e.g., syntax error, type mismatch).

Usage Example:

rows, err := db.Query(ctx, "MATCH (n:User) RETURN n.name, n.age")

---

BeginTx

Description: Begins a transaction (supporting MVCC). Transactions provide ACID guarantees.

Interface Signature:

func (db *DB) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error)

2. Transaction Operations (api.Tx)

After obtaining a transaction instance through BeginTx, you can perform atomic commits or rollbacks.

Commit and Rollback

Description: Commits persistence when a transaction succeeds (Commit); otherwise cancels the operation (Rollback).

Interface Signature:

func (tx *Tx) Commit() error
func (tx *Tx) Rollback() error

Description: Similar to DB, Tx itself also exposes Exec and Query methods with consistent usage.

3. Result Set (api.Rows)

Rows provides the ability to iteratively stream through query results (typically items specified by RETURN).

Next

Description: Advances the iteration cursor to the next row. If false is returned, it indicates the end of the result set has been reached.

Interface Signature:

func (r *Rows) Next() bool

Scan

Description: Writes the data of the current cursor row into the destination pointers in order.

Interface Signature:

func (r *Rows) Scan(dest ...interface{}) error

Parameters: Pass a list of pointers for the fields to be mapped (such as *string, *int64, *bool, *float64, etc.). The order must exactly match the RETURN declaration.

Return Values: Returns errors such as api.ErrNoMoreRows if out of bounds or type mismatch.

Close

Description: Safely closes the cursor and releases internal resources. Be sure to properly close with defer rows.Close() after Query.

4. Common Error Enumerations (Error)

During development, you may encounter the following constant-defined error codes: - api.ErrDBClosed: Performing Query/Exec operations on a DB object that has already called Close(). - api.ErrNoMoreRows: Thrown when continuing to call Scan() on an iterator that has reached the end.