Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions src/content/docs/client-apis/cli.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,10 @@ data is persisted to disk after the CLI shell is closed. Note that if the databa
directory does not exist, it will be created for you.

```bash
$ lbug example.lbug
$ lbug example.lbdb
```
```
Opened the database example.lbug in read-write mode.
Opened the database example.lbdb in read-write mode.
Enter ":help" for usage hints.
lbug>
```
Expand Down Expand Up @@ -199,10 +199,10 @@ COPY Person FROM 'person.csv';
Pipe the file content to the CLI as follows:

```bash
lbug example.lbug < schema.cypher
lbug example.lbdb < schema.cypher
```
``` table
Opened the database example.lbug in read-write mode.
Opened the database example.lbdb in read-write mode.
Enter ":help" for usage hints.
┌────────────────────────────────┐
│ result │
Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/client-apis/nodejs.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ const lbug = require("@ladybugdb/core");

(async () => {
// Create an empty on-disk database and connect to it
const db = new lbug.Database("example.lbug");
const db = new lbug.Database("example.lbdb");
const conn = new lbug.Connection(db);

// Create the tables
Expand Down Expand Up @@ -68,7 +68,7 @@ where async operations are not desired.
const lbug = require("@ladybugdb/core");

// Create an empty on-disk database and connect to it
const db = new lbug.Database("example.lbug");
const db = new lbug.Database("example.lbdb");
const conn = new lbug.Connection(db);

// Create the tables
Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/client-apis/python.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ import ladybug as lb

def main() -> None:
# Create an empty on-disk database and connect to it
db = lb.Database("example.lbug")
db = lb.Database("example.lbdb")
conn = lb.Connection(db)

create_tables(conn)
Expand Down Expand Up @@ -83,7 +83,7 @@ import ladybug as lb

async def main():
# Create an empty on-disk database and connect to it
db = lb.Database("example.lbug")
db = lb.Database("example.lbdb")
# The underlying connection pool will be automatically created and managed by the async connection
conn = lb.AsyncConnection(db, max_concurrent_queries=4)

Expand Down
32 changes: 16 additions & 16 deletions src/content/docs/concurrency.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,14 @@ local database, whereas under [in-memory](/get-started#in-memory-database) mode,
no data is persisted to disk.

Throughout this documentation, let's suppose you open a Ladybug database file that's on-disk, named
`example.lbug`.
`example.lbdb`.

## Understand connections

### Database and connection objects
Application processes must connect to a Ladybug database in two steps before they can start querying it:

**Step 1.** Create an instance of a `Database` object `db` and pass it the database filename (`example.lbug` in our example below), and
**Step 1.** Create an instance of a `Database` object `db` and pass it the database filename (`example.lbdb` in our example below), and
a read-write mode which can be either:
1. `READ_WRITE` (default); or
2. `READ_ONLY`
Expand All @@ -38,16 +38,16 @@ do both read (e.g., queries with `MATCH WHERE RETURN` statements) as well as wri
- In contrast, a Connection object that was created using a `READ_ONLY` database can only execute
queries that do read operations.

Then, using `conn`, one can execute Cypher queries against the `example.lbug` database.
Then, using `conn`, one can execute Cypher queries against the `example.lbdb` database.
Here's a simple example application in Python that demonstrates these two steps for creating a `READ_WRITE`
database and a connection. The same principles apply to other language APIs as well:

```python
import ladybug as lb

# Open the database in `READ_WRITE` mode. The below code is equivalent to:
# db = lb.Database("example.lbug", read_only=False)
db = lb.Database("example.lbug")
# db = lb.Database("example.lbdb", read_only=False)
db = lb.Database("example.lbdb")
conn = lb.Connection(db)
conn.execute("CREATE (a:Person {name: 'Alice'});")
```
Expand Down Expand Up @@ -97,13 +97,13 @@ in that process).
However, there are common scenarios when you may want to launch
multiple application processes that connect to the same database. One such scenario
is when developing your workflow in Python using a Jupyter notebook
that connects to `example.lbug`. Say you want to also run the Ladybug CLI alongside your Jupyter notebook,
which also connects to the same `example.lbug`. When you launch Ladybug CLI and point it to
`example.lbug`, Ladybug CLI embeds Ladybug and tries to create a `READ_WRITE` Database object. So if your notebook process already
that connects to `example.lbdb`. Say you want to also run the Ladybug CLI alongside your Jupyter notebook,
which also connects to the same `example.lbdb`. When you launch Ladybug CLI and point it to
`example.lbdb`, Ladybug CLI embeds Ladybug and tries to create a `READ_WRITE` Database object. So if your notebook process already
has created a Database object, this will fail with an error that looks like this:

```console
RuntimeError: IO exception: Could not set lock on file : /path/to/database/example.lbug
RuntimeError: IO exception: Could not set lock on file : /path/to/database/example.lbdb
```

If this happens, you would have to shut down your notebook process (or simply restart your Jupyter server),
Expand All @@ -113,12 +113,12 @@ so that its Database object is destroyed, before the CLI can run.

Note that the above limitation about creating multiple Database objects does not mean that you cannot create
multiple Connections from the same `READ_WRITE` Database object and issue concurrent queries. For example,
you can write a program that creates a single `READ_WRITE` Database object `db` that points to `example.lbug`.
you can write a program that creates a single `READ_WRITE` Database object `db` that points to `example.lbdb`.
Then, you can spawn multiple threads
T<sub>1</sub>, ..., T<sub>k</sub>, and each T<sub>i</sub> obtains a connection from `db` and concurrently issues
read or write queries. This is safe. Every read and write statement in Ladybug is wrapped around a transaction
(either automatically or manually by you). Concurrent transactions that operate on the same database
`example.lbug` are safely executed by Ladybug's transaction manager (i.e., the transaction manager inside `db`),
`example.lbdb` are safely executed by Ladybug's transaction manager (i.e., the transaction manager inside `db`),
again as long as those transactions are issued by connections that were created from the same Database object.
See the documentation on [transactions](/cypher/transaction) for the transactional guarantees that Ladybug provides.

Expand All @@ -128,7 +128,7 @@ Below, we provide some examples and best practices for common scenarios you are

### Scenario 1: One process that creates a `READ_WRITE` database
In this scenario, you have a single application process that embeds Ladybug and creates a `READ_WRITE` Database object
that opens the `example.lbug` database. Within this process, you can create multiple concurrent connections, each of which
that opens the `example.lbdb` database. Within this process, you can create multiple concurrent connections, each of which
can execute queries that can read and write to the database, which will be handled safely
by Ladybug's transaction manager. Pictorially, this scenario looks as follows:

Expand All @@ -139,7 +139,7 @@ from `conn1` and `conn2` are executed sequentially but they could be running con

### Scenario 2: Multiple processes that create `READ_ONLY` databases
In this scenario, you have multiple application processes that embed
Ladybug and create `READ_ONLY` Database objects that open the same database `example.lbug`.
Ladybug and create `READ_ONLY` Database objects that open the same database `example.lbdb`.
Each process can create multiple concurrent connections and issue queries.
However, each connection can only execute read-only queries (because the database is opened in `READ_ONLY` mode).
Since the connections and queries are read-only, none of the queries can change the actual database files on disk.
Expand All @@ -152,12 +152,12 @@ If you're interested in running multiple processes that can read and write to th

### Performing read-write operations from multiple processes
In certain production settings, you may need to have multiple processes that read and write to the same Ladybug database,
say again stored under `example.lbug`.
say again stored under `example.lbdb`.
This is the case for example if you have an online application. Say you have a browser application and multiple users
use your application from different browsers and each user interaction leads to concurrent read-write queries
on the same database. To support such scenarios, a common design pattern is this:
1. **One API server process** that embeds Ladybug
and creates a single `READ_WRITE` Database object pointing to `example.lbug`.
and creates a single `READ_WRITE` Database object pointing to `example.lbdb`.
The API server is responsible for handling incoming requests from clients, say through HTTP or gRPC. The
requests' Cypher queries, which can read and write data to the database, are executed
(possibly) concurrently.
Expand Down Expand Up @@ -210,7 +210,7 @@ Sometimes, when you are working in a Jupyter notebook and building your Ladybug
open other processes that connect to the same directory as the database file, you may come across this error:

```console
RuntimeError: IO exception: Could not set lock on file : /path/to/database/example.lbug
RuntimeError: IO exception: Could not set lock on file : /path/to/database/example.lbdb
```

The lock, as described in earlier sections on this page, is present to protect you from inadvertent
Expand Down
8 changes: 4 additions & 4 deletions src/content/docs/developer-guide/files.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,10 @@ in the same directory as the database file.

| File Type | Example |
| --- | --- |
| Database file | `example.lbug` |
| Write-ahead log file | `example.lbug.wal` |
| Shadow file | `example.lbug.shadow` |
| Temporary file | `example.lbug.tmp` |
| Database file | `example.lbdb` |
| Write-ahead log file | `example.lbdb.wal` |
| Shadow file | `example.lbdb.shadow` |
| Temporary file | `example.lbdb.tmp` |

#### Database file

Expand Down
14 changes: 7 additions & 7 deletions src/content/docs/extensions/attach/lbug.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,15 +28,15 @@ you can attach to a single external Ladybug database (or be connected to the loc
Therefore, you don't need to prefix your node and relationship tables.
Instead, you will use the alias to `DETACH` from the external Ladybug database.

Suppose you are connected to a local database `example.lbug`. After configuring a [S3 connection](/extensions/s3#configure-the-connection), you can attach a Ladybug database hosted on S3 as:
Suppose you are connected to a local database `example.lbdb`. After configuring a [S3 connection](/extensions/s3#configure-the-connection), you can attach a Ladybug database hosted on S3 as:

```cypher
ATTACH 's3://lbug-example/university.lbug.lbug' AS uw (dbtype lbug);
ATTACH 's3://lbug-example/university.lbdb.lbdb' AS uw (dbtype lbug);
```
After attaching a remote Ladybug database, you no longer have access to the original local Ladybug database `example.lbug`.
After the `ATTACH` statement above, you can only query the external Ladybug database under `s3://lbug-example/university.lbug.lbug`.
After attaching a remote Ladybug database, you no longer have access to the original local Ladybug database `example.lbdb`.
After the `ATTACH` statement above, you can only query the external Ladybug database under `s3://lbug-example/university.lbdb.lbdb`.

If you wish to attach to a database hosted on GCS instead, just replace the prefix `s3://` with `gs://` (in this case it would become `gs://lbug-example/university.lbug`). For more information on how to set up Ladybug with GCS, see [here](/extensions/gcs).
If you wish to attach to a database hosted on GCS instead, just replace the prefix `s3://` with `gs://` (in this case it would become `gs://lbug-example/university.lbdb`). For more information on how to set up Ladybug with GCS, see [here](/extensions/gcs).

#### Execute queries on external Ladybug database
We only allow **read-only** queries to execute on external Ladybug databases (even if the external database is stored on local disk).
Expand Down Expand Up @@ -72,12 +72,12 @@ To detach from an external Ladybug database, use `DETACH [ALIAS]`:
DETACH uw;
```

After the `DETACH` statement, you can continue querying your local Ladybug database `example.lbug`. Therefore, detaching
After the `DETACH` statement, you can continue querying your local Ladybug database `example.lbdb`. Therefore, detaching
from an external Ladybug database switches your Ladybug database back to the local database you had started your session with.

### Use a local cache for remote files

When connecting to a remote external Ladybug database, say the `s3://lbug-example/university.lbug` database in our example above,
When connecting to a remote external Ladybug database, say the `s3://lbug-example/university.lbdb` database in our example above,
you would use the `httpfs` extension. When querying this remote database in Cypher, Ladybug will make HTTPS calls to the
remote server to query this database. You can speed up your Cypher queries by using the local httpfs cache,
similar to how you can speed up `LOAD FROM` queries using the [local httpfs cache](/extensions/httpfs#local-cache)
Expand Down
8 changes: 4 additions & 4 deletions src/content/docs/extensions/vector.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ extension to directly create the embeddings using Cypher.
import ladybug as lb
import os

db = lb.Database("example.lbug")
db = lb.Database("example.lbdb")
conn = lb.Connection(db)

from sentence_transformers import SentenceTransformer
Expand Down Expand Up @@ -99,7 +99,7 @@ for title, publisher in zip(titles, publishers):
import ladybug as lb
import os

db = lb.Database("example.lbug")
db = lb.Database("example.lbdb")
conn = lb.Connection(db)

conn.execute("INSTALL llm; LOAD llm;")
Expand Down Expand Up @@ -272,7 +272,7 @@ Let's run some example search queries on our newly created vector index.
import ladybug as lb

# Initialize the database
db = lb.Database("example.lbug")
db = lb.Database("example.lbdb")
conn = lb.Connection(db)

# Install and load vector extension once again
Expand Down Expand Up @@ -307,7 +307,7 @@ print(result.get_as_pl())
import ladybug as lb

# Initialize the database
db = lb.Database("example.lbug")
db = lb.Database("example.lbdb")
conn = lb.Connection(db)

# Install and load vector extension once again
Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/get-started/cypher-intro.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,12 @@ Run the appropriate version of Ladybug Explorer via Docker as follows:

```bash
docker run --rm -p 8000:8000 \
-v /path/to/example.lbug:/database \
-v /path/to/example.lbdb:/database \
ghcr.io/ladybugdb/explorer:latest

docker run -p 8000:8000 \
-v /path/to/local/directory:/database \
-e LBUG_FILE=example.lbug \
-e LBUG_FILE=example.lbdb \
--rm ghcr.io/ladybugdb/explorer:latest
```

Expand Down
10 changes: 5 additions & 5 deletions src/content/docs/get-started/graph-algorithms.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,13 +30,13 @@ uv add lbug polars pyarrow networkx numpy scipy

## Create the graph

First, initialize a connection to a new Ladybug database named `example.lbug`:
First, initialize a connection to a new Ladybug database named `example.lbdb`:

```py
from pathlib import Path
import ladybug as lb

db_path = "example.lbug"
db_path = "example.lbdb"

Path(db_path).unlink(missing_ok=True)
Path(db_path + ".wal").unlink(missing_ok=True)
Expand Down Expand Up @@ -114,7 +114,7 @@ The first method to run a graph algorithm natively in Ladybug is using the `algo
```py
import ladybug as lb

db_path = "example.lbug"
db_path = "example.lbdb"

db = lb.Database(db_path)
conn = lb.Connection(db)
Expand Down Expand Up @@ -234,12 +234,12 @@ you want to run a graph algorithm that's not yet supported in Ladybug. It's triv
a NetworkX algorithm result into a Pandas/Polars DataFrame and write it back to Ladybug.
:::

First, obtain a connection to the existing `example.lbug` database:
First, obtain a connection to the existing `example.lbdb` database:

```py
import ladybug as lb

db_path = "example.lbug"
db_path = "example.lbdb"

db = lb.Database(db_path)
conn = lb.Connection(db)
Expand Down
Loading
Loading