Flight SQL Server

The standalone server lives in crates/nexus-server. Run it when clients need a remote Arrow Flight SQL endpoint instead of an embedded Rust API.

Build and start

Build the nexus-server package and its datafusion_nexus_server binary:

cargo build --release -p nexus-server --all-features --bin datafusion_nexus_server

Every selected GPU needs an explicit device profile. For a single-GPU local server, create server.toml in the repository root:

[[admission.device_profiles]]
device_ordinal = 0

Then start the server on localhost. The development helper enables its local Iceberg defaults unless NEXUS_RUN_SERVER_ICEBERG=0 is set:

export NEXUS_SERVER_CONFIG_FILE="$PWD/server.toml"
export NEXUS_SERVER_BIND=127.0.0.1:50051
export NEXUS_RUN_SERVER_ICEBERG=0

flock /tmp/cudf-gpu.lock bash scripts/dev/run_server.sh

From another terminal, verify the endpoint with the repository client:

cargo run -p nexus-tools --all-features -- \
  flight-sql-query http://127.0.0.1:50051 "SELECT 1 AS one"

The expected result is a column named one containing 1. Authentication is disabled by default, so keep this setup on a trusted local interface. See Configuration before exposing the endpoint or selecting more GPUs.

Start the citation demo server

The graph examples use an Iceberg REST catalog backed by RustFS. Start the fixture, load the citation network, and reuse the server.toml profile above:

docker compose -f fixture/iceberg-local/docker-compose.yml up -d
fixture/fixture.sh iceberg rest load \
  --workload citation_network \
  --load-mode add-files

export NEXUS_SERVER_CONFIG_FILE="$PWD/server.toml"
export NEXUS_RUN_SERVER_ICEBERG=1
export NEXUS_SERVER_CUGRAPH_ENABLED=true
export NEXUS_SERVER_BIND=127.0.0.1:50051
export DATAFUSION_CATALOG_DEFAULT_CATALOG=datafusion
export DATAFUSION_CATALOG_DEFAULT_SCHEMA=public
export NEXUS_ICEBERG_CATALOG_KIND=rest
export NEXUS_ICEBERG_CATALOG_NAME=lake
export NEXUS_ICEBERG_NAMESPACE=citation_network
export NEXUS_ICEBERG_WAREHOUSE=s3://lakehouse/warehouse
export NEXUS_ICEBERG_REST_URI=http://localhost:8181
export NEXUS_ICEBERG_S3_ENDPOINT=http://localhost:9000
export NEXUS_ICEBERG_S3_REGION=us-east-1
export NEXUS_ICEBERG_S3_PATH_STYLE=true
export NEXUS_ICEBERG_S3_ACCESS_KEY_ID=nexusadmin
export NEXUS_ICEBERG_S3_SECRET_ACCESS_KEY=nexusadmin
export NEXUS_SERVER_WORKSPACE_CATALOG=datafusion
export NEXUS_SERVER_WORKSPACE_SCHEMA=public
export NEXUS_SERVER_WORKSPACE_BACKING_CATALOG=lake
export NEXUS_SERVER_WORKSPACE_BACKING_SCHEMA=citation_network
export NEXUS_SERVER_WORKSPACE_BACKING_ALIASES=citation_edges,citation_edges_by_dst,papers,paper_authors,paper_fos

flock /tmp/cudf-gpu.lock bash scripts/dev/run_server.sh

The startup snapshot should report iceberg_enabled=true, cugraph_enabled=true, and a non-zero cugraph_registry_algorithm_count. The demo dataset page lists the available tables.

Connect with ADBC

Use an Apache Arrow ADBC Flight SQL driver from application code. The Python DB-API wrapper requires both the Flight SQL driver and PyArrow:

python -m pip install adbc-driver-flightsql pyarrow

from adbc_driver_flightsql import dbapi


with dbapi.connect(uri="grpc://127.0.0.1:50051") as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT 1 AS one")
        result = cur.fetch_arrow_table()

The same endpoint works with other ADBC language bindings. Keep pooling, timeouts, authentication, and result conversion in the client service.

Use an interactive client

Choose either client for an interactive session.

DataBow

databow exercises the ADBC driver path:

databow --driver flightsql --uri grpc://127.0.0.1:50051

arrow_cli

arrow_cli connects directly over Flight SQL:

arrow_cli --host 127.0.0.1 --port 50051 --timeout 120

Flight SQL accepts ordinary DataFusion SET statements, but rejects SET datafusion_nexus.*; server resource policy comes from ServerConfig. Native execution requires a CUDA-capable host and the runtime libraries for the enabled Cargo features. Unsupported GPU operators fail closed rather than falling back to the CPU.