Documentation
¶
Overview ¶
Package GO-SQLDB is a deliberately minimal spike to validate the central thesis of the GO-SQLDB design: that an in-memory Go store with a canonical WAL can beat SQLite-in-memory on the hot OLTP path.
The spike implements ONE hardcoded table:
users(id TEXT PK, email TEXT, name TEXT)
The implementations are as simple as possible, but the types are the same types the full v1 design will use: RowID, RowRef, RowHead, Mutation, canonical WAL records. That way, adding partitions, ordered indexes, or checkpoints later does not require rewriting the existing code.
Index ¶
- type DB
- func (db *DB) Close() error
- func (db *DB) Delete(id string) error
- func (db *DB) Get(id string) (User, bool, error)
- func (db *DB) Insert(u User) (RowRef, error)
- func (db *DB) InsertBatch(users []User) error
- func (db *DB) Stats() (rows, liveIndex int)
- func (db *DB) UnsafeGet(id string) (User, bool)
- func (db *DB) Update(u User) error
- type DBL3a
- type DBL3b
- type DBL3c
- type DBL3e
- type DBL3f
- type Message
- type MessagesDB
- func (db *MessagesDB) Close() error
- func (db *MessagesDB) FlushWAL() error
- func (db *MessagesDB) GetByID(id UUIDv7, threadID [16]byte) (Message, bool)
- func (db *MessagesDB) Insert(m Message) error
- func (db *MessagesDB) LastN(threadID [16]byte, n int, dst []Message) []Message
- func (db *MessagesDB) LastNSince(threadID [16]byte, minSeq int64, limit int, dst []Message) []Message
- type PartitionID
- type RowHead
- type RowID
- type RowRef
- type TableID
- type UUIDv7
- type User
- type UserV2
- type UsersDB
- type V1DB
- type V2DB
- type V3DB
- type V4DB
- type V5DB
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
func OpenMemory ¶
OpenMemory creates a memory-only DB with no WAL. Used to measure the ceiling of the in-process map+index path without any disk I/O. NOT durable — process exit loses all data. Useful for cache/scratch workloads where the source of truth lives elsewhere.
func OpenWithSize ¶
OpenWithSize is Open with an estimated row-count hint. The hint pre-sizes the in-memory maps so the hot Insert path doesn't pay for repeated bucket-grow allocations. Pass 0 for "no hint" (matches Open).
func (*DB) InsertBatch ¶
InsertBatch inserts a slice of users under a single db.mu hold and (when WAL is on) a single wal.mu hold around the bufio writes. Reduces per-call lock/unlock and function-call overhead vs N separate Inserts. Returns the first error encountered; any prior successful inserts in the batch are NOT rolled back.
type DBL3e ¶
type DBL3e struct {
// contains filtered or unexported fields
}
func (*DBL3e) InsertBulk ¶
InsertBulk avoids the O(N) copy per insert by building the snapshot once. Use for setup/bench warmup where N inserts would otherwise be O(N^2). The snapshot is replaced atomically at the end.
type MessagesDB ¶
type MessagesDB struct {
// contains filtered or unexported fields
}
func OpenMessagesDB ¶
func OpenMessagesDB(sizeHint int) *MessagesDB
OpenMessagesDB — memory-only (no WAL).
func OpenMessagesDBWAL ¶
func OpenMessagesDBWAL(walPath string, sizeHint int) (*MessagesDB, error)
OpenMessagesDBWAL — WAL-backed for the mixed workload test.
func (*MessagesDB) Close ¶
func (db *MessagesDB) Close() error
func (*MessagesDB) FlushWAL ¶
func (db *MessagesDB) FlushWAL() error
FlushWAL forces a bufio flush. Used by mixed-workload tests to bound durability windows during the bench.
func (*MessagesDB) GetByID ¶
func (db *MessagesDB) GetByID(id UUIDv7, threadID [16]byte) (Message, bool)
GetByID — point lookup. Uses pk index, no ordered traversal.
func (*MessagesDB) Insert ¶
func (db *MessagesDB) Insert(m Message) error
func (*MessagesDB) LastN ¶
func (db *MessagesDB) LastN(threadID [16]byte, n int, dst []Message) []Message
LastN — the thesis query. Returns the last N messages of a thread in descending seq order. Single-shard read since we sharded by thread_id.
func (*MessagesDB) LastNSince ¶
func (db *MessagesDB) LastNSince(threadID [16]byte, minSeq int64, limit int, dst []Message) []Message
LastNSince — variant: last N messages with seq > minSeq. Used to validate the index-driven range scan (vs full scan + filter).
type PartitionID ¶
type PartitionID uint16
type RowHead ¶
RowHead is the indirection between RowID and the current row. V4 variant: stores the decoded User struct directly (no encoded bytes retained). Get becomes a pure struct copy with no decodeUser call. Encoded bytes are still produced on the Insert/Update path for the WAL write, but discarded after the WAL append returns.
type RowRef ¶
type RowRef struct {
Table TableID
Partition PartitionID
Row RowID
}
RowRef is the stable logical row identity used across partitions and (later) global indexes. In the spike there is only one table and one partition, but every API still produces RowRefs so that adding partitions later does not change the index contracts.
type User ¶
User is the public Go shape. The spike has a hardcoded schema, so we use a struct directly instead of a generic column model. The codec is still schema-driven: every encoded row starts with a layout version and a null bitmap, exactly like the v1 EncodedRow.
type UsersDB ¶
type UsersDB struct {
// contains filtered or unexported fields
}
func OpenUsersDB ¶
type V1DB ¶
type V1DB struct {
// contains filtered or unexported fields
}
func OpenV1Memory ¶
OpenV1Memory — no WAL, ceiling measurement.
func (*V1DB) Insert ¶
Insert — typed in-memory, then WAL framing under walMu.
Order: WAL FIRST so that on crash mid-Insert the in-memory state reflects only what's durable. Spike order was the opposite; v1 gets it right.
func (*V1DB) InsertBatch ¶
InsertBatch — N inserts under N shard-locks (one per shard's batch). More throughput than per-record Insert because WAL framing is amortised under a single walMu hold.
type V3DB ¶
type V3DB struct {
// contains filtered or unexported fields
}
func (*V3DB) BulkInsert ¶
BulkInsert — bypasses the drainer for warm-loads. Acquires shard mutexes, builds one new snapshot per shard with all rows inserted, atomic-stores. Avoids the O(N^2) cost of N sequential InsertSync.
func (*V3DB) Insert ¶
Insert — async. Returns when the write is enqueued, not when committed. For read-your-writes consistency, use InsertSync.
func (*V3DB) InsertSync ¶
InsertSync — blocks until the write has been applied to a snapshot.
Source Files