2 Commits

Include renames

Author	SHA1	Message	Date
Jonathan HsiehandClaude Opus 5	60a1b4c219	feat(secrets): named Secrets, bindings, and namespace addressing (#4150) ... Adds the client half of database-scoped named Secrets: a Secret is a name and an opaque value stored by the service, and a Function binds one to the environment variable its library already reads. Secrets are addressed by a namespace path plus a name. The UDF body is unchanged and stays portable — it reads `OPENAI_API_KEY` the way it always did, and the binding is what puts a value there: ```python db.create_secret("openai-prod", os.environ["OPENAI_API_KEY"]) function = db.create_function( analyze_caption, secrets=[ EnvVarSecret(secret_name="openai-prod", env_variable="OPENAI_API_KEY") ], ) function.secret_bindings # the Secret's name, never its value ``` - `create_secret` / `alter_secret` / `list_secrets` / `describe_secret` / `drop_secret` on sync, async and remote connections, with the pyo3 binding and the Rust client behind them. Each takes `namespace_path` keyword-only, defaulting to the root. - **There is no read API, by construction rather than by policy** — no code path returns a stored credential, and `describe_secret` answers with metadata only. - `EnvVarSecret` is a pure local constructor: it contacts no server, so it cannot fail on a Secret that does not exist. It exists so that a bare string in that position — which would be a credential — is a `TypeError` rather than a plausible-looking mistake that reads identically in a diff. - `create_function(..., secrets=[...])` carries the bindings as `secret_bindings`: a list of `SecretBinding` tagged by `kind`, so a later delivery mode is a variant rather than a sibling field. The value never travels — it is resolved by the service when the Function runs, which is what lets a rotation reach columns already pinned to an older FunctionVersion. - A binding names its Secret as a `SecretReference` of `{name, namespace_path}` rather than one joined string, so no delimiter has to be excluded from every name and segment forever, and `ClientConfig.id_delimiter` cannot contradict an identity built on a fixed separator. - A root namespace is omitted from the request body rather than sent empty, so a root request is byte-identical to one from a client that predates namespaces. Tests pin it. This is the client surface the design's §4 describes; the service side lives in sophon. **Previously split across two PRs.** Namespace addressing was #4151, stacked on this one; it is folded in here so the Secret identity contract — name, namespace path, and the binding that carries both — is reviewable as one piece rather than as a shape introduced and then replaced. ## Identifier safety, merged from #4189 **#4189 is merged into this branch**, so the client half of Secrets and the guards on the identity it puts in the URL are one PR. What it added: - Components are checked where the identifier is built, before a request is constructed. `create_secret("../jobs", value)` no longer resolves to `/v1/jobs/create` and delivers a credential-bearing body to a route with none of this one's body suppression. - Each component is percent-encoded and joined by the delimiter, so nothing inside a component can end the path segment or add one. - A component may not be empty, a relative segment (`.`, `..`, and their `%2e` spellings), or the delimiter itself — the three ways a component erases a boundary the split has to recover. `["prod", ""]` joined to `prod$`, which reads back as `["prod"]`. - `$` is the only accepted `id_delimiter`, refused at client construction. `ClientConfig.id_delimiter` remains, since the identifier grammar comes from the Lance REST catalog standard, but a value that would produce identifiers no service splits the caller's way is now an error where it was written. - One `build_object_identifier` and one character set serve tables, namespaces, Secrets, Functions and materialized views. Components are checked for *addressability*, not a character set: the name's own grammar stays each object's own, so a catalog database keeps the `/` that `RemoteCatalog::validate_name` allows. ## Known shortcoming `secret_bindings` is omitted from a registration body when empty, so a client that binds nothing sends what a client without bindings sends. When a client does bind a Secret and the service does not know the field, the field is ignored: registration succeeds, the returned version carries no bindings, and the Function fails at execution with the variable unset, far from the call that asked for it. `ServerVersion` is how this codebase refuses a feature the service is too old for, and it gates five features already. It does not gate this one: it is held per table, and registering a Function is a database-level call. Noted at the field in `remote/db.rs`; wiring the gate is follow-up work. **Tests:** lancedb lib 1340 passed, `first_class_function_slice1` 9, `first_class_function_slice2` 3, plus Python tests across both slices. Rebased onto `main` after #4176 (OCI Function identity), #4191 (`.`/`..` table names) and #4195 (remote catalogs). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01UfmeJ533rQDnPBkMtjerV6 --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-09-16 17:00:23 -07:00
Jack YeandXuanwo	6a07f88980	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>	2026-09-17 01:51:10 +08:00