Quickstart

This page builds a small database from scratch. You need one of the two packages from Installation. Both import as arcadedb.

Package Install Pick this if

arcadedb (native, the default)

uv add arcadedb

Scripts, notebooks, tests, CLIs, serverless functions, agents.

arcadedb-jvm (JVM)

uv add arcadedb-jvm

Heavy, long-running loads, or the Java-object APIs.

See Which package? if you are not sure. If you are not sure, take arcadedb.

The scripts on this page ran on Python 3.12 against both packages, version 26.11.1.post3, and both printed the output shown. The code is the same for both packages.

Embedded mode

The database runs in your Python process. You use SQL for the schema and for CRUD, through two calls. ArcadeDB SQL is its own dialect, and it has no JOINs: records link to each other and a query follows the links (see No JOINs).

  • db.command(language, statement, *params) runs a statement that can change data or schema.

  • db.query(language, statement, *params) runs a read.

Two rules cover most first mistakes:

  • Use a with block. It closes the database when the block ends, also when an exception leaves it.

  • Writes need a transaction. INSERT, UPDATE and DELETE go inside with db.transaction():. Schema statements apply immediately. Reads need no transaction. What a transaction does on an error, and how to roll back by hand, is on Transactions.

A complete example

import arcadedb


def main():
    # Create database
    with arcadedb.create_database("./quickstart") as db:
        # Create schema (SQL)
        db.command("sql", "CREATE DOCUMENT TYPE Person")
        db.command("sql", "CREATE PROPERTY Person.name STRING")
        db.command("sql", "CREATE PROPERTY Person.age INTEGER")
        db.command("sql", "CREATE PROPERTY Person.email STRING")
        db.command("sql", "CREATE INDEX ON Person (name) NOTUNIQUE")

        # Insert data (in a transaction)
        with db.transaction():
            for name, age, email in [
                ("Alice", 30, "[email protected]"),
                ("Bob", 25, "[email protected]"),
                ("Charlie", 35, "[email protected]"),
            ]:
                db.command(
                    "sql",
                    "INSERT INTO Person SET name = ?, age = ?, email = ?",
                    name,
                    age,
                    email,
                )
        print("Inserted 3 records")

        # Query all (no transaction needed for reads)
        print("All people:")
        for record in db.query("sql", "SELECT FROM Person ORDER BY age"):
            print(f"  - {record.get('name')}, age {record.get('age')}")

        # Query with a filter
        print("People over 25:")
        for record in db.query("sql", "SELECT FROM Person WHERE age > 25 ORDER BY age"):
            print(f"  - {record.get('name')}, age {record.get('age')}")

        # Count
        total = db.query("sql", "SELECT count(*) as total FROM Person").first().get("total")
        print("Total people:", total)


if __name__ == "__main__":
    main()
Inserted 3 records
All people:
  - Bob, age 25
  - Alice, age 30
  - Charlie, age 35
People over 25:
  - Alice, age 30
  - Charlie, age 35
Total people: 3

create_database raises if the path already holds a database, so run the script in an empty directory or delete ./quickstart before you run it again.

The steps in the script are:

  1. create_database("./quickstart") creates the directory and opens a database in it.

  2. Four CREATE statements define a document type Person, three properties and an index on name.

  3. A transaction inserts three records. The ? marks are positional parameters bound to the values after the statement.

  4. db.query reads them back, with and without a filter, and count(*) counts them.

Reopen the database

Open an existing database with open_database. The second part of the script shows what happens when a write runs outside a transaction:

import arcadedb

# Open the database that quickstart.py created
with arcadedb.open_database("./quickstart") as db:
    result = db.query("sql", "SELECT FROM Person")
    print(f"Found {len(list(result))} records")

# A write outside a transaction raises
with arcadedb.open_database("./quickstart") as db:
    try:
        db.command("sql", "INSERT INTO Person SET name = 'Dora'")
    except Exception as e:
        print(type(e).__name__, e, sep=": ")
Found 3 records
ArcadeDBError: Command failed: com.arcadedb.exception.TransactionException: Transaction not begun

Server mode

When another process or another language needs the same data, start the bundled server. The process that created it keeps direct embedded access, and other processes reach the same databases over the HTTP API on the port that get_http_port() returns:

import arcadedb

with arcadedb.create_server("./databases", root_password="password123") as server:
    db = server.create_database("mydb")        # embedded access, in this process
    print("HTTP port:", server.get_http_port())  # HTTP access, any process
HTTP port: 2480

The server runs only while your Python process runs. See Embedded bindings or the HTTP driver for when to run the regular ArcadeDB server (the official Docker image arcadedata/arcadedb) instead.

The server takes a config dictionary. These keys matter first:

  • host defaults to localhost, so only clients on the same machine connect. A client in a Docker container or on another machine needs config={"host": "0.0.0.0"} (all IPv4 interfaces, or "::" for IPv6). host applies to the HTTP server and to every wire protocol that you enable. A per-protocol key such as postgres_host overrides it for that protocol.

  • http_port (default 2480) and mode (default development) are read by the bindings.

  • Any other key becomes the engine setting arcadedb.<key with _ replaced by .>. For example, postgres_port sets arcadedb.postgres.port.

Both packages carry the Postgres, Redis and Bolt wire protocol plugins, and none starts unless you name it in server_plugins:

config = {
    "host": "0.0.0.0",
    "server_plugins": "Postgres:com.arcadedb.postgres.PostgresProtocolPlugin",
    "postgres_port": 5432,   # sets arcadedb.postgres.port
}

The class names of the other two are com.arcadedb.redis.RedisProtocolPlugin (port key redis_port) and com.arcadedb.bolt.BoltProtocolPlugin (port key bolt_port).

The native server has no Studio web UI.

In the arcadedb-jvm wheels from 26.11.1 the server also serves the Studio web UI, and get_studio_url() returns its address. The earlier 26.10.x wheels do not contain Studio: see the note in What is included.

Next steps