db

package
v3.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 20, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MetaKeyRepoPath = "repo_path"
)

Metadata keys

View Source 
const SchemaVersion = 3

SchemaVersion is the current schema version. Version 3 introduces: - Committer fields (committer_name, committer_email, committed_at) - Renamed created_at -> authored_at - Split content into pgit_text_content (TEXT) + pgit_binary_content (BYTEA) - Added is_binary flag to pgit_file_refs

Variables

This section is empty.

Functions

func SetDefault 

func SetDefault(db *DB)

SetDefault sets the default database instance

Types

type AmbiguousCommitError added in v3.2.0 

type AmbiguousCommitError struct {
	PartialID string
	MatchIDs  []string
}

AmbiguousCommitError is returned when a partial commit ID matches multiple commits.

func (*AmbiguousCommitError) Error added in v3.2.0 

func (e *AmbiguousCommitError) Error() string

type Blob 

type Blob struct {
	Path          string
	CommitID      string
	Content       []byte // file bytes (empty for empty files)
	ContentHash   []byte // 16 bytes BLAKE3, nil = deleted
	Mode          int
	IsSymlink     bool
	SymlinkTarget *string
	IsBinary      bool
}

Blob represents a file at a specific commit. This is the compatibility layer that combines data from pgit_paths, pgit_file_refs, and pgit_text_content/pgit_binary_content tables in schema v3.

func (*Blob) IsDeleted 

func (b *Blob) IsDeleted() bool

IsDeleted returns true if this blob represents a deletion.

type Commit 

type Commit struct {
	ID             string
	ParentID       *string
	TreeHash       string
	Message        string
	AuthorName     string
	AuthorEmail    string
	AuthoredAt     time.Time
	CommitterName  string
	CommitterEmail string
	CommittedAt    time.Time
}

Commit represents a commit in the database

type Content 

type Content struct {
	GroupID   int32
	VersionID int32
	Content   []byte
	IsBinary  bool // Determines which table to use
}

Content represents file content stored in text or binary content tables. Content is delta-compressed by xpatch, grouped by group_id.

type ContentKey 

type ContentKey struct {
	GroupID   int32
	VersionID int32
}

ContentKey is used for batch lookups.

type ContentVersionPair 

type ContentVersionPair struct {
	VersionID int32
	Content   []byte
}

ContentVersionPair holds a version_id and its content.

type DB 

type DB struct {
	// contains filtered or unexported fields
}

DB holds the database connection pool

func Connect 

func Connect(ctx context.Context, url string) (*DB, error)

Connect establishes a connection to the database with a full connection pool

func ConnectLite 

func ConnectLite(ctx context.Context, url string) (*DB, error)

ConnectLite establishes a lightweight connection (single connection, no pool) Use this for quick operations like metadata lookups

func Default 

func Default() *DB

Default returns the default database instance

func (*DB) Begin 

func (db *DB) Begin(ctx context.Context) (pgx.Tx, error)

Begin starts a transaction

func (*DB) BeginTx 

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

BeginTx starts a transaction with options

func (*DB) BlobExists 

func (db *DB) BlobExists(ctx context.Context, path, commitID string) (bool, error)

BlobExists checks if a blob exists at a specific commit.

func (*DB) Close 

func (db *DB) Close()

Close closes the database connection

func (*DB) CommitExists 

func (db *DB) CommitExists(ctx context.Context, id string) (bool, error)

CommitExists checks if a commit exists

func (*DB) ContentExists 

func (db *DB) ContentExists(ctx context.Context, groupID, versionID int32) (bool, error)

ContentExists checks if content exists in either table.

func (*DB) CountBlobs 

func (db *DB) CountBlobs(ctx context.Context) (int64, error)

CountBlobs returns the total number of blob versions (file refs).

func (*DB) CountCommits 

func (db *DB) CountCommits(ctx context.Context) (int, error)

CountCommits returns the total number of commits

func (*DB) CountContents 

func (db *DB) CountContents(ctx context.Context) (int64, error)

CountContents returns the total number of content entries across both tables.

func (*DB) CountFileRefs 

func (db *DB) CountFileRefs(ctx context.Context) (int64, error)

CountFileRefs returns the total number of file refs.

func (*DB) CountPaths 

func (db *DB) CountPaths(ctx context.Context) (int64, error)

CountPaths returns the number of unique paths in the repository.

func (*DB) CreateBlob 

func (db *DB) CreateBlob(ctx context.Context, b *Blob) error

CreateBlob inserts a new blob into the database. This writes to pgit_paths, pgit_file_refs, and pgit_text_content or pgit_binary_content.

func (*DB) CreateBlobs 

func (db *DB) CreateBlobs(ctx context.Context, blobs []*Blob) error

CreateBlobs inserts multiple blobs efficiently. Blobs should be pre-sorted by path for optimal delta compression.

func (*DB) CreateBlobsForGroup added in v3.3.0 

func (db *DB) CreateBlobsForGroup(ctx context.Context, blobs []*Blob, groupID int32, versionCounter *int32, onProgress func(int)) error

CreateBlobsForGroup inserts all blobs for a single group (path) in one transaction. Large groups are split into chunks of copyChunkSize, each chunk getting its own COPY calls — but all within the same transaction to keep xpatch's delta chain on one connection.

groupID is the pre-registered group_id for this path. versionCounter points to the caller-managed next version_id for this group. onProgress is called after each chunk with the number of blobs in that chunk (may be nil).

func (*DB) CreateBlobsTx added in v3.2.0 

func (db *DB) CreateBlobsTx(ctx context.Context, tx pgx.Tx, blobs []*Blob) error

CreateBlobsTx inserts multiple blobs within an existing transaction. Same logic as CreateBlobs but uses the provided tx instead of creating its own.

func (*DB) CreateCommit 

func (db *DB) CreateCommit(ctx context.Context, c *Commit) error

CreateCommit inserts a new commit into the database

func (*DB) CreateCommitsBatch 

func (db *DB) CreateCommitsBatch(ctx context.Context, commits []*Commit) error

CreateCommitsBatch inserts multiple commits using pgx.CopyFrom for speed Commits must be in order (parents before children)

func (*DB) CreateCommitsBatchTx added in v3.2.0 

func (db *DB) CreateCommitsBatchTx(ctx context.Context, tx pgx.Tx, commits []*Commit) error

CreateCommitsBatchTx inserts multiple commits within an existing transaction.

func (*DB) CreateContent 

func (db *DB) CreateContent(ctx context.Context, c *Content) error

CreateContent inserts content into the appropriate content table.

func (*DB) CreateContentBatch 

func (db *DB) CreateContentBatch(ctx context.Context, contents []*Content) error

CreateContentBatch inserts multiple content entries using COPY for speed. Splits into text and binary batches and writes to respective tables.

func (*DB) CreateContentTx 

func (db *DB) CreateContentTx(ctx context.Context, tx pgx.Tx, c *Content) error

CreateContentTx inserts content within a transaction.

func (*DB) CreateFileRef 

func (db *DB) CreateFileRef(ctx context.Context, ref *FileRef) error

CreateFileRef inserts a new file reference.

func (*DB) CreateFileRefTx 

func (db *DB) CreateFileRefTx(ctx context.Context, tx pgx.Tx, ref *FileRef) error

CreateFileRefTx inserts a new file reference within a transaction.

func (*DB) CreateFileRefsBatch 

func (db *DB) CreateFileRefsBatch(ctx context.Context, refs []*FileRef) error

CreateFileRefsBatch inserts multiple file references using COPY for speed.

func (*DB) CreateFileRefsIndexes added in v3.3.1 

func (db *DB) CreateFileRefsIndexes(ctx context.Context) error

CreateFileRefsIndexes creates the secondary indexes on pgit_file_refs. This is much faster than maintaining indexes during bulk insert because PostgreSQL can sort and bulk-load the B-tree in a single pass.

func (*DB) DeleteBlobsForCommits added in v3.2.0 

func (db *DB) DeleteBlobsForCommits(ctx context.Context, commitIDs []string) error

DeleteBlobsForCommits removes all file_refs and content data for the given commit IDs. For xpatch content tables, it truncates each affected file's chain at the lowest version_id being removed (xpatch cascade-deletes the rest). This must be called BEFORE DeleteCommits since we need the commit data to identify which content versions to clean up.

func (*DB) DeleteCommits added in v3.2.0 

func (db *DB) DeleteCommits(ctx context.Context, commitIDs []string) error

DeleteCommits deletes the given commits from the xpatch chain by PK. In xpatch, deleting a row cascade-deletes all rows with higher _xp_seq in the same group. So deleting the earliest commit in the list effectively truncates the chain from that point forward.

The caller should pass ALL commit IDs that need to be removed (local-only commits, plus any previously-pulled remote commits that are interleaved). Subsequent deletes after the first cascade are harmless no-ops.

After deletion, refreshes xpatch stats for the commits table.

func (*DB) DeleteMetadata 

func (db *DB) DeleteMetadata(ctx context.Context, key string) error

DeleteMetadata removes a metadata key

func (*DB) DeleteRef 

func (db *DB) DeleteRef(ctx context.Context, name string) error

DeleteRef deletes a ref

func (*DB) DeleteSyncState 

func (db *DB) DeleteSyncState(ctx context.Context, remoteName string) error

DeleteSyncState deletes the sync state for a remote

func (*DB) DropFileRefsIndexes added in v3.3.1 

func (db *DB) DropFileRefsIndexes(ctx context.Context) error

DropFileRefsIndexes drops the secondary indexes on pgit_file_refs. The primary key (group_id, commit_id) is kept for COPY conflict detection. Call this before bulk import to avoid random B-tree insertions, then call CreateFileRefsIndexes after import to rebuild them efficiently.

func (*DB) DropSchema 

func (db *DB) DropSchema(ctx context.Context) error

DropSchema drops all pgit tables (use with caution!)

func (*DB) EnsureMetadataTable 

func (db *DB) EnsureMetadataTable(ctx context.Context) error

EnsureMetadataTable creates the metadata table if it doesn't exist

func (*DB) Exec 

func (db *DB) Exec(ctx context.Context, sql string, args ...any) error

Exec executes a query without returning rows

func (*DB) FileExistsInTree 

func (db *DB) FileExistsInTree(ctx context.Context, path, commitID string) (bool, error)

FileExistsInTree checks if a file exists (is not deleted) in the tree at a commit. This finds the latest version of the file at or before commitID and checks if it's not deleted.

func (*DB) FileRefExists 

func (db *DB) FileRefExists(ctx context.Context, groupID int32, commitID string) (bool, error)

FileRefExists checks if a file ref exists at a specific commit.

func (*DB) FindCommitByPartialID 

func (db *DB) FindCommitByPartialID(ctx context.Context, partialID string) (*Commit, error)

FindCommitByPartialID finds a commit by partial ID match. Uses prefix range scan first (fast, uses xpatch PK index), then falls back to suffix match on pgit_file_refs (normal table) if no prefix match found.

func (*DB) FindCommonAncestor 

func (db *DB) FindCommonAncestor(ctx context.Context, commitA, commitB string) (string, error)

FindCommonAncestor finds the common ancestor between two commits

func (*DB) GetAllCommitIDsOrdered added in v3.2.0 

func (db *DB) GetAllCommitIDsOrdered(ctx context.Context) ([]string, error)

GetAllCommitIDsOrdered returns all commit IDs in ascending ULID order. Used for rebuilding markToULID mapping during import resume.

func (*DB) GetAllCommits 

func (db *DB) GetAllCommits(ctx context.Context) ([]*Commit, error)

GetAllCommits retrieves all commits ordered by ID (ULID = time order)

func (*DB) GetAllContentForGroup 

func (db *DB) GetAllContentForGroup(ctx context.Context, groupID int32, isBinary bool) ([]ContentVersionPair, error)

GetAllContentForGroup retrieves all content versions for a single group, ordered by version_id ASC (front-to-back). This is the fastest access pattern for xpatch: a single Index Scan through the delta chain, decompressing sequentially. The caller can reverse the slice in Go for newest-first iteration.

func (*DB) GetAllPaths 

func (db *DB) GetAllPaths(ctx context.Context) ([]string, error)

GetAllPaths returns all unique file paths in the repository. This is very fast as it queries the small pgit_paths table.

func (*DB) GetAllPathsV2 

func (db *DB) GetAllPathsV2(ctx context.Context) ([]string, error)

GetAllPathsV2 retrieves all unique file paths in the repository. This is very fast as it queries the small pgit_paths table. Note: This replaces the old GetAllPaths from blobs.go in schema v2.

func (*DB) GetAllRefs 

func (db *DB) GetAllRefs(ctx context.Context) ([]*Ref, error)

GetAllRefs retrieves all refs

func (*DB) GetAllSyncStates 

func (db *DB) GetAllSyncStates(ctx context.Context) ([]*SyncState, error)

GetAllSyncStates retrieves all sync states

func (*DB) GetBlob 

func (db *DB) GetBlob(ctx context.Context, path, commitID string) (*Blob, error)

GetBlob retrieves a specific blob by path and commit.

func (*DB) GetBlobStats 

func (db *DB) GetBlobStats(ctx context.Context) (map[string]interface{}, error)

GetBlobStats returns statistics about blobs using the v3 schema. Sums stats from both pgit_text_content and pgit_binary_content.

func (*DB) GetBlobsAtCommit 

func (db *DB) GetBlobsAtCommit(ctx context.Context, commitID string) ([]*Blob, error)

GetBlobsAtCommit retrieves all blobs at a specific commit. This returns only files that were changed in that specific commit. Uses a two-step approach: get refs, then batch-fetch content from both tables.

func (*DB) GetBlobsAtCommitMetadata 

func (db *DB) GetBlobsAtCommitMetadata(ctx context.Context, commitID string) ([]*Blob, error)

GetBlobsAtCommitMetadata retrieves all blobs at a specific commit WITHOUT content. This returns only files that were changed in that specific commit (not the full tree).

func (*DB) GetChangedFileRefs 

func (db *DB) GetChangedFileRefs(ctx context.Context, fromCommit, toCommit string) ([]*FileRef, error)

GetChangedFileRefs returns file refs that changed between two commits.

func (*DB) GetChangedFileRefsWithPaths 

func (db *DB) GetChangedFileRefsWithPaths(ctx context.Context, fromCommit, toCommit string) ([]*FileRefWithPath, error)

GetChangedFileRefsWithPaths returns file refs with paths that changed between two commits.

func (*DB) GetChangedFiles 

func (db *DB) GetChangedFiles(ctx context.Context, fromCommit, toCommit string) ([]*Blob, error)

GetChangedFiles returns files that changed between two commits.

func (*DB) GetChangedFilesMetadata 

func (db *DB) GetChangedFilesMetadata(ctx context.Context, fromCommit, toCommit string) ([]*Blob, error)

GetChangedFilesMetadata returns files that changed between two commits WITHOUT content. Use this for operations that only need paths and hashes (e.g., diff --name-only).

func (*DB) GetCommit 

func (db *DB) GetCommit(ctx context.Context, id string) (*Commit, error)

GetCommit retrieves a commit by ID

func (*DB) GetCommitLog 

func (db *DB) GetCommitLog(ctx context.Context, limit int) ([]*Commit, error)

GetCommitLog retrieves commits starting from HEAD in reverse chronological order. Uses a range query on ULID-ordered IDs instead of a recursive CTE, which is much faster on xpatch tables (sequential scan vs random PK lookups).

func (*DB) GetCommitLogFrom 

func (db *DB) GetCommitLogFrom(ctx context.Context, commitID string, limit int) ([]*Commit, error)

GetCommitLogFrom retrieves commits in reverse chronological order starting from a commit. Since commit IDs are ULIDs (lexicographically = chronologically ordered), we use a simple range query instead of walking parent_id chains.

func (*DB) GetCommitStats 

func (db *DB) GetCommitStats(ctx context.Context) (map[string]interface{}, error)

GetCommitStats returns statistics about commits using xpatch.stats() for O(1) performance

func (*DB) GetCommitsAfter added in v3.2.0 

func (db *DB) GetCommitsAfter(ctx context.Context, afterID string) ([]*Commit, error)

GetCommitsAfter returns all commits with ID > afterID, in chronological order (oldest first). If afterID is empty, returns all commits (same as GetAllCommits). Uses a forward scan on the xpatch delta chain — optimal access pattern.

func (*DB) GetCommitsBatch 

func (db *DB) GetCommitsBatch(ctx context.Context, ids []string) (map[string]*Commit, error)

GetCommitsBatch retrieves multiple commits by their IDs in a single query.

func (*DB) GetCommitsBatchByRange 

func (db *DB) GetCommitsBatchByRange(ctx context.Context, ids []string) (map[string]*Commit, error)

GetCommitsBatchByRange retrieves multiple commits using a range scan instead of ANY(). This is much faster on xpatch tables because it scans a contiguous range of the delta chain instead of doing random-access per ID. The ids slice is used to filter results in Go after the range scan.

func (*DB) GetContent 

func (db *DB) GetContent(ctx context.Context, groupID, versionID int32, isBinary bool) ([]byte, error)

GetContent retrieves content by (group_id, version_id). isBinary determines which table to query.

func (*DB) GetContentForFileRef 

func (db *DB) GetContentForFileRef(ctx context.Context, ref *FileRef) ([]byte, error)

GetContentForFileRef retrieves content for a file ref. Returns nil for deleted refs (ContentHash == nil) since they have no content row.

func (*DB) GetContentsBatch 

func (db *DB) GetContentsBatch(ctx context.Context, keys []ContentKey, isBinaryMap map[ContentKey]bool) (map[ContentKey][]byte, error)

GetContentsBatch retrieves multiple contents by their keys. isBinaryMap indicates which keys are binary. Keys not in the map default to text.

func (*DB) GetContentsByGroupID 

func (db *DB) GetContentsByGroupID(ctx context.Context, groupID int32) ([]*Content, error)

GetContentsByGroupID retrieves all content versions for a group. Queries both tables and merges results.

func (*DB) GetContentsForFileRefs 

func (db *DB) GetContentsForFileRefs(ctx context.Context, refs []*FileRef) (map[ContentKey][]byte, error)

GetContentsForFileRefs retrieves content for multiple file refs. Skips deleted refs (ContentHash == nil) since they have no content row.

func (*DB) GetCurrentTree 

func (db *DB) GetCurrentTree(ctx context.Context) ([]*Blob, error)

GetCurrentTree retrieves the tree at HEAD.

func (*DB) GetCurrentTreeMetadata 

func (db *DB) GetCurrentTreeMetadata(ctx context.Context) ([]*Blob, error)

GetCurrentTreeMetadata retrieves the tree metadata at HEAD without content. Use this for operations that only need paths and hashes.

func (*DB) GetDetailedTableSizes 

func (db *DB) GetDetailedTableSizes(ctx context.Context) (*DetailedTableSizes, error)

GetDetailedTableSizes returns sizes for all pgit tables.

func (*DB) GetFileAtCommit 

func (db *DB) GetFileAtCommit(ctx context.Context, path, commitID string) (*Blob, error)

GetFileAtCommit retrieves a file at a specific commit (or the latest version before it). Uses file ref lookup + content fetch from the correct table.

func (*DB) GetFileHistory 

func (db *DB) GetFileHistory(ctx context.Context, path string) ([]*Blob, error)

GetFileHistory retrieves all versions of a file. Uses a two-step approach: get refs, then batch-fetch content from both tables.

func (*DB) GetFileRef 

func (db *DB) GetFileRef(ctx context.Context, groupID int32, commitID string) (*FileRef, error)

GetFileRef retrieves a specific file reference.

func (*DB) GetFileRefAtCommit 

func (db *DB) GetFileRefAtCommit(ctx context.Context, groupID int32, commitID string) (*FileRef, error)

GetFileRefAtCommit retrieves a file ref at or before a specific commit.

func (*DB) GetFileRefHistory 

func (db *DB) GetFileRefHistory(ctx context.Context, groupID int32) ([]*FileRef, error)

GetFileRefHistory retrieves all versions of a file by group_id.

func (*DB) GetFileRefsAtCommit 

func (db *DB) GetFileRefsAtCommit(ctx context.Context, commitID string) ([]*FileRef, error)

GetFileRefsAtCommit retrieves all file refs at a specific commit. This returns only files that were changed in that specific commit.

func (*DB) GetFileRefsAtCommitWithPaths 

func (db *DB) GetFileRefsAtCommitWithPaths(ctx context.Context, commitID string) ([]*FileRefWithPath, error)

GetFileRefsAtCommitWithPaths retrieves file refs with resolved paths.

func (*DB) GetGroupIDByPath 

func (db *DB) GetGroupIDByPath(ctx context.Context, path string) (int32, error)

GetGroupIDByPath retrieves the group_id for a specific path. Returns 0 and nil error if the path doesn't exist.

func (*DB) GetHead 

func (db *DB) GetHead(ctx context.Context) (string, error)

GetHead returns the HEAD commit ID

func (*DB) GetHeadCommit 

func (db *DB) GetHeadCommit(ctx context.Context) (*Commit, error)

GetHeadCommit retrieves the commit that HEAD points to

func (*DB) GetImportedPaths added in v3.2.0 

func (db *DB) GetImportedPaths(ctx context.Context) (map[string]bool, error)

GetImportedPaths returns the set of paths that have at least one file ref. Used during import resume to skip paths whose blobs are already imported.

func (*DB) GetLatestCommitID 

func (db *DB) GetLatestCommitID(ctx context.Context) (string, error)

GetLatestCommitID returns the ID of the latest commit (by ULID order)

func (*DB) GetMetadata 

func (db *DB) GetMetadata(ctx context.Context, key string) (string, error)

GetMetadata retrieves a metadata value by key

func (*DB) GetNextVersionID 

func (db *DB) GetNextVersionID(ctx context.Context, groupID int32) (int32, error)

GetNextVersionID returns the next version_id for a group. This is used when creating new file refs.

func (*DB) GetNextVersionIDTx 

func (db *DB) GetNextVersionIDTx(ctx context.Context, tx pgx.Tx, groupID int32) (int32, error)

GetNextVersionIDTx returns the next version_id within a transaction.

func (*DB) GetOrCreatePath 

func (db *DB) GetOrCreatePath(ctx context.Context, path string) (int32, error)

GetOrCreatePath returns the group_id for a path, creating it if needed. This is the primary method for getting a group_id during blob creation.

func (*DB) GetOrCreatePathTx 

func (db *DB) GetOrCreatePathTx(ctx context.Context, tx pgx.Tx, path string) (int32, error)

GetOrCreatePathTx returns the group_id for a path within a transaction.

func (*DB) GetOrCreatePathsBatch 

func (db *DB) GetOrCreatePathsBatch(ctx context.Context, paths []string) (map[string]int32, error)

GetOrCreatePathsBatch handles multiple paths efficiently. Returns a map of path -> group_id.

func (*DB) GetPath 

func (db *DB) GetPath(ctx context.Context, groupID int32) (string, error)

GetPath retrieves a path by group_id.

func (*DB) GetPathsByGroupIDs 

func (db *DB) GetPathsByGroupIDs(ctx context.Context, groupIDs []int32) (map[int32]string, error)

GetPathsByGroupIDs retrieves multiple paths by group_ids. Returns a map of group_id -> path.

func (*DB) GetRef 

func (db *DB) GetRef(ctx context.Context, name string) (*Ref, error)

GetRef retrieves a ref by name

func (*DB) GetRepoPath 

func (db *DB) GetRepoPath(ctx context.Context) string

GetRepoPath returns the stored repository path, or empty string if not set

func (*DB) GetRepoStatsFast 

func (db *DB) GetRepoStatsFast(ctx context.Context) (*RepoStats, error)

GetRepoStatsFast returns repository statistics using xpatch.stats() for O(1) performance. This version supports the v3 schema with split text/binary content tables.

func (*DB) GetSchemaVersion 

func (db *DB) GetSchemaVersion(ctx context.Context) (int, error)

GetSchemaVersion returns the current schema version from the database. Returns 1 for legacy schemas that don't have a version set.

func (*DB) GetSyncState 

func (db *DB) GetSyncState(ctx context.Context, remoteName string) (*SyncState, error)

GetSyncState retrieves the sync state for a remote

func (*DB) GetTreeAtCommit 

func (db *DB) GetTreeAtCommit(ctx context.Context, commitID string) ([]*Blob, error)

GetTreeAtCommit retrieves the full tree (all files) at a commit. Uses a two-step approach: get refs with DISTINCT ON, then batch-fetch content.

func (*DB) GetTreeMetadataAtCommit 

func (db *DB) GetTreeMetadataAtCommit(ctx context.Context, commitID string) ([]*Blob, error)

GetTreeMetadataAtCommit retrieves the full tree metadata (all files) at a commit WITHOUT loading content. This is much faster than GetTreeAtCommit when you only need paths and hashes (e.g., for status, ls-tree). The returned Blobs have Content set to nil.

func (*DB) GetTreeRefsAtCommit 

func (db *DB) GetTreeRefsAtCommit(ctx context.Context, commitID string) ([]*FileRef, error)

GetTreeRefsAtCommit retrieves the full tree (latest version per path <= commitID). This is the core query for getting the state of the repository at a commit.

func (*DB) GetTreeRefsAtCommitWithPaths 

func (db *DB) GetTreeRefsAtCommitWithPaths(ctx context.Context, commitID string) ([]*FileRefWithPath, error)

GetTreeRefsAtCommitWithPaths retrieves the full tree with resolved paths. This is a metadata-only query - no content is fetched.

func (*DB) GetXpatchStats 

func (db *DB) GetXpatchStats(ctx context.Context, tableName string) (*XpatchStats, error)

GetXpatchStats retrieves compression statistics for a table

func (*DB) InitSchema 

func (db *DB) InitSchema(ctx context.Context) error

InitSchema creates the pgit schema in the database

func (*DB) IsConnected 

func (db *DB) IsConnected() bool

IsConnected returns true if the database is connected

func (*DB) IsSchemaAtLeast 

func (db *DB) IsSchemaAtLeast(ctx context.Context, minVersion int) (bool, error)

IsSchemaAtLeast checks if the database schema is at least the given version.

func (*DB) Ping 

func (db *DB) Ping(ctx context.Context) error

Ping tests the database connection

func (*DB) Pool 

func (db *DB) Pool() *pgxpool.Pool

Pool returns the underlying connection pool

func (*DB) PreRegisterPaths added in v3.3.0 

func (db *DB) PreRegisterPaths(ctx context.Context, paths []string) (map[string]int32, error)

PreRegisterPaths inserts all paths into pgit_paths in a single transaction and returns the complete path -> group_id mapping. This eliminates per-worker path lookup queries during import. Paths that already exist are returned as-is.

func (*DB) Query 

func (db *DB) Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)

Query executes a query and returns rows

func (*DB) QueryRow 

func (db *DB) QueryRow(ctx context.Context, sql string, args ...any) pgx.Row

QueryRow executes a query and returns a single row

func (*DB) RefExists 

func (db *DB) RefExists(ctx context.Context, name string) (bool, error)

RefExists checks if a ref exists

func (*DB) ResetImportGUCs added in v3.3.0 

func (db *DB) ResetImportGUCs(ctx context.Context) error

ResetImportGUCs restores default PostgreSQL session settings after import.

func (*DB) SchemaExists 

func (db *DB) SchemaExists(ctx context.Context) (bool, error)

SchemaExists checks if the pgit schema exists

func (*DB) SearchContent 

func (db *DB) SearchContent(ctx context.Context, opts SearchContentOptions) ([]*SearchContentResult, error)

SearchContent searches text file contents using parallel-by-group fetching. Binary files are excluded from search results. Strategy:

  1. Load all matching file refs into memory
  2. Group by group_id, build version→ref lookup
  3. Worker goroutines process groups in parallel, each issuing a single server-side regex query per group for optimal xpatch delta-chain access

func (*DB) SearchContentAtCommit 

func (db *DB) SearchContentAtCommit(ctx context.Context, commitID string, opts SearchContentOptions) ([]*SearchContentResult, error)

SearchContentAtCommit searches text file contents at a specific commit. This searches the tree state at that commit (latest version of each file <= commitID). Binary files are excluded from search results.

func (*DB) SetHead 

func (db *DB) SetHead(ctx context.Context, commitID string) error

SetHead sets the HEAD to point to a commit

func (*DB) SetImportGUCs added in v3.3.0 

func (db *DB) SetImportGUCs(ctx context.Context) error

SetImportGUCs configures session-level PostgreSQL settings optimized for bulk import on ALL connections in the pool. These settings trade crash safety for speed — safe because import can resume from the temp file if PostgreSQL crashes.

func (*DB) SetMetadata 

func (db *DB) SetMetadata(ctx context.Context, key, value string) error

SetMetadata sets a metadata key-value pair (upsert)

func (*DB) SetRef 

func (db *DB) SetRef(ctx context.Context, name, commitID string) error

SetRef creates or updates a ref

func (*DB) SetRepoPath 

func (db *DB) SetRepoPath(ctx context.Context, path string) error

SetRepoPath stores the repository working directory path

func (*DB) SetSchemaVersion 

func (db *DB) SetSchemaVersion(ctx context.Context, version int) error

SetSchemaVersion sets the schema version in the database.

func (*DB) SetSyncState 

func (db *DB) SetSyncState(ctx context.Context, remoteName string, lastCommitID *string) error

SetSyncState creates or updates the sync state for a remote

func (*DB) URL 

func (db *DB) URL() string

URL returns the connection URL

func (*DB) WithTx 

func (db *DB) WithTx(ctx context.Context, fn func(tx pgx.Tx) error) error

WithTx executes a function within a transaction

type DetailedTableSizes 

type DetailedTableSizes struct {
	Commits       int64
	Paths         int64
	FileRefs      int64
	TextContent   int64
	BinaryContent int64
	Refs          int64
	SyncState     int64
	Metadata      int64
	Indexes       int64
}

GetDetailedTableSizes returns detailed size information for each table.

type FileRef 

type FileRef struct {
	GroupID       int32
	CommitID      string
	VersionID     int32
	ContentHash   []byte // 16 bytes BLAKE3, nil = deleted
	Mode          int
	IsSymlink     bool
	SymlinkTarget *string
	IsBinary      bool
}

FileRef represents a file reference at a specific commit. This is the metadata-only representation without actual content.

type FileRefWithPath 

type FileRefWithPath struct {
	Path          string
	GroupID       int32
	CommitID      string
	VersionID     int32
	ContentHash   []byte
	Mode          int
	IsSymlink     bool
	SymlinkTarget *string
	IsBinary      bool
}

FileRefWithPath combines FileRef with resolved path. Used when returning results that need the actual file path.

type Path 

type Path struct {
	GroupID int32
	Path    string
}

Path represents a file path in the path registry. Each unique path gets a unique group_id for efficient storage.

type Ref 

type Ref struct {
	Name     string
	CommitID string
}

Ref represents a named reference to a commit

type RepoStats 

type RepoStats struct {
	// Commit stats
	TotalCommits  int64
	FirstCommitID *string
	LastCommitID  *string

	// File stats
	TotalBlobs       int64 // Total file refs (from pgit_file_refs)
	UniqueFiles      int64 // Unique paths (from pgit_paths)
	TotalContentSize int64 // Raw content size (sum from both content tables via xpatch.stats)
	DeletedEntries   int64

	// Table sizes from PostgreSQL (pg_table_size = heap + TOAST + FSM)
	CommitsTableSize       int64
	PathsTableSize         int64
	FileRefsTableSize      int64
	TextContentTableSize   int64
	BinaryContentTableSize int64
	RefsTableSize          int64
	MetadataTableSize      int64
	SyncStateTableSize     int64
	TotalIndexSize         int64

	// xpatch compressed bytes (compressed_size_bytes from xpatch.stats)
	// This is the actual data after delta compression, excluding PG overhead.
	XpatchCompressedCommits int64
	XpatchCompressedText    int64
	XpatchCompressedBinary  int64

	// Normal table raw data bytes (computed from column widths, no PG overhead)
	NormalRawFileRefs int64
	NormalRawPaths    int64
	NormalRawRefs     int64
	NormalRawMetadata int64

	// Legacy field for compatibility (sum of paths + file_refs + both content tables)
	BlobsTableSize int64
}

RepoStats contains all repository statistics for schema v3.

type SearchContentOptions 

type SearchContentOptions struct {
	// Pattern is the regex pattern to search for (PostgreSQL regex syntax).
	Pattern string
	// IgnoreCase enables case-insensitive matching.
	IgnoreCase bool
	// PathPattern is an optional glob pattern to filter files by path.
	PathPattern string
	// CommitID limits search to files at or before this commit.
	// Empty string means search all versions.
	CommitID string
	// Limit is the maximum number of matching files to return.
	// 0 means no limit.
	Limit int
}

SearchContentOptions configures content search behavior.

type SearchContentResult 

type SearchContentResult struct {
	Path      string
	GroupID   int32
	CommitID  string
	VersionID int32
	Content   []byte
}

SearchContentResult represents a file that matched the search.

type SyncState 

type SyncState struct {
	RemoteName   string
	LastCommitID *string
	SyncedAt     time.Time
}

SyncState represents the sync state with a remote

type XpatchStats 

type XpatchStats struct {
	TotalRows        int64
	TotalGroups      int64
	KeyframeCount    int64
	DeltaCount       int64
	RawSizeBytes     int64
	CompressedBytes  int64
	CompressionRatio float64
	CacheHits        int64
	CacheMisses      int64
	AvgDepth         float64 // avg_compression_depth: average delta distance (versions back) per reconstruction
}

XpatchStats represents compression statistics from pg-xpatch

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.