> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lancedb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring Cloud Storage in LanceDB

> Configure LanceDB to use S3, GCS, Azure Blob, and S3-compatible object stores with environment variables or storage options.

export const TsStorageTigrisConnect = "async function storageTigrisConnect() {\n  const db = await lancedb.connect(\n    \"s3://your-bucket/path\",\n    {\n      storageOptions: {\n        endpoint: \"https://t3.storage.dev\",\n        region: \"auto\",\n      },\n    },\n  );\n  return db;\n}\n";

export const TsStorageTableTimeout = "async function storageTableTimeout() {\n  const db = await lancedb.connect(\"s3://bucket/path\");\n  const table = await db.createTable(\n    \"table\",\n    [{ a: 1, b: 2 }],\n    { storageOptions: { timeout: \"60s\" } },\n  );\n  return table;\n}\n";

export const TsStorageS3SseKms = "async function storageS3SseKms() {\n  const db = await lancedb.connect(\"s3://bucket/path\", {\n    storageOptions: {\n      awsServerSideEncryption: \"aws:kms\",\n      awsSseKmsKeyId: \"<your-kms-key-id-or-arn>\",\n    },\n  });\n  return db;\n}\n";

export const TsStorageS3Minio = "async function storageS3Minio() {\n  const db = await lancedb.connect(\"s3://bucket/path\", {\n    storageOptions: {\n      region: \"us-east-1\",\n      endpoint: \"http://minio:9000\",\n    },\n  });\n  return db;\n}\n";

export const TsStorageS3Express = "async function storageS3Express() {\n  const db = await lancedb.connect(\n    \"s3://my-bucket--use1-az4--x-s3/path\",\n    {\n      storageOptions: {\n        region: \"us-east-1\",\n        s3Express: \"true\",\n      },\n    },\n  );\n  return db;\n}\n";

export const TsStorageGcsServiceAccount = "async function storageGcsServiceAccount() {\n  const db = await lancedb.connect(\n    \"gs://my-bucket/my-database\",\n    {\n      storageOptions: {\n        serviceAccount: \"path/to/service-account.json\",\n      },\n    },\n  );\n  return db;\n}\n";

export const TsStorageConnectTimeout = "async function storageConnectTimeout() {\n  const db = await lancedb.connect(\"s3://bucket/path\", {\n    storageOptions: { timeout: \"60s\" },\n  });\n  return db;\n}\n";

export const TsStorageConnectS3 = "async function storageConnectS3() {\n  const db = await lancedb.connect(\"s3://bucket/path\");\n  return db;\n}\n";

export const TsStorageConnectGcs = "async function storageConnectGcs() {\n  const db = await lancedb.connect(\"gs://bucket/path\");\n  return db;\n}\n";

export const TsStorageConnectAzure = "async function storageConnectAzure() {\n  const db = await lancedb.connect(\"az://bucket/path\");\n  return db;\n}\n";

export const TsStorageAzureSas = "async function storageAzureSas() {\n  const db = await lancedb.connect(\n    \"az://my-container/my-database\",\n    {\n      storageOptions: {\n        azureStorageAccountName: \"some-account\",\n        azureStorageSasToken: \"<sas-token>\",\n      },\n    },\n  );\n  return db;\n}\n";

export const TsStorageAzureAccount = "async function storageAzureAccount() {\n  const db = await lancedb.connect(\n    \"az://my-container/my-database\",\n    {\n      storageOptions: {\n        accountName: \"some-account\",\n        accountKey: \"some-key\",\n      },\n    },\n  );\n  return db;\n}\n";

export const PyStorageTigrisConnect = "db = lancedb.connect(\n    \"s3://your-bucket/path\",\n    storage_options={\n        \"endpoint\": \"https://t3.storage.dev\",\n        \"region\": \"auto\",\n    },\n)\n";

export const PyStorageTableTimeout = "table = db.create_table(\n    \"table\",\n    [{\"a\": 1, \"b\": 2}],\n    storage_options={\"timeout\": \"60s\"},\n)\n";

export const PyStorageS3SseKms = "db = lancedb.connect(\n    \"s3://bucket/path\",\n    storage_options={\n        \"aws_server_side_encryption\": \"aws:kms\",\n        \"aws_sse_kms_key_id\": \"<your-kms-key-id-or-arn>\",\n    },\n)\n";

export const PyStorageS3Minio = "db = lancedb.connect(\n    \"s3://bucket/path\",\n    storage_options={\n        \"region\": \"us-east-1\",\n        \"endpoint\": \"http://minio:9000\",\n    },\n)\n";

export const PyStorageS3Express = "db = lancedb.connect(\n    \"s3://my-bucket--use1-az4--x-s3/path\",\n    storage_options={\n        \"region\": \"us-east-1\",\n        \"s3_express\": \"true\",\n    },\n)\n";

export const PyStorageGcsServiceAccount = "db = lancedb.connect(\n    \"gs://my-bucket/my-database\",\n    storage_options={\n        \"service_account\": \"path/to/service-account.json\",\n    },\n)\n";

export const PyStorageConnectTimeout = "db = lancedb.connect(\n    \"s3://bucket/path\",\n    storage_options={\"timeout\": \"60s\"},\n)\n";

export const PyStorageConnectS3 = "db = lancedb.connect(\"s3://bucket/path\")\n";

export const PyStorageConnectGcs = "db = lancedb.connect(\"gs://bucket/path\")\n";

export const PyStorageConnectAzure = "db = lancedb.connect(\"az://bucket/path\")\n";

export const PyStorageAzureSas = "db = lancedb.connect(\n    \"az://my-container/my-database\",\n    storage_options={\n        \"azure_storage_account_name\": \"some-account\",\n        \"azure_storage_sas_token\": \"<sas-token>\",\n    },\n)\n";

export const PyStorageAzureAccount = "db = lancedb.connect(\n    \"az://my-container/my-database\",\n    storage_options={\n        \"account_name\": \"some-account\",\n        \"account_key\": \"some-key\",\n    },\n)\n";

When using LanceDB OSS, you can choose where to store your data. The tradeoffs between storage options are covered in the [storage architecture guide](/storage). This page shows how to configure each backend.

<Note>
  **LanceDB Enterprise storage configuration**

  In LanceDB Enterprise, you connect with `db://...` and the cluster owns the storage credentials, so `storage_options` are not passed at runtime. Cloud auth is set at deployment time. For federated databases, the namespace service vends per-request credentials automatically. See the [Enterprise quickstart](/enterprise/quickstart) and the [Azure deployment guide](/enterprise/deployment/azure) for the Enterprise flow.
</Note>

## Object stores

LanceDB supports AWS S3 (and compatible stores), Azure Blob Storage, and Google Cloud Storage. The URI scheme in your `connect` call selects the backend.

<CodeGroup>
  <CodeBlock filename="Python" language="Python" icon="python">
    {PyStorageConnectS3}
  </CodeBlock>

  <CodeBlock filename="TypeScript" language="TypeScript" icon="square-js">
    {TsStorageConnectS3}
  </CodeBlock>
</CodeGroup>

<CodeGroup>
  <CodeBlock filename="Python" language="Python" icon="python">
    {PyStorageConnectGcs}
  </CodeBlock>

  <CodeBlock filename="TypeScript" language="TypeScript" icon="square-js">
    {TsStorageConnectGcs}
  </CodeBlock>
</CodeGroup>

<CodeGroup>
  <CodeBlock filename="Python" language="Python" icon="python">
    {PyStorageConnectAzure}
  </CodeBlock>

  <CodeBlock filename="TypeScript" language="TypeScript" icon="square-js">
    {TsStorageConnectAzure}
  </CodeBlock>
</CodeGroup>

### Configuration options

When running inside the target cloud with correct IAM bindings, LanceDB often needs no extra configuration. When running elsewhere, provide credentials via environment variables or `storage_options`.

<CodeGroup>
  <CodeBlock filename="Python" language="Python" icon="python">
    {PyStorageConnectTimeout}
  </CodeBlock>

  <CodeBlock filename="TypeScript" language="TypeScript" icon="square-js">
    {TsStorageConnectTimeout}
  </CodeBlock>
</CodeGroup>

<Info>
  **Storage option casing**

  Keys are case-insensitive. Use lowercase in `storage_options` and uppercase in environment variables.
</Info>

Table-level `storage_options` inherit every key from the connection and override on a per-key basis. Pass them to `create_table` or `open_table` for options that should apply to a single table:

<CodeGroup>
  <CodeBlock filename="Python" language="Python" icon="python">
    {PyStorageTableTimeout}
  </CodeBlock>

  <CodeBlock filename="TypeScript" language="TypeScript" icon="square-js">
    {TsStorageTableTimeout}
  </CodeBlock>
</CodeGroup>

<Tip>
  **Inspect the effective options**

  On `AsyncTable`, `await table.initial_storage_options()` returns the options the table was opened with, and `await table.latest_storage_options()` returns the current options after any provider-driven refresh. The deprecated `table.storage_options()` method will be removed in a future release.
</Tip>

#### General object store options

| Key                          | Description                                                     |
| :--------------------------- | :-------------------------------------------------------------- |
| `allow_http`                 | Allow non-TLS connections.                                      |
| `allow_invalid_certificates` | Skip certificate validation for TLS connections.                |
| `connect_timeout`            | Timeout for the connect phase.                                  |
| `timeout`                    | Timeout for the full request.                                   |
| `user_agent`                 | User agent string sent with requests.                           |
| `proxy_url`                  | Proxy URL to route requests through.                            |
| `proxy_ca_certificate`       | PEM-formatted CA certificate for proxy connections.             |
| `proxy_excludes`             | Comma-separated hosts that bypass the proxy (domains or CIDR).  |
| `download_retry_count`       | Number of retries when downloading objects.                     |
| `client_max_retries`         | Maximum retries for object-store client requests.               |
| `client_retry_timeout`       | Total retry timeout (seconds) for object-store client requests. |

<Info>
  **Option support varies by backend**

  These are commonly used options. Cloud-specific keys (for example `region`, `endpoint`, `service_account`, and Azure credential keys) are backend-dependent and can be provided in `storage_options` as needed.
</Info>

#### New table configuration

These options control the Lance file format and features used when creating new tables. Pass them via `storage_options` at connection or table level. They are evaluated only at table creation; setting them on an existing connection does not rewrite or alter tables that already exist.

| Key                                  | Values             | Default  | Description                                                                                                                                                       |
| :----------------------------------- | :----------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `new_table_data_storage_version`     | `legacy`, `stable` | `stable` | Lance file format version for new tables. Use `legacy` for backward compatibility with older clients, or `stable` for the current format with better performance. |
| `new_table_enable_v2_manifest_paths` | `true`, `false`    | `false`  | Use v2 manifest path naming. Requires LanceDB >= 0.10.0 to read.                                                                                                  |
| `new_table_enable_stable_row_ids`    | `true`, `false`    | `false`  | Keep row IDs stable across compaction, delete, and merge operations.                                                                                              |

```mermaid theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
flowchart TD
    A[Creating a new table] --> B{Need backward compatibility\nwith older LanceDB clients?}
    B -->|Yes| C[new_table_data_storage_version: legacy]
    B -->|No| D[new_table_data_storage_version: stable\nDefault — recommended]
    D --> E{Need stable row IDs\nacross compaction and deletes?}
    E -->|Yes| F[new_table_enable_stable_row_ids: true]
    E -->|No| G[Default: false]
    D --> H{All clients on LanceDB >= 0.10.0?}
    H -->|Yes| I[new_table_enable_v2_manifest_paths: true]
    H -->|No| J[Default: false]
```

<CodeGroup>
  ```python Python icon="python" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
  import lancedb

  # Set the Lance file format version at connection level
  db = lancedb.connect(
      "s3://bucket/path",
      storage_options={
          "new_table_data_storage_version": "stable",
      },
  )
  ```

  ```typescript TypeScript icon="square-js" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
  import * as lancedb from "@lancedb/lancedb";

  // Set the Lance file format version at connection level
  const db = await lancedb.connect("s3://bucket/path", {
    storageOptions: {
      newTableDataStorageVersion: "stable",
    },
  });
  ```
</CodeGroup>

<Warning>
  **Deprecated parameter**

  The `data_storage_version` parameter on `create_table()` is deprecated. Use `new_table_data_storage_version` in `storage_options` instead.
</Warning>

## AWS S3

<img src="https://mintcdn.com/lancedb-bcbb4faf/0sS6vrpmM3KSVyss/static/assets/images/storage/aws.jpg?fit=max&auto=format&n=0sS6vrpmM3KSVyss&q=85&s=e5ca36574c5c78fb379e1ffb0a6836bc" alt="" width="1560" height="390" data-path="static/assets/images/storage/aws.jpg" />

Set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optionally `AWS_SESSION_TOKEN` as environment variables or pass them in `storage_options`. Region is optional for AWS but required for most S3-compatible stores.

Minimum permissions usually include `s3:PutObject`, `s3:GetObject`, `s3:DeleteObject`, `s3:ListBucket`, and `s3:GetBucketLocation` scoped to the relevant bucket/prefix.

### S3-compatible stores

<CodeGroup>
  <CodeBlock filename="Python" language="Python" icon="python">
    {PyStorageS3Minio}
  </CodeBlock>

  <CodeBlock filename="TypeScript" language="TypeScript" icon="square-js">
    {TsStorageS3Minio}
  </CodeBlock>
</CodeGroup>

If the endpoint is `http://` (common in local development), also set `ALLOW_HTTP=true` or pass `allow_http=True` in `storage_options`.

### S3 Express

<CodeGroup>
  <CodeBlock filename="Python" language="Python" icon="python">
    {PyStorageS3Express}
  </CodeBlock>

  <CodeBlock filename="TypeScript" language="TypeScript" icon="square-js">
    {TsStorageS3Express}
  </CodeBlock>
</CodeGroup>

Consult AWS networking requirements for S3 Express before enabling.

<Tip>
  **Clean up failed multipart uploads**

  LanceDB aborts multipart uploads on graceful shutdown, but crashes can leave incomplete uploads. Add an S3 lifecycle rule to delete in-progress uploads after a few days.
</Tip>

### Server-side encryption with KMS

To encrypt at rest with an AWS KMS key, set `aws_server_side_encryption` to `aws:kms` and `aws_sse_kms_key_id` to the key ID or ARN. The same options apply at connection or table level and combine with bucket-level default encryption.

<CodeGroup>
  <CodeBlock filename="Python" language="Python" icon="python">
    {PyStorageS3SseKms}
  </CodeBlock>

  <CodeBlock filename="TypeScript" language="TypeScript" icon="square-js">
    {TsStorageS3SseKms}
  </CodeBlock>
</CodeGroup>

The IAM principal needs `kms:Encrypt`, `kms:Decrypt`, and `kms:GenerateDataKey` on the configured KMS key.

## Google Cloud Storage

<img src="https://mintcdn.com/lancedb-bcbb4faf/0sS6vrpmM3KSVyss/static/assets/images/storage/gcp.jpg?fit=max&auto=format&n=0sS6vrpmM3KSVyss&q=85&s=c6e235e8dc41623579d507a8dd7d60ef" alt="" width="2920" height="730" data-path="static/assets/images/storage/gcp.jpg" />

Provide credentials via `GOOGLE_SERVICE_ACCOUNT` (path to JSON) or include the path in `storage_options`. GCS defaults to HTTP/1; set `HTTP1_ONLY=false` if you need HTTP/2.

<CodeGroup>
  <CodeBlock filename="Python" language="Python" icon="python">
    {PyStorageGcsServiceAccount}
  </CodeBlock>

  <CodeBlock filename="TypeScript" language="TypeScript" icon="square-js">
    {TsStorageGcsServiceAccount}
  </CodeBlock>
</CodeGroup>

## Azure Blob Storage

<img src="https://mintcdn.com/lancedb-bcbb4faf/0sS6vrpmM3KSVyss/static/assets/images/storage/azure.jpg?fit=max&auto=format&n=0sS6vrpmM3KSVyss&q=85&s=2ab2a9af6d996eb0cd0ca1273738f360" alt="" width="1202" height="301" data-path="static/assets/images/storage/azure.jpg" />

Set `AZURE_STORAGE_ACCOUNT_NAME` and `AZURE_STORAGE_ACCOUNT_KEY` as environment variables, or pass them via `storage_options`.

<CodeGroup>
  <CodeBlock filename="Python" language="Python" icon="python">
    {PyStorageAzureAccount}
  </CodeBlock>

  <CodeBlock filename="TypeScript" language="TypeScript" icon="square-js">
    {TsStorageAzureAccount}
  </CodeBlock>
</CodeGroup>

For SAS-token auth, set `azure_storage_account_name` and `azure_storage_sas_token`:

<CodeGroup>
  <CodeBlock filename="Python" language="Python" icon="python">
    {PyStorageAzureSas}
  </CodeBlock>

  <CodeBlock filename="TypeScript" language="TypeScript" icon="square-js">
    {TsStorageAzureSas}
  </CodeBlock>
</CodeGroup>

Other supported keys include service principal credentials (`azure_client_id`, `azure_client_secret`, `azure_tenant_id`), managed identities, and custom endpoints.

## Tigris Object Storage

<img src="https://mintcdn.com/lancedb-bcbb4faf/0sS6vrpmM3KSVyss/static/assets/images/storage/tigris.jpg?fit=max&auto=format&n=0sS6vrpmM3KSVyss&q=85&s=572dbfe7dd0a3e125b36f73b33df5fda" alt="" width="2920" height="730" data-path="static/assets/images/storage/tigris.jpg" />

Tigris exposes an S3-compatible API. Configure the endpoint and region:

<CodeGroup>
  <CodeBlock filename="Python" language="Python" icon="python">
    {PyStorageTigrisConnect}
  </CodeBlock>

  <CodeBlock filename="TypeScript" language="TypeScript" icon="square-js">
    {TsStorageTigrisConnect}
  </CodeBlock>
</CodeGroup>

Environment variables `AWS_ENDPOINT=https://t3.storage.dev` and `AWS_DEFAULT_REGION=auto` achieve the same configuration.