ferret

What the FQL language and runtime provide

Ferret is a declarative first, expression oriented embedded language and runtime for data automation. The README explains that FQL, the Ferret Query Language, combines querying, transformation, synchronization, and structured results with host defined values and capabilities. Applications can embed the runtime and decide exactly which functions, modules, data, and external operations a program is allowed to use, which makes the language fit for controlled automation rather than as a general purpose scripting tool. The design keeps a declarative core and adds domain oriented orchestration plus constrained mutable state for automation that cannot be expressed as a pure data transformation. The feature list expands on this. There is a purpose built declarative language for querying, transforming, synchronizing, and automating structured data. There is an embeddable Go runtime with reusable compiled plans and isolated execution sessions. There is a capability based host value system for exposing application objects, resources, and external systems directly to FQL. There is a unified query model that covers browsers, APIs, databases, documents, and custom data sources. The runtime is extensible through namespaced functions, modules, hooks, and custom value types. It supports event driven synchronization and dispatch for asynchronous and stateful resources, and it manages the lifecycle of files, connections, cursors, streams, and other host resources. Finally, a bytecode virtual machine and portable programs allow efficient repeated execution and precompiled artifacts. These pieces together describe a tool meant to be embedded inside a larger Go application that needs repeatable data workflows.

Getting started with the native v2 API

The README covers Ferret v2, which is in alpha on the branch that holds the upcoming release, while the stable v1 lives on its own branch. Getting the library is a single Go command that fetches the v2 module at latest. There are two ways to start with v2: the native v2 API, which the README recommends for new projects, and a compat module, which it recommends as a first migration step for existing v1 integrations. The native flow is described as engine, compile query, create session, and run. The README shows a Go example that creates an engine with engine.New, defers its close, compiles a query with eng.Compile, creates a session with plan.NewSession, defers the session close, and runs it with session.Run before printing the content. That short program is the entire minimal path from embedding the runtime to executing a query. The README also points to a playground where you can try the new syntax and to blog posts that explain the design behind the new runtime, the new execution model, and the new language capabilities. Because v2 is alpha, the README warns that some APIs and language features may still change before the stable v2 release, and it frames the current builds as intended for early adopters, experimentation, and feedback rather than production use.

Migrating from v1 and the alpha status

For teams already on v1, the README describes a two stage migration. The first stage uses the ferret migrate command from the project's command line tool, run from anywhere inside the application's Go module. The command supports a dry run that lists the files that would change, a print mode that shows a unified diff without writing, and the plain command that applies the migration. What it does is rewrite the documented v1 imports to their v2 compatibility packages, update go.mod and go.sum as those rewrites require, and format the changed Go files. Generated, vendored, and nested module files are left untouched, and unsupported v1 imports are reported as manual follow up. If the project vendors dependencies, you run go mod vendor after applying the migration. The README is clear that this is only the mechanical compatibility stage: the command does not convert application logic to the native v2 API, nor does it migrate drivers and other unsupported v1 packages. Running it again on an already migrated compatibility project is a no op and does not upgrade the Ferret v2 dependency merely because the CLI is newer. After applying it, you address reported follow ups, build and test, then migrate to the native v2 API over time. The compatibility layer is called a migration aid rather than the long term preferred API, and new projects are told to use the native v2 packages directly. The maintainers section links to a versioned core API reference for people working on the project itself.

Editorial conclusion

Ferret is a Go data automation language under the Apache 2.0 license that you add with go get for the v2 module, and it offers a ferret migrate command to rewrite v1 imports to the v2 compatibility packages.