Documentation
¶
Index ¶
- Constants
- Variables
- func ApplyLocaleToRead(data map[string]any, cols map[string]*ingitdb.ColumnDef) map[string]any
- func ApplyLocaleToWrite(data map[string]any, cols map[string]*ingitdb.ColumnDef) map[string]any
- func CollectionForKey(def *ingitdb.Definition, id string) (*ingitdb.CollectionDef, string, error)
- func EncodeMapOfRecordsContent(data map[string]map[string]any, format ingitdb.RecordFormat, ...) ([]byte, error)
- func EncodeRecordContentForCollection(value any, colDef *ingitdb.CollectionDef) ([]byte, error)
- func NewDatabase(projectPath string, reader ingitdb.CollectionsReader) (dal.DB, error)
- func ParseMapOfRecordsContent(content []byte, format ingitdb.RecordFormat) (map[string]map[string]any, error)
- func ParseRecordContent(content []byte, format ingitdb.RecordFormat) (map[string]any, error)
- func ParseRecordContentForCollection(content []byte, colDef *ingitdb.CollectionDef) (map[string]any, error)
- type CSVParseOptions
- type Database
- func (db *Database) Adapter() dal.Adapter
- func (db *Database) AlterCollection(ctx context.Context, name string, ops ...ddl.AlterOp) error
- func (db *Database) CreateCollection(_ context.Context, c dbschema.CollectionDef, opts ...ddl.Option) error
- func (db *Database) DescribeCollection(_ context.Context, ref *dal.CollectionRef) (*dbschema.CollectionDef, error)
- func (db *Database) DropCollection(_ context.Context, name string, opts ...ddl.Option) error
- func (db *Database) ExecuteQueryToRecordsReader(ctx context.Context, query dal.Query) (dal.RecordsReader, error)
- func (db *Database) ExecuteQueryToRecordsetReader(_ context.Context, _ dal.Query, _ ...recordset.Option) (dal.RecordsetReader, error)
- func (db *Database) Exists(ctx context.Context, key *dal.Key) (bool, error)
- func (db *Database) Get(ctx context.Context, record dal.Record) error
- func (db *Database) GetMulti(ctx context.Context, records []dal.Record) error
- func (db *Database) ID() string
- func (db *Database) ListCollections(_ context.Context, _ *dal.Key) ([]dal.CollectionRef, error)
- func (db *Database) ListConstraints(_ context.Context, _ *dal.CollectionRef) ([]dbschema.ConstraintDef, error)
- func (db *Database) ListIndexes(_ context.Context, _ *dal.CollectionRef) ([]dbschema.IndexDef, error)
- func (db *Database) ListReferrers(_ context.Context, _ *dal.CollectionRef) ([]dbschema.Referrer, error)
- func (db *Database) RunReadonlyTransaction(ctx context.Context, f dal.ROTxWorker, _ ...dal.TransactionOption) error
- func (db *Database) RunReadwriteTransaction(ctx context.Context, f dal.RWTxWorker, _ ...dal.TransactionOption) error
- func (db *Database) Schema() dal.Schema
- func (db *Database) SupportsTransactionalDDL() bool
- type ParsedRecord
Constants ¶
const DatabaseID = "dalgo2ingitdb"
DatabaseID is the name reported by Database.ID() and used as the Adapter name.
Variables ¶
var ErrCollectionPathConflict = errors.New("dalgo2ingitdb: root-collections.yaml entry conflicts with auto-registration")
ErrCollectionPathConflict is returned by CreateCollection when <projectPath>/.ingitdb/root-collections.yaml already contains an entry for the collection name with a non-default path value. Callers either remove the existing entry or pick a different collection name.
Functions ¶
func ApplyLocaleToRead ¶ added in v0.12.0
ApplyLocaleToRead transforms record data from file representation to application representation. For each column that has a Locale value set (e.g. column "title" with locale "en"), the paired map column (e.g. "titles") is inspected: the locale entry is extracted and exposed as the shortcut column ("title"), and that locale key is removed from the pair map to avoid duplication. The caller receives e.g. {"title": "Work", "titles": {"ru": "Работа"}}.
func ApplyLocaleToWrite ¶ added in v0.12.0
ApplyLocaleToWrite normalises record data before writing to file. For each column that has a Locale value set (e.g. column "title" with locale "en"):
- The shortcut column ("title") is stored as-is in the file.
- If the paired map column ("titles") contains an entry for the primary locale key ("en"), that entry is promoted to the shortcut column and removed from the map, so the value is never duplicated across both fields.
- If the paired map becomes empty after removing the primary locale entry, it is dropped from the result to avoid writing a redundant empty map.
func CollectionForKey ¶ added in v0.9.0
func CollectionForKey(def *ingitdb.Definition, id string) (*ingitdb.CollectionDef, string, error)
CollectionForKey finds the collection and record key for a given ID string.
The id format is "{collectionID}/{recordKey}" where collection IDs use "." for namespaces. "/" is reserved for separating collection ID from record key path segments. The longest matching collection prefix wins.
func EncodeMapOfRecordsContent ¶ added in v0.57.0
func EncodeMapOfRecordsContent(data map[string]map[string]any, format ingitdb.RecordFormat, recordsetName string, columnsOrder []string) ([]byte, error)
EncodeMapOfRecordsContent serializes a map of ID-keyed records into the declared format. For yaml/json/toml, the data is written as a top-level mapping (record ID -> field map). For INGR, the data is flattened into a list of records (each gets `$ID` injected as the first column) and written via the ingr-io writer.
recordsetName is used as the INGR header title (typically the collection ID). It is ignored for non-INGR formats. columnsOrder controls the column order in the INGR header; when empty, columns are emitted in alphabetical order with `$ID` first.
func EncodeRecordContentForCollection ¶ added in v1.2.0
func EncodeRecordContentForCollection(value any, colDef *ingitdb.CollectionDef) ([]byte, error)
EncodeRecordContentForCollection serializes record content using the collection's declared format. It is the write-side counterpart of ParseRecordContentForCollection and the only path callers should use when writing records that may be in a format that requires schema access (csv today; possibly others later).
For csv, value MUST be []map[string]any — see encodeCSVForCollection. For the other six formats, value is passed through to marshalForFormat unchanged; callers that want a single-record map[string]any can keep using the schema-agnostic marshalForFormat directly.
func NewDatabase ¶ added in v1.8.0
NewDatabase constructs a Database rooted at projectPath. The reader is used to load the project Definition at the start of each transaction and inside DB-level record-access methods. Returns an error if projectPath is empty or does not exist; the constructor does NOT load any collection definitions.
func ParseMapOfRecordsContent ¶ added in v0.40.0
func ParseMapOfRecordsContent(content []byte, format ingitdb.RecordFormat) (map[string]map[string]any, error)
ParseMapOfRecordsContent parses content containing a map of ID-keyed records.
For yaml/json/toml, the file's top-level structure is a mapping from record ID to a per-record field map; we re-shape it into map[string]map[string]any.
For INGR, the file is a list of records where the reserved `$ID` column holds each record's key; we read the list and re-index by `$ID`. Records missing `$ID`, or with duplicate `$ID` values, are rejected as malformed.
func ParseRecordContent ¶ added in v0.12.0
ParseRecordContent parses record content in YAML or JSON format. For markdown-format collections use ParseRecordContentForCollection, which also has access to the column schema and content-field name.
func ParseRecordContentForCollection ¶ added in v0.55.0
func ParseRecordContentForCollection(content []byte, colDef *ingitdb.CollectionDef) (map[string]any, error)
ParseRecordContentForCollection parses record content using the collection's declared format. For YAML and JSON this is equivalent to ParseRecordContent. For markdown records it parses YAML frontmatter, filters to columns declared in the schema, and exposes the body under the configured content_field column name.
Types ¶
type CSVParseOptions ¶ added in v1.7.0
type CSVParseOptions struct {
// KeyColumn, if non-empty, names the column to use as the record
// key (overrides $id/id auto-resolution).
KeyColumn string
// Fields, if non-empty, replaces the header row: the first stdin
// line is treated as data and these names are used for column
// mapping.
Fields []string
}
CSVParseOptions controls CSV-specific behavior.
type Database ¶ added in v1.8.0
type Database struct {
// dal.ConcurrencyAvailable: gofrs/flock provides cross-platform file
// locking (syscall.Flock on Unix, LockFileEx on Windows), so two DB
// handles against the same project directory can operate concurrently
// without data races.
dal.ConcurrencyAvailable
// contains filtered or unexported fields
}
Database is the dal.DB implementation for inGitDB projects on the local filesystem. It implements the schema-management capability interfaces (dbschema.SchemaReader, ddl.SchemaModifier, ddl.TransactionalDDL), the dal.DB record-access methods, and reports dal.ConcurrencyAvailable via the embedded helper struct — concurrent connections are safe because every read and write path goes through gofrs/flock file locking.
Record access loads the project Definition once per transaction via the injected CollectionsReader; individual file operations take a shared (read) or exclusive (write) advisory lock on the affected file. ExecuteQueryToRecordsetReader is not yet implemented and returns dal.ErrNotSupported.
func (*Database) AlterCollection ¶ added in v1.8.0
AlterCollection applies AlterOp values in order. Operations mutate an in-memory ingitdb.CollectionDef; after each op the updated definition is flushed to disk. Failure mid-sequence returns *ddl.PartialSuccessError with applied / failed / not-attempted lists.
func (*Database) CreateCollection ¶ added in v1.8.0
func (db *Database) CreateCollection(_ context.Context, c dbschema.CollectionDef, opts ...ddl.Option) error
CreateCollection writes <projectPath>/<c.Name>/.collection/definition.yaml from the dbschema.CollectionDef. Validates name and field types before any filesystem write. With ddl.IfNotExists, an existing collection is a no-op; without it, an existing collection is an error.
After the definition.yaml write succeeds, the collection is registered in <projectPath>/.ingitdb/root-collections.yaml (REQ:auto-register-in-root-collections) so the validator-backed CollectionsReader picks it up. Registry conflicts (an existing entry mapping the same name to a non-default path) return ErrCollectionPathConflict; the definition.yaml is left in place — see AC:create-collection-rejects-registry-conflict for the recovery story.
func (*Database) DescribeCollection ¶ added in v1.8.0
func (db *Database) DescribeCollection(_ context.Context, ref *dal.CollectionRef) (*dbschema.CollectionDef, error)
DescribeCollection reads and parses the collection's definition.yaml under a shared lock, then maps the ingitdb columns to dbschema fields via type_mapping. PrimaryKey is synthesized as [pkFieldName] because inGitDB uses the record's filesystem key as the de-facto PK.
func (*Database) DropCollection ¶ added in v1.8.0
DropCollection removes <projectPath>/<name>/ from disk. The directory must contain a .collection/definition.yaml as a safety check — this guards against accidentally deleting non-collection directories. With ddl.IfExists, a missing collection is a no-op.
func (*Database) ExecuteQueryToRecordsReader ¶ added in v1.8.0
func (db *Database) ExecuteQueryToRecordsReader(ctx context.Context, query dal.Query) (dal.RecordsReader, error)
ExecuteQueryToRecordsReader runs a structured query against a single collection. See readonlyTx.ExecuteQueryToRecordsReader for supported query features.
func (*Database) ExecuteQueryToRecordsetReader ¶ added in v1.8.0
func (db *Database) ExecuteQueryToRecordsetReader(_ context.Context, _ dal.Query, _ ...recordset.Option) (dal.RecordsetReader, error)
ExecuteQueryToRecordsetReader is not implemented yet; callers should use ExecuteQueryToRecordsReader instead.
func (*Database) Exists ¶ added in v1.8.0
Exists reports whether the record identified by key exists on disk.
func (*Database) ListCollections ¶ added in v1.8.0
ListCollections walks the project directory looking for directories that contain a .collection/definition.yaml file. The parent argument is ignored (inGitDB has no catalog hierarchy). Results are sorted alphabetically by name; names use "/" as the separator for nested collection paths relative to projectPath.
func (*Database) ListConstraints ¶ added in v1.8.0
func (db *Database) ListConstraints(_ context.Context, _ *dal.CollectionRef) ([]dbschema.ConstraintDef, error)
ListConstraints returns a synthesized single-element slice describing the primary-key constraint. ingitdb does not store other constraint kinds in definition.yaml. The richer PK column information lives on `DescribeCollection.PrimaryKey`; dbschema.ConstraintDef is intentionally minimal (Name + Type only).
func (*Database) ListIndexes ¶ added in v1.8.0
func (db *Database) ListIndexes(_ context.Context, _ *dal.CollectionRef) ([]dbschema.IndexDef, error)
ListIndexes returns a non-nil empty slice and nil error. inGitDB has no per-collection index declarations today.
func (*Database) ListReferrers ¶ added in v1.8.0
func (db *Database) ListReferrers(_ context.Context, _ *dal.CollectionRef) ([]dbschema.Referrer, error)
ListReferrers returns *dbschema.NotSupportedError — inGitDB has no structural foreign-key declarations; ColumnDef.ForeignKey is a free-text hint, not a navigable reference.
func (*Database) RunReadonlyTransaction ¶ added in v1.8.0
func (db *Database) RunReadonlyTransaction(ctx context.Context, f dal.ROTxWorker, _ ...dal.TransactionOption) error
RunReadonlyTransaction loads the project Definition and invokes the worker with a readonly transaction. The Definition is captured at the start of the transaction; subsequent on-disk schema changes are not observed within the transaction.
func (*Database) RunReadwriteTransaction ¶ added in v1.8.0
func (db *Database) RunReadwriteTransaction(ctx context.Context, f dal.RWTxWorker, _ ...dal.TransactionOption) error
RunReadwriteTransaction loads the project Definition and invokes the worker with a read-write transaction. inGitDB does not guarantee atomicity across multiple file writes within a transaction; each individual file write is locked exclusively, but a worker that fails after writing some files leaves those writes in place.
func (*Database) Schema ¶ added in v1.8.0
Schema returns nil — inGitDB does not yet expose a dal.Schema view of its collection definitions. Callers needing schema introspection should use dbschema.SchemaReader instead.
func (*Database) SupportsTransactionalDDL ¶ added in v1.8.0
SupportsTransactionalDDL satisfies ddl.TransactionalDDL by reporting that this driver does NOT guarantee all-or-nothing for multi-op AlterCollection calls. A failure mid-sequence leaves earlier ops applied; the caller receives a *ddl.PartialSuccessError.
type ParsedRecord ¶ added in v1.5.0
type ParsedRecord struct {
// Position is 1-based: line number for jsonl/csv, document index
// for yaml/ingr. For csv with a header row, Position 2 is the
// first data record.
Position int
// Key is the resolved record key (from $id, id, or --key-column).
Key string
// Data is the record's structured fields with the key field stripped.
Data map[string]any
}
ParsedRecord is one record extracted from a batch stream.
func ParseBatchCSV ¶ added in v1.7.0
func ParseBatchCSV(r io.Reader, opts CSVParseOptions) ([]ParsedRecord, error)
ParseBatchCSV reads RFC 4180 CSV from r and returns one ParsedRecord per data row. Key resolution precedence is:
- opts.KeyColumn if set (rejected before reading rows if column missing).
- column named "$id" if present.
- column named "id" if present (auto-mapped).
- otherwise error.
When both "$id" and "id" columns exist without opts.KeyColumn, "$id" wins; "id" is kept as a data field. The resolved key column's value is stripped from Data.
If opts.Fields is non-empty, those names override the header row: the first stdin line is treated as data, and Position is 1-based against data rows. Otherwise Position is 1-based against source lines, so the header is line 1 and the first data row is line 2.
func ParseBatchINGR ¶ added in v1.6.0
func ParseBatchINGR(r io.Reader) ([]ParsedRecord, error)
ParseBatchINGR reads an INGR multi-record stream from r and returns one ParsedRecord per record. The key is read from the reserved $ID column (INGR's key field; note the uppercase). $ID is stripped from the returned Data map. Position is the 1-based record index.
func ParseBatchJSONL ¶ added in v1.5.0
func ParseBatchJSONL(r io.Reader) ([]ParsedRecord, error)
ParseBatchJSONL reads NDJSON from r and returns one ParsedRecord per non-blank line. Each record MUST have a top-level $id; the $id is stripped from the returned Data map. Blank lines are skipped but counted for the Position field.
func ParseBatchYAMLStream ¶ added in v1.6.0
func ParseBatchYAMLStream(r io.Reader) ([]ParsedRecord, error)
ParseBatchYAMLStream reads a YAML multi-document stream from r and returns one ParsedRecord per non-nil document. Each record MUST have a top-level $id; $id is stripped from the returned Data map. Position is the 1-based document index.
Source Files