Connecting

Clients

TypeDB server accepts remote connections from TypeDB Clients via gRPC.

Once connected, TypeDB Clients can manage databases, sessions, and transactions.

It’s recommended to instantiate a single client per application.

  • TypeDB Console

  • Java

  • Python

  • Node.js

typedb console --server=0.0.0.0:1729
TypeDBClient client = TypeDB.coreClient("0.0.0.0:1729");
client = TypeDB.core_client("0.0.0.0:1729")
client = TypeDB.coreClient("0.0.0.0:1729");

To connect to TypeDB Cloud use clusterClient/cluster_client instead of coreClient/core_client. It requires a second argument of TypeDBCredential type.

Protocol version control

There is a server-side check for the TypeDB protocol version. If an incompatible version of a TypeDB Client tries to connect to a TypeDB server, the server will send an error instead of initiating the connection.

This is to prevent any potential errors from using incompatible versions of the client and the server.

In the 2.18.0 version of TypeDB, the TypeDB protocol has version number 1.

For backward compatibility protocol version control will allow TypeDB Clients versions prior to 2.18.0 (i.e., with protocol version N/A, or < 1) to connect with a TypeDB server with protocol version 1.

If we try to connect to an older server (prior to version 2.18.0) with a newer client, we should still get an error due to the older server lacking the API to check the protocol version.

Databases

TypeDB instances can contain multiple databases. A database consists of a schema and data. It is both separate and independent of any other database: two databases can’t influence each other. However, TypeDB Clients can connect to multiple databases simultaneously.

TypeDB is optimized for a small number of databases. It’s recommended to start with a single database and add more if necessary (e.g., to support more applications). The best practice is to keep the number of databases under 10.

  • TypeDB Console

  • Java

  • Python

  • Node.js

# create database
database create test-db
# get database schema
database schema test-db
# list all databases
database list
# delete database
database delete test-db
// create database
client.databases().create("test-db");
// get database schema
client.databases().get("test-db").schema();
// get all databases
client.databases().all();
// check if database exists
client.databases().contains("test-db");
// delete database
client.databases().get("test-db").delete();
# create database
client.databases().create("test-db")
# get database schema
client.databases().get("test-db").schema()
# get all databases
client.databases().all()
# check if database exists
client.databases().contains("test-db")
# delete database
client.databases().get("test-db").delete()
// create database
await client.databases().create("test-db");
// get database schema
await client.databases().get("test-db").schema();
// get all databases
await client.databases().all();
// check if database exists
await client.databases().contains("test-db");
// delete database
await (await client.databases().get("test-db")).delete();

Sessions

A session is like a tunnel connection to a database in a TypeDB server. An open session lets us open transactions in it.

Session-transaction-query

Any TypeDB Client will automatically exchange internal signals with the server to keep the session alive when it’s open. If the server doesn’t receive this signal for a period of time bigger than timeout (30 secs by default) it will forcibly close the session due to inactivity.

There are two types of sessions:

  • SCHEMA sessions,

  • DATA sessions.

Only one Schema session can be open at any time. And any open Schema session blocks all attempts to open a Data Write transaction. For more information on these limits see the Schema integrity enforcement section.
Session type Read data Write data Read schema Write schema

DATA

Yes

Yes

Yes

No

SCHEMA

Yes

No

Yes

Yes

TypeDB Clients should read and write data in DATA sessions.

TypeDB Clients should read and write schema in SCHEMA sessions.

If a client needs to read both schema and data from a database, it can be done in any session type (usually used when a data query needs information on types). But it is NOT possible to modify a schema and its data in the same session, regardless of the type.

Write transactions are strict to the session types (see the table above for illustration).

Once a session has been opened, Clients can open and close transactions in that session to read or write a database’s schema or data.

  • TypeDB Console

  • Java

  • Python

  • Node.js

transaction iam data read
TypeDBSession session = client.session("iam", TypeDBSession.Type.DATA);
session = client.session("iam", SessionType.DATA)
session = await client.session("iam", SessionType.DATA);

Sessions must be explicitly opened and closed by TypeDB Clients.

For more information on how to do it with different Clients see the documentation:

It is recommended to avoid long-running sessions, because of possible network failures.

A good principle to follow is for logically coherent transactions to be grouped into a session.

Transactions

All queries to a TypeDB database are performed through transactions. TypeDB transactions provide full ACID guarantees up to snapshot isolation.

There are two types of transactions:

  • READ transactions

  • WRITE transactions

  • TypeDB Console

  • Java

  • Python

  • Node.js

# start transaction
transaction iam data write
insert $x isa person;
$x has full-name "Kevin";
$x has email "[email protected]";
# commit changes
commit
// start transaction
TypeDBTransaction transaction = session.transaction(TypeDBTransaction.Type.WRITE);
transaction.query().insert(insertQuery1);
transaction.query().insert(insertQuery2);
transaction.query().insert(insertQueryN);
// commit changes
transaction.commit();
# start transaction
transaction = session.transaction(TransactionType.WRITE)
transaction.query().insert(insert_query1)
transaction.query().insert(insert_query2)
transaction.query().insert(insert_queryN)
# commit changes
transaction.commit()
// start transaction
const transaction = await session.transaction(TransactionType.WRITE);
transaction.query().insert(InsertQuery1);
transaction.query().insert(InsertQuery2);
transaction.query().insert(InsertQueryN);
// commit changes
transaction.commit();

Transactions must be explicitly opened and closed by a TypeDB Client.

TypeDB Studio lets developers commit/rollback transactions through its GUI.

For more information on how to do it with different Clients see the documentation:

TypeDB transactions use snapshot isolation and optimistic concurrency control to support concurrent, lock-free read/write transactions. For more information, see the ACID guarantees section below.

Transaction time limit

TypeDB transactions have a duration limit. By default, it’s 5 minutes. The default value can be changed with Client options.

The time limit is intended to encourage short-lived transactions, prevent memory leaks caused by transactions that will not be completed and terminate unresponsive transactions.

Best practices

  • Avoid long-running transactions which can result in conflicts and resource contention.

  • Transactions should group logically coherent queries.

For more advice and best practices visit the Best practices page.

ACID guarantees

All TypeDB transactions have ACID guarantees.

Schema operations have additional concurrency restrictions to guarantee schema integrity. See the Schema integrity enforcement section.

Atomicity

TypeDB transactions are all or nothing. If a commit succeeds, all of its changes are persisted. If it fails, all of its changes will be rolled back.

Consistency

TypeDB validates all changes to data and schemas. If changes to a database violate schema or data constraints, the transaction will fail and be rolled back.

Isolation

TypeDB transactions use snapshot isolation and optimistic concurrency control to support simultaneous, lock-free read/write transactions. Thus, a transaction operates on its snapshot of the data, independent of any other. All of its changes are hidden from other transactions. However, they will become visible immediately after a successful commit.

If two transactions attempt to modify the same data, one will succeed on commit while the other will fail. However, one transaction can read data while another is writing it.

Durability

TypeDB writes transactions to a write-ahead log upon commit, ensuring they can be recovered if an unexpected failure (e.g., power outage) occurs before the data is modified.

TypeDB durability guarantees do not apply when storage devices become corrupt or damaged.

Successful write transactions are written to the write-ahead log before returning a response to the client. If a transaction is not successful, all changes are rolled back.

For TypeDB Enterprise and TypeDB Cloud installations, transaction acknowledgment is sent to the client after a majority of replicas replicated the transaction results. See Replication for details.

Schema integrity enforcement

  • Only one Schema session can be opened.

  • Only one Write transaction in a Schema session can be opened.

  • Opening a Schema session prevents any Data Write transactions.

  • Any Write transaction opened in a Data session prevents us from opening a Schema session.

If anything prevents us from opening a session TypeDB will wait for a timeout of about 10 seconds and, if the problem persists, throw an error:

[SSN03] Invalid Session Operation: Could not acquire lock for schema session. Another schema session may have been left open.

Hence, we can always:

  • open Data session,

  • open a Read transaction in an existing session of any type.

Learn more

With the essential knowledge of the Fundamentals section and the ability to connect to a TypeDB databases, described on this page, let’s try defining our own schema.

After that we can try writing and reading data from a database.