Documentation
¶
Overview ¶
Package assetloader implements a native Go asset/file loader that binds local binary and text files as pgx query parameters during database seeding. Files are bound as actual []byte query parameters — never converted to SQL text literals — so binary data stays byte-exact and no escaping is needed.
Manifests are small YAML files (assets.yaml) that describe, per file, the SQL call to invoke and the named placeholders for :bytes, :filename, and any static column values. Manifests live inside directories that follow the same {priority}_{sequence}_{name} naming convention used by the sqldir reader, so asset-loading steps can be interleaved with SQL scripts in a migrate-apply run.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildQuery ¶
func BuildQuery(call string, fileBytes []byte, filename string, staticParams map[string]string) (query string, args []any, err error)
BuildQuery converts a SQL call that uses :name named placeholders into a pgx-compatible positional-parameter query ($1, $2, …) and returns the corresponding argument slice.
Built-in placeholders:
- :bytes → fileBytes ([]byte)
- :filename → filename (string, base name only)
- :any_key → staticParams["any_key"] (string)
A placeholder that appears more than once maps to the same $N. An unknown placeholder (not built-in and not in staticParams) returns an error. PostgreSQL cast syntax (::type) is left untouched.
func ExecuteItem ¶
ExecuteItem reads the asset file referenced by item.Entry.File (which is the absolute path set by ScanDir) and executes the configured SQL call via conn. The file's raw bytes are bound as a []byte parameter — no encoding or escaping.
Types ¶
type Item ¶
type Item struct {
// Priority and Sequence come from the parent directory's naming pattern.
Priority int
Sequence uint
// DirName is the last path component of the manifest's directory.
DirName string
// Dir is the absolute path to the directory containing assets.yaml and files.
Dir string
// Entry is the parsed manifest entry.
Entry ManifestEntry
}
Item combines a manifest entry with its ordering metadata and the resolved directory where the manifest and asset file reside.
func ScanDir ¶
ScanDir recursively walks baseDir, finds all assets.yaml manifests, resolves each file entry (skipping symlinks and path traversal), and returns the resulting Items sorted by (Priority, Sequence, DirName).
Each manifest must reside in a directory whose name follows the {priority}_{sequence}_{name} pattern. Manifests in directories that do not follow this convention are assigned Priority=0, Sequence=0 and sorted last.
type ManifestEntry ¶
type ManifestEntry struct {
// File is the path to the asset file, relative to the manifest directory.
File string `yaml:"file"`
// Call is the SQL statement to execute. Use :bytes for file content,
// :filename for the base name, and :param_name for static params.
Call string `yaml:"call"`
// Params holds optional static named parameters referenced in Call.
Params map[string]string `yaml:"params,omitempty"`
}
ManifestEntry describes a single file to load from an assets.yaml manifest.
func LoadManifest ¶
func LoadManifest(dir string) ([]ManifestEntry, error)
LoadManifest reads and parses the assets.yaml file in dir, returning the ordered list of manifest entries. Returns an error if assets.yaml is absent or contains invalid YAML.
Source Files