README
¶
hazedb
sql db written in go
Documentation
¶
Overview ¶
Package fastsql is a memory-resident SQL store for embedded Go applications with single-process deployment and latency-sensitive reads. See FASTSQL_v1_RFC.md and FASTSQL_PITCH.md at the repo root.
This is the v1 first-cut: generic Value-based execution. Codegen for typed-Go hot paths arrives in M3.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrDuplicatePK = errors.New("fastsql: duplicate primary key") ErrUnknownTable = errors.New("fastsql: unknown table") ErrUnknownColumn = errors.New("fastsql: unknown column") ErrTypeMismatch = errors.New("fastsql: type mismatch") ErrParamMismatch = errors.New("fastsql: parameter count mismatch") ErrPKUpdate = errors.New("fastsql: UPDATE on PK column not supported") ErrParse = errors.New("fastsql: parse error") ErrWALCorrupt = errors.New("fastsql: WAL corrupted") ErrTableExists = errors.New("hazedb: table already exists") ErrTxUnsupported = errors.New("hazedb: operation not supported in a transaction") )
Functions ¶
This section is empty.
Types ¶
type ColumnDef ¶
type ColumnDef struct {
Name string
Type ColumnType
// PK marks the single primary-key column. It must be TypeUUID and is
// implicitly immutable.
PK bool
// Immutable rejects UPDATE SET on this column at plan time. Used for an
// ordering column (e.g. seq) so a tail index can cache its order safely.
Immutable bool
// PartitionKey marks the column the table is sharded/ordered by (e.g.
// thread_id on a messages table). At most one per table; must be UUID in
// v1; implicitly immutable (a partition move is DELETE + INSERT). Storage
// routing + the ordered tail index build on it.
PartitionKey bool
Nullable bool
}
ColumnDef describes one column at table-create time.
type ColumnType ¶
type ColumnType uint8
ColumnType is the declared type of a column. Generic v1 supports a small set; codegen (M3) expands to richer types.
const ( TypeInt ColumnType = iota + 1 TypeString TypeBytes TypeBool TypeUUID )
func (ColumnType) String ¶
func (t ColumnType) String() string
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB is the embedded database handle. One DB per process per WAL path. Open is goroutine-safe; Exec and Query are goroutine-safe.
func Open ¶
Open prepares the database. If WALPath is non-empty, the file is opened and any existing records are replayed into memory before Open returns. Open is blocking until replay completes.
func (*DB) Exec ¶
Exec runs an INSERT, UPDATE, DELETE, CREATE TABLE, or DROP TABLE. Returns the affected row count (0 for DDL).
func (*DB) FlushWAL ¶
FlushWAL forces bufio to fsync. Use before reading a record back from disk in tests, or for an explicit durability boundary in callers. Memory-only DBs are a no-op.
type Options ¶
type Options struct {
// WALPath is the on-disk write-ahead log. Empty = memory-only
// (no durability). The file is created if it doesn't exist.
WALPath string
// Schema declares the tables. Required; at least one table.
Schema Schema
// SizeHint is a per-table row-count estimate for shard arena
// pre-allocation. Zero = use a small default.
SizeHint int
// WALFlushInterval is how often the background goroutine flushes the WAL
// buffer to the OS (and fsyncs when WALSync is set). Zero selects the
// safe default of 1s; a negative value disables the ticker entirely
// (manual FlushWAL() only). Ignored when WALPath is empty.
WALFlushInterval time.Duration
// WALSync makes the ticker fsync after flushing when anything is dirty,
// bounding power-loss to <= WALFlushInterval. Default false (flush only;
// survives process crash, not power loss).
WALSync bool
// WALSyncPerWrite flushes and fsyncs after every individual WAL record,
// under the WAL lock. Strongest durability (no acknowledged-loss window),
// highest per-write cost. Overrides the ticker's sync cadence.
WALSyncPerWrite bool
}
Options control Open behaviour.
type Schema ¶
type Schema struct {
Tables []TableDef
}
Schema is the database schema. Tables are addressed by name.
type TableDef ¶
TableDef defines a table. Exactly one column must have PK=true. Multi-column PK is v1.1+.
type Tx ¶
type Tx struct {
// contains filtered or unexported fields
}
Tx is the transaction handle passed to the db.Transaction closure.
type UUID ¶
type UUID [16]byte
UUID is a 128-bit identifier (RFC 9562). It is a fixed array so it is comparable and usable directly as a map key with no allocation — the primary key index is map[UUID]uint64.
func NewUUIDv7 ¶
func NewUUIDv7() UUID
NewUUIDv7 returns a fresh UUIDv7 with within-millisecond monotonicity: IDs from this process sort by creation time, including inside one millisecond, via a 12-bit counter in rand_a (RFC 9562 "fixed-length dedicated counter"). Beyond 4096 IDs in a single ms the timestamp is nudged forward to keep the ordering total. Client-supplied UUIDs get no such guarantee.
func ParseUUID ¶
ParseUUID parses the canonical 36-character hyphenated hex form. It accepts any well-formed UUID (version is not enforced here — callers that require v7 check IsV7). Used at the API boundary to turn a string PK into the internal [16]byte; storage never sees the string form.
func (UUID) IsV7 ¶
IsV7 reports whether u has the v7 version nibble and the RFC 4122/9562 variant bits (10xx). Used to validate client-supplied IDs.
type Value ¶
Value is the runtime cell type. Generic and slow-ish vs a typed struct; appropriate for the interpreter path (codegen replaces []Value with typed structs per table on the eventual hot path).
- KindInt: I holds the value
- KindString: S holds the value
- KindBytes: B holds the value (avoid allocs by reusing slices upstream)
- KindBool: I == 0 false, I == 1 true
- KindUUID: U holds the 16 bytes (no heap alloc; usable as a map key)
- KindNull: all zero
U is a fixed [16]byte rather than living in B so a UUID PK is a comparable, allocation-free map key. It costs 16 bytes on every cell; if that proves to matter it can be packed into two uint64 — measure first.
func (Value) AsInt ¶
AsInt returns the value as int64, coercing strings via strconv. Used for ORDER BY / range comparisons.
func (Value) AsString ¶
AsString returns the value formatted as text. Used for PK keys in the map index and for display.
func (Value) Compare ¶
Compare returns -1/0/1 for v < o, v == o, v > o. Coerces along the most-precise route: int-int → numeric, otherwise string-string. Null comparisons return 0 with comparable=false to let callers decide.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
addons
|
|
|
frankenphp-ext
module
|
|
|
caddymodule
module
|
|
|
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.
|
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. |