Add export options and in-memory SQL export

[welpie21]

JS-parity gap

The JS SDK's export(options) (packages/sdk/src/api/surreal.ts, SqlExportOptions) can filter what an export contains (users, accesses, params, functions, analyzers, apis, buckets, modules, configs, sequences, versions, records, and tables: boolean | string[]) and returns the export as a string. The Java SDK only offered exportSql(String path): file-path only, no options, no in-memory result.

Reproduction

On the embedded memory engine: created person/city records, a DEFINE FUNCTION and a DEFINE PARAM, then called exportSql(path). The export always contains all sections (OPTION, PARAMS, FUNCTIONS, table definitions, and INSERT table data) and there is no API to exclude any of them, nor to obtain the export without going through a file.

Rust SDK capability (surrealdb 3.1.5)

src/method/export.rs supports both halves of the gap:

• export(target).with_config() exposes builder filters: users, accesses, params, functions, analyzers, apis, buckets, modules, configs, versions, records, and tables(impl Into<TableConfig>) (accepting bool or a Vec<String> table list).
• export(()) resolves to a Backup stream of byte chunks, i.e. an in-memory export.

Note: the JS sequences option has no counterpart in the Rust 3.1.5 with_config() builder, so it is not exposed here (it stays at its server default, included). Everything else in the JS option set maps 1:1.

Fix

• New com.surrealdb.ExportOptions builder covering exactly the Rust SDK's config options: users, accesses, params, functions, analyzers, apis, buckets, modules, configs, versions, records, tables(boolean) / tables(String...). Defaults mirror the server defaults (everything on except versions).
• Surreal.exportSql(String path, ExportOptions options) — filtered export to a file.
• Surreal.exportSql(ExportOptions options) and Surreal.exportSql() — in-memory export returned as a String, collected from the Rust byte stream.
• Existing exportSql(String path) is unchanged.
• JNI plumbing (exportSqlOptions / exportSqlString in src/main/rust/surreal.rs): the boolean options travel as an int bitmask (constants kept in sync between ExportOptions.java and surreal.rs) plus a nullable String[] for an explicit table list, which takes precedence over the all-tables bit.

Tests

New ExportOptionsTests (memory engine, export/import is not supported over WebSocket):

• default export contains records and definitions;
• records(false) drops INSERT data but keeps DEFINE TABLE;
• tables("person") limits which tables appear; tables(false) drops all tables while keeping functions;
• functions(false).params(false) drops those definitions;
• string export is byte-identical to file export for the same options;
• round-trip: export to string, write to temp file, importSql, records and function intact.

Full ./gradlew test suite passes; spotlessApply and cargo fmt --check clean.

🤖 Generated with Claude Code

[emmanuel-keller]

Review — approve with nits.

Plumbing checks out end-to-end: the flag bits match bit-for-bit between ExportOptions and the Rust EXPORT_FLAG_*, every flag maps to the right with_config() setter, and the defaults match Config::default() (all-true except versions, with sequences staying on — accurately documented). Mid-stream stream errors propagate (no truncated string is ever returned) and non-UTF-8 surfaces as a clean exception. No native handle allocated, so no leak.

Test gaps: no empty-database export; no non-ASCII/multibyte content test (the one case that actually exercises the new from_utf8/new_string path); several flags (versions(true), users/accesses/analyzers/apis/buckets/modules/configs) untested (mechanically identical to the tested ones, so low risk).

[emmanuel-keller]

Worth a Javadoc note here: the in-memory variant buffers the whole export (Rust Vec<u8> → String → JVM UTF-16, so ~3x peak memory), there's no size guard, and new_string can't represent a >2 GB modified-UTF-8 payload. It's a reasonable tradeoff (matches the JS SDK's string return, and the file overload exists for large DBs) — just point large exports at exportSql(String, ...).

[welpie21]

Added in cc1ade3: both in-memory variants (exportSql() and exportSql(ExportOptions)) now carry a Javadoc note that the whole export is buffered in memory (native byte buffer then copied to a UTF-16 String, so roughly 3x peak memory), that there is no size guard, that exports larger than 2 GB cannot be represented as a single Java string, and that large databases should use the file overloads exportSql(String) / exportSql(String, ExportOptions).

[emmanuel-keller]

tables(String...) with zero args produces a non-null empty array → TableConfig::Some(vec![]) → exports no tables. new ExportOptions().tables() returning nothing is surprising; consider treating an empty list as "all", or documenting it. (Also allTables stays true here, so FLAG_TABLES is still set but ignored native-side when the list is Some — dead in that path.)

[welpie21]

Fixed in cc1ade3. tables() with zero args is now equivalent to tables(true) — it exports all tables instead of none — and the Javadoc documents that empty means all. The dead-path issue is resolved too: setting a non-empty list now clears the all-tables flag, so FLAG_TABLES is never set alongside an explicit list (the native side already gives the list precedence; the Java side just no longer sends the ignored bit). Added tablesEmptyVarargs_exportsAllTables to pin the behaviour, including that a zero-arg call replaces a previously set narrower list.

[emmanuel-keller]

exportSql(String, ExportOptions) / exportSql(ExportOptions) throw a raw NPE if options is null (the no-arg overload is safe). Worth a @throws NullPointerException note or an explicit guard.

[welpie21]

Fixed in cc1ade3: both exportSql(String, ExportOptions) and exportSql(ExportOptions) now guard with Objects.requireNonNull(options, "options") and document @throws NullPointerException if options is null. Added nullOptions_throwNullPointerException covering both overloads.