lancedb/docs/web/management/database.mdx

---
title: "Database"
sidebarTitle: "Database"
description: "Connect to LanceDB and configure storage, credentials and read consistency."
icon: database
keywords: ["connect", "database", "uri", "api key", "storage options", "consistency"]
availability:
  oss: available
  enterprise: available
  summary: >-
    LanceDB Embedded opens tables in a local directory or object storage.
    LanceDB Enterprise connects with a database URI and credentials and runs
    operations with LanceDB Distributed.
---

import { PyConnectEnterprisePlaceholders, TsConnectEnterprisePlaceholders } from '/snippets/connection.mdx';

A database connection provides access to tables and namespaces in a
[catalog](/basics/catalog). Use it to create and open tables, list catalog
objects, and configure how your application reaches the data.

## Connection URIs {#uris}

| URI | Offering | Where queries run |
| --- | --- | --- |
| `./.lancedb` | LanceDB Embedded, with local storage | In your application |
| `s3://bucket/path`, `gs://bucket/path`, `az://container/path` | LanceDB Embedded, with object storage | In your application |
| `db://my-database` | LanceDB Enterprise | On the Enterprise service (LanceDB Distributed) |

[Connect to LanceDB](/basics/connect) has examples for each connection type.
A connection to object storage still uses LanceDB Embedded: your process
reads and writes the bucket directly. LanceDB Enterprise runs LanceDB
Distributed: query execution, indexing and maintenance run on the Enterprise
service, outside your application.

## Connect to Enterprise {#deployment}

Replace the placeholders with the database URI, key, region and endpoint
provided by your administrator.

<CodeGroup>
  <CodeBlock filename="Python" language="Python" icon="python">
    {PyConnectEnterprisePlaceholders}
  </CodeBlock>
  <CodeBlock filename="TypeScript" language="TypeScript" icon="square-js">
    { "import * as lancedb from \"@lancedb/lancedb\";\n\n" }
    {TsConnectEnterprisePlaceholders}
  </CodeBlock>
</CodeGroup>

| Python option | TypeScript option | Purpose |
| --- | --- | --- |
| `api_key` | `apiKey` | Authenticate the connection |
| `region` | `region` | Select the database's region |
| `host_override` | `hostOverride` | Set the Enterprise endpoint |
| `client_config` | `clientConfig` | Configure retries, timeouts and connection pooling. A retry can [repeat an append](/ingestion/insert#performance). |

Use your deployment's region rather than relying on the `us-east-1` default.
For application code, load credentials from environment variables or a secrets
manager. See [Authentication](/enterprise/authentication) for OAuth and
[SQL](/basics/sql) for the separate SQL connection settings.

## Storage options {#storage-options}

For LanceDB Embedded tables in object storage, `storage_options` configures credentials,
endpoints and options for new tables. This example enables stable row IDs for
tables created through the connection:

<CodeGroup>
```python Python icon="python"
import lancedb

db = lancedb.connect(
    "s3://bucket/path",
    storage_options={"new_table_enable_stable_row_ids": "true"},
)
```

```typescript TypeScript icon="square-js"
import * as lancedb from "@lancedb/lancedb";

const db = await lancedb.connect("s3://bucket/path", {
  storageOptions: { new_table_enable_stable_row_ids: "true" },
});
```
</CodeGroup>

Set stable row IDs before creating a table that needs them, such as an ordinary
materialized-view source in Python SDK 0.40.0. The option does not change tables
that already exist. Enterprise storage settings are managed on the server.

See [Storage](/deployment/storage) for provider credentials and other options.

## Read consistency {#consistency}

For LanceDB Embedded connections, `read_consistency_interval` controls how often reads check
for table versions committed by other writers. For example, check at most once
every five seconds:

<CodeGroup>
```python Python icon="python"
from datetime import timedelta
import lancedb

db = lancedb.connect(
    "./.lancedb", read_consistency_interval=timedelta(seconds=5)
)
```

```typescript TypeScript icon="square-js"
import * as lancedb from "@lancedb/lancedb";

const db = await lancedb.connect("./.lancedb", { readConsistencyInterval: 5 });
```
</CodeGroup>

By default, an Embedded table handle does not automatically pick up another
process's writes. Reopen the table, check out its latest version, or configure
a consistency interval when you need those updates. A zero interval checks on
every read, with the cost of a metadata check.

Enterprise manages read freshness on the server. See
[Consistency](/tables/consistency) for its behavior and the distinction between
seeing your own writes and seeing another client's writes.

## Database operations {#operations}

The connection provides methods to create, open, list and drop tables.

| Operation | Python | TypeScript |
| --- | --- | --- |
| Create a table | `create_table` | `createTable` |
| Open a table | `open_table` | `openTable` |
| List tables | `table_names`, `list_tables` | `tableNames`, `listTables` |
| Drop a table | `drop_table` | `dropTable` |

Use the namespace and pagination options documented in
[Namespaces](/management/namespace) when working outside the root namespace
or listing a large catalog. [Tables](/management/table) covers table schemas,
versions and lifecycle operations.

<Warning>
Dropping a table removes its history as well as its current data. You cannot
recover a dropped table through table versioning. The LanceDB Embedded `drop_database()`
and `drop_all_tables()` operations remove all tables without a confirmation prompt.
</Warning>

## Async connections {#async}

Python's `connect_async` returns an `AsyncConnection`. Await its operations
when working in an asynchronous application:

```python
import lancedb

db = await lancedb.connect_async("./.lancedb")
table = await db.open_table("documents")
```

TypeScript's connection and table operations already return promises.

An async connection and a background job serve different purposes. Async APIs
let other tasks run while your application waits for an operation. A
[job](/basics/jobs) represents work that can continue on the server after the
submission call returns.