feat: add remote catalogs and Python and TypeScript bindings (#4195)

Add a `Catalog` trait and `RemoteCatalog` for managing databases,
exposed through Rust, synchronous/asynchronous Python, and TypeScript. A
remote catalog represents the server's root namespace, and each database
is one child namespace. Create/connect return ordinary LanceDB
connections, so existing table APIs work unchanged.

## Rust API

`Catalog` is an object-safe async trait with `create_database`,
`connect_database`, `list_databases`, and `drop_database`. Backend
create/connect methods return `Arc<dyn Database>`; the public
`CatalogConnection` wraps them as `Connection` values and shares its
embedding registry with those connections. `RemoteCatalog` implements
the trait; `connect_catalog` is the convenience builder, available with
the `remote` feature.

```rust
use lancedb::catalog::{
    CreateDatabaseRequest, DropDatabaseRequest, ListDatabasesRequest,
};

let catalog = lancedb::connect_catalog("https://my-server.example")
    .api_key("my-api-key")
    .execute()
    .await?;

let db = catalog.create_database(
    CreateDatabaseRequest::new("analytics").exist_ok(true),
).await?;
let connected = catalog.connect_database("analytics").await?;
let page = catalog.list_databases(
    ListDatabasesRequest::default().limit(20),
).await?;
// page.databases: Vec<String>; page.page_token: Option<String>
catalog.drop_database(
    DropDatabaseRequest::new("analytics").ignore_missing(true),
).await?;
```

Create/drop also accept a plain name for default behavior, e.g.
`catalog.create_database("analytics").await?`. Existing names fail
creation unless `exist_ok` is enabled; missing names fail drop unless
`ignore_missing` is enabled. Drop always requires an empty database.

## Python API

```python
import lancedb

catalog = lancedb.connect_catalog(
    "https://my-server.example", api_key="my-api-key"
)
db = catalog.create_database("analytics", exist_ok=True)
connected = catalog.connect_database("analytics")
page = catalog.list_databases(limit=20)
# page.databases: list[str]; page.page_token: Optional[str]
if page.page_token is not None:
    next_page = catalog.list_databases(limit=20, page_token=page.page_token)
catalog.drop_database("analytics", ignore_missing=True)
```

`connect_catalog` returns `Catalog`; create/connect return the existing
`DBConnection` API. The async equivalent is `catalog = await
lancedb.connect_catalog_async(...)`, returning `AsyncCatalog`; await
each of the same four methods, with create/connect returning
`AsyncConnection`.

## TypeScript API

```typescript
import { connectCatalog } from "@lancedb/lancedb";

const catalog = await connectCatalog("https://my-server.example", {
  apiKey: "my-api-key",
});
const db = await catalog.createDatabase("analytics", { existOk: true });
const connected = await catalog.connectDatabase("analytics");
const page = await catalog.listDatabases({ limit: 20 });
// page.databases: string[]; page.pageToken?: string
if (page.pageToken !== undefined) {
  const nextPage = await catalog.listDatabases({
    limit: 20, pageToken: page.pageToken,
  });
}
await catalog.dropDatabase("analytics", { ignoreMissing: true });
```

Create/connect return the existing `Connection` API. All four methods
are asynchronous.

## REST mapping

All paths below are relative to the catalog endpoint. `{name}` is the
logical database name encoded as one URL path component. The default
namespace delimiter is `$`, so the root identifier is encoded as `%24`.

| Catalog operation | Existing REST route | Request |
| --- | --- | --- |
| `create_database(name)` | `POST /v1/namespace/{name}/create` |
`{"mode":"Create"}`; `exist_ok=true` sends `{"mode":"ExistOk"}` |
| `connect_database(name)` | `POST /v1/namespace/{name}/describe` |
`{}`; verifies existence before returning a scoped connection |
| `list_databases(...)` | `GET /v1/namespace/%24/list` | Optional
`limit` and `page_token` query parameters |
| `drop_database(name)` | `POST /v1/namespace/{name}/drop` |
`{"mode":"Fail","behavior":"Restrict"}`; `ignore_missing=true` changes
mode to `"Skip"` |

For example, database `team/search` uses
`/v1/namespace/team%2Fsearch/create`. A paginated root listing can use
`/v1/namespace/%24/list?limit=20&page_token=a%2Fb`. The list response
retains the existing namespace wire shape,
`{"namespaces":["analytics"],"page_token":"next"}`; the SDK exposes
`namespaces` as `databases` and preserves the opaque continuation token.
An absent or empty token ends pagination. Page limits must be between 1
and 2147483647. Create/drop accept a namespace JSON response or HTTP
204.

Catalog management requests omit both `x-lancedb-database` and
`x-lancedb-database-prefix`, including values supplied through static or
dynamic headers. Returned database connections set `x-lancedb-database`
to the exact logical name and keep independent scope. API keys, OAuth or
dynamic authentication, client settings, table read consistency
settings, and an optional SQL endpoint override carry over to those
connections. OAuth cannot be combined with an API key or a custom header
provider.

For SQL through an HTTPS catalog, configure the existing SQL endpoint
contract with Rust
`.sql_host_override("grpc+tls://sql.example.com:10026")` or Python
`sql_host_override="grpc+tls://sql.example.com:10026"`. TypeScript
catalog options expose the same setting as `sqlHostOverride`. It is
inherited by created/connected databases, retained by Python connection
serialization, and initialized lazily when SQL is executed.

Create HTTP 409 maps to `DatabaseAlreadyExists`; connect/drop HTTP 404
maps to `DatabaseNotFound`, except that `ignore_missing` suppresses a
missing-database drop. Other server errors propagate. The server
enforces restricted deletion; the client never requests cascading
deletion.

Database names preserve literal slashes as part of one name. They must
be nonempty ASCII, with no control characters, surrounding whitespace,
or configured namespace delimiter, and cannot be `.` or `..`. Endpoints
must be HTTP(S) URLs without embedded credentials, query parameters, or
fragments.

## Scope

This PR adds the client API and reuses existing namespace endpoints.
Local catalogs, `__catalog` storage, location generation/sanitization,
and `__manifest` lifecycle support remain deferred; the Lance dependency
is unchanged.

The PR also runs macOS Node tests serially to avoid existing
resource-contention timeouts reproduced across recent main runs.

---------

Co-authored-by: Xuanwo <github@xuanwo.io>

nodejs/__test__/catalog.test.ts

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+import * as http from "http";
+import { Catalog, connectCatalog } from "../lancedb";
+
+type RecordedRequest = {
+  url: string;
+  headers: http.IncomingHttpHeaders;
+  body: Record<string, unknown>;
+};
+
+async function withCatalog(
+  responses: [number, unknown][],
+  callback: (catalog: Catalog, requests: RecordedRequest[]) => Promise<void>,
+) {
+  const requests: RecordedRequest[] = [];
+  const server = http.createServer(async (req, res) => {
+    const chunks: Buffer[] = [];
+    for await (const chunk of req) chunks.push(Buffer.from(chunk));
+    const body = Buffer.concat(chunks).toString();
+    requests.push({
+      url: req.url ?? "",
+      headers: req.headers,
+      body: body ? JSON.parse(body) : {},
+    });
+    const [status, response] = responses.shift() ?? [
+      500,
+      { error: "Unexpected request" },
+    ];
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(status === 204 ? undefined : JSON.stringify(response));
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  if (!address || typeof address === "string")
+    throw new Error("Missing server address");
+  try {
+    const catalog = await connectCatalog(`http://127.0.0.1:${address.port}`, {
+      apiKey: "secret",
+      sqlHostOverride: "grpc+tls://sql.example.com:10026",
+      clientConfig: {
+        extraHeaders: {
+          "X-LanceDB-Database": "wrong-static",
+          "X-LanceDB-Database-Prefix": "wrong",
+        },
+      },
+      headerProvider: () => ({
+        "X-LanceDB-Database": "wrong-dynamic",
+        "X-LanceDB-Database-Prefix": "wrong",
+        authorization: "Bearer refreshed",
+      }),
+    });
+    await callback(catalog, requests);
+    expect(responses).toHaveLength(0);
+  } finally {
+    server.closeAllConnections();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+}
+
+describe("remote catalog", () => {
+  it("uses root namespace routes and preserves independent database scope", async () => {
+    await withCatalog(
+      [
+        [204, null],
+        [200, { tables: [] }],
+        [200, {}],
+        [200, { tables: [] }],
+        [200, { tables: [] }],
+        // biome-ignore lint/style/useNamingConvention: server wire format
+        [200, { namespaces: ["team/search"], page_token: "next" }],
+        [204, null],
+      ],
+      async (catalog, requests) => {
+        const first = await catalog.createDatabase("team/search", {
+          existOk: true,
+        });
+        expect(await first.tableNames()).toEqual([]);
+        const second = await catalog.connectDatabase("other");
+        expect(await second.tableNames()).toEqual([]);
+        expect(await first.tableNames()).toEqual([]);
+        expect(
+          await catalog.listDatabases({ limit: 1, pageToken: "a/b" }),
+        ).toEqual({ databases: ["team/search"], pageToken: "next" });
+        await catalog.dropDatabase("team/search", { ignoreMissing: true });
+        expect(requests[0].url).toBe("/v1/namespace/team%2Fsearch/create");
+        expect(requests[0].body).toEqual({ mode: "ExistOk" });
+        expect(requests[5].url).toBe(
+          "/v1/namespace/%24/list?limit=1&page_token=a%2Fb",
+        );
+        expect(requests[6].body).toEqual({
+          mode: "Skip",
+          behavior: "Restrict",
+        });
+        for (const [i, request] of requests.entries()) {
+          expect(request.headers["x-lancedb-database"]).toBe(
+            i === 1 || i === 4 ? "team/search" : i === 3 ? "other" : undefined,
+          );
+          expect(request.headers["x-lancedb-database-prefix"]).toBeUndefined();
+          expect(request.headers.authorization).toBe("Bearer refreshed");
+        }
+      },
+    );
+  });
+
+  it("propagates lifecycle errors and sends restricted drops", async () => {
+    await withCatalog(
+      [
+        [404, {}],
+        [409, {}],
+        [400, {}],
+        [404, {}],
+      ],
+      async (catalog, requests) => {
+        await expect(catalog.connectDatabase("missing")).rejects.toThrow(
+          "missing",
+        );
+        await expect(catalog.createDatabase("exists")).rejects.toThrow(
+          "exists",
+        );
+        await expect(catalog.dropDatabase("full")).rejects.toThrow();
+        await catalog.dropDatabase("missing", { ignoreMissing: true });
+        expect(requests[2].body).toEqual({
+          mode: "Fail",
+          behavior: "Restrict",
+        });
+      },
+    );
+  });
+
+  it("validates endpoints and pagination", async () => {
+    await expect(connectCatalog("/tmp/catalog")).rejects.toThrow();
+    const catalog = await connectCatalog("http://127.0.0.1:1");
+    for (const limit of [0, -1, 1.5, 2147483648]) {
+      await expect(catalog.listDatabases({ limit })).rejects.toThrow("limit");
+    }
+    await expect(catalog.connectDatabase("a$b")).rejects.toThrow(
+      "Invalid database name",
+    );
+  });
+});

nodejs/lancedb/catalog.ts

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+import { Connection, LocalConnection } from "./connection";
+import { HeaderProvider } from "./header";
+import {
+  JsHeaderProvider,
+  ListDatabasesResponse,
+  Catalog as NativeCatalog,
+  CatalogOptions as NativeCatalogOptions,
+} from "./native.js";
+import { OAuthConfig } from "./oauth";
+
+/** Options shared by a catalog and the database connections it returns. */
+export interface CatalogOptions
+  extends Omit<NativeCatalogOptions, "oauthConfig"> {
+  oauthConfig?: OAuthConfig;
+  /** Called for each request to supply authentication headers. */
+  headerProvider?:
+    | HeaderProvider
+    | (() => Record<string, string> | Promise<Record<string, string>>);
+}
+
+export type { ListDatabasesResponse } from "./native.js";
+
+/** A remote catalog manages databases through the server's root namespace. */
+export class Catalog {
+  /** @hidden */
+  constructor(private readonly inner: NativeCatalog) {}
+
+  /** The root namespace endpoint. */
+  get uri(): string {
+    return this.inner.uri;
+  }
+
+  /** Create a database, or open an existing database when existOk is true. */
+  async createDatabase(
+    name: string,
+    options: { existOk?: boolean } = {},
+  ): Promise<Connection> {
+    return new LocalConnection(
+      await this.inner.createDatabase(name, options.existOk),
+    );
+  }
+
+  /** Connect to an existing database by its logical name. */
+  async connectDatabase(name: string): Promise<Connection> {
+    return new LocalConnection(await this.inner.connectDatabase(name));
+  }
+
+  /** Drop an empty database. The server rejects nonempty databases. */
+  async dropDatabase(
+    name: string,
+    options: { ignoreMissing?: boolean } = {},
+  ): Promise<void> {
+    await this.inner.dropDatabase(name, options.ignoreMissing);
+  }
+
+  /** List one page of databases; pass pageToken from a response for the next page. */
+  async listDatabases(
+    options: { limit?: number; pageToken?: string } = {},
+  ): Promise<ListDatabasesResponse> {
+    if (
+      options.limit !== undefined &&
+      (!Number.isInteger(options.limit) ||
+        options.limit <= 0 ||
+        options.limit > 2147483647)
+    ) {
+      throw new Error(
+        "Database list limit must be an integer between 1 and 2147483647",
+      );
+    }
+    return this.inner.listDatabases(options.limit, options.pageToken);
+  }
+}
+
+/**
+ * Connect to an HTTP(S) catalog endpoint. Catalog requests omit database-selection
+ * headers; opened database connections inherit authentication and client options.
+ *
+ * @example
+ * ```ts
+ * const catalog = await connectCatalog("https://my-server.example", { apiKey: "secret" });
+ * const db = await catalog.createDatabase("analytics", { existOk: true });
+ * const page = await catalog.listDatabases({ limit: 20 });
+ * ```
+ */
+export async function connectCatalog(
+  endpoint: string,
+  options: CatalogOptions = {},
+): Promise<Catalog> {
+  const { headerProvider, ...nativeOptions } = options;
+  const provider = headerProvider
+    ? new JsHeaderProvider(async () =>
+        typeof headerProvider === "function"
+          ? headerProvider()
+          : headerProvider.getHeaders(),
+      )
+    : undefined;
+  return new Catalog(
+    await NativeCatalog.new(endpoint, nativeOptions, provider),
+  );
+}

nodejs/lancedb/index.ts

@@ -629,3 +629,10 @@ export async function connectNamespace(
   );
   return new LocalConnection(nativeConn);
 }
+
+export {
+  Catalog,
+  CatalogOptions,
+  ListDatabasesResponse,
+  connectCatalog,
+} from "./catalog";

nodejs/src/catalog.rs

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use lancedb::catalog::{
+    CatalogConnection, CreateDatabaseRequest, DropDatabaseRequest, ListDatabasesRequest,
+};
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+use crate::connection::Connection;
+use crate::error::NapiErrorExt;
+use crate::header::JsHeaderProvider;
+use crate::remote::{ClientConfig, OAuthConfig};
+
+#[napi(object)]
+pub struct CatalogOptions {
+    pub api_key: Option<String>,
+    pub client_config: Option<ClientConfig>,
+    /// SQL service endpoint inherited by database connections.
+    pub sql_host_override: Option<String>,
+    pub read_consistency_interval: Option<f64>,
+    pub oauth_config: Option<OAuthConfig>,
+}
+
+#[napi(object)]
+pub struct ListDatabasesResponse {
+    pub databases: Vec<String>,
+    pub page_token: Option<String>,
+}
+
+#[napi]
+pub struct Catalog {
+    inner: CatalogConnection,
+}
+
+#[napi]
+impl Catalog {
+    #[napi(factory)]
+    pub async fn new(
+        endpoint: String,
+        options: CatalogOptions,
+        header_provider: Option<&JsHeaderProvider>,
+    ) -> Result<Self> {
+        let mut builder = lancedb::connect_catalog(endpoint);
+        if let Some(key) = options.api_key {
+            builder = builder.api_key(key);
+        }
+        let mut config: lancedb::remote::ClientConfig =
+            options.client_config.unwrap_or_default().into();
+        if let Some(provider) = header_provider {
+            config.header_provider = Some(Arc::new(provider.clone()));
+        }
+        builder = builder.client_config(config);
+        if let Some(endpoint) = options.sql_host_override {
+            builder = builder.sql_host_override(endpoint);
+        }
+        if let Some(interval) = options.read_consistency_interval {
+            let interval = Duration::try_from_secs_f64(interval).map_err(|err| {
+                Error::from_reason(format!("Invalid read consistency interval: {err}"))
+            })?;
+            builder = builder.read_consistency_interval(interval);
+        }
+        if let Some(oauth) = options.oauth_config {
+            builder = builder.oauth_config(oauth.try_into().default_error()?);
+        }
+        Ok(Self {
+            inner: builder.execute().await.default_error()?,
+        })
+    }
+
+    #[napi(getter)]
+    pub fn uri(&self) -> String {
+        self.inner.uri().to_string()
+    }
+
+    #[napi]
+    pub async fn create_database(
+        &self,
+        name: String,
+        exist_ok: Option<bool>,
+    ) -> Result<Connection> {
+        self.inner
+            .create_database(CreateDatabaseRequest::new(name).exist_ok(exist_ok.unwrap_or(false)))
+            .await
+            .map(Connection::inner_new)
+            .default_error()
+    }
+    #[napi]
+    pub async fn connect_database(&self, name: String) -> Result<Connection> {
+        self.inner
+            .connect_database(name)
+            .await
+            .map(Connection::inner_new)
+            .default_error()
+    }
+    #[napi]
+    pub async fn drop_database(&self, name: String, ignore_missing: Option<bool>) -> Result<()> {
+        self.inner
+            .drop_database(
+                DropDatabaseRequest::new(name).ignore_missing(ignore_missing.unwrap_or(false)),
+            )
+            .await
+            .default_error()
+    }
+    #[napi]
+    pub async fn list_databases(
+        &self,
+        limit: Option<u32>,
+        page_token: Option<String>,
+    ) -> Result<ListDatabasesResponse> {
+        let mut request = ListDatabasesRequest::default();
+        request.limit = limit;
+        request.page_token = page_token;
+        let response = self.inner.list_databases(request).await.default_error()?;
+        Ok(ListDatabasesResponse {
+            databases: response.databases,
+            page_token: response.page_token,
+        })
+    }
+}

nodejs/src/lib.rs

@@ -11,6 +11,7 @@ use env_logger::Env;
 use napi_derive::*;
 
 mod blob;
+mod catalog;
 mod connection;
 mod error;
 mod header;