diff --git a/new_core_concepts/modules/ROOT/pages/drivers/overview.adoc b/new_core_concepts/modules/ROOT/pages/drivers/overview.adoc index c5dd69d9c..8a07e9b57 100644 --- a/new_core_concepts/modules/ROOT/pages/drivers/overview.adoc +++ b/new_core_concepts/modules/ROOT/pages/drivers/overview.adoc @@ -16,8 +16,10 @@ Key responsibilities of a TypeDB driver include: * **Query execution**: Sending TypeQL queries and processing results * **Error handling**: Converting server errors into language-specific exceptions * **Resource management**: Properly managing network resources and memory +* **Database management**: Create and delete databases +* **User management**: Create, delete, and manage users. -They also allow you to manage databases and users. +Check out the available xref:{page-version}@new_reference::typedb-grpc-drivers/index.adoc[gRPC drivers] and xref:{page-version}@new_reference::typedb-http-drivers/index.adoc[HTTP helper libraries] to find a driver that works for you. == Communication endpoints diff --git a/new_core_concepts/modules/ROOT/pages/typedb/connections.adoc b/new_core_concepts/modules/ROOT/pages/typedb/connections.adoc index 7196fe3c6..c5f3d4a6d 100644 --- a/new_core_concepts/modules/ROOT/pages/typedb/connections.adoc +++ b/new_core_concepts/modules/ROOT/pages/typedb/connections.adoc @@ -1,4 +1,135 @@ = Connections -[placeholder] -Managing connections in TypeDB server. \ No newline at end of file +== Overview + +To interact with a TypeDB database, a client application must first establish a connection to the server. This is typically done using a +xref:{page-version}@new_core_concepts::drivers/index.adoc[TypeDB driver] for your chosen programming language (e.g., Python, Java, Rust, Node.js) or through a tool like the TypeDB Console or TypeDB Studio. + +A connection requires the server's address (host and port) and valid user credentials. For production environments, a secure connection using +TLS is strongly recommended. + +== Connecting to TypeDB Cloud & Enterprise + +[tabs] +==== +Studio:: ++ +-- +For a cloud deployment: + +// include::../tools/studio.adoc[tag=connect_cloud_studio] +. In the https://cloud.typedb.com[TypeDB Cloud website], navigate to your cluster and click *Connect*. Then, click *Connect with TypeDB Studio*. This will launch TypeDB Studio. +. Fill in your password and hit *Connect*. Your password can be found in your downloaded credentials file (if you have one). + +For an enterprise deployment: + +// include::../tools/studio.adoc[tag=connect_enterprise_studio] +. Launch TypeDB Studio. +. Enter the address of the HTTP endpoint of your cluster. By default, this is at port 8000. +. Enter your username and password. +. Click `Connect`. +-- +Console:: ++ +-- +Run Console in CLI: + +//include::../tools/console.adoc[tag=connect_console] +.Connect to TypeDB +[source,console] +---- +typedb console --address= --username= +---- + +You will be prompted for a password. +-- + +==== + +== Connecting your application + +For programmatic access, use one of the TypeDB xref:{page-component-version}@drivers::overview.adoc[drivers] via the network API: + +[tabs] +==== +Rust:: ++ +-- +[,rust,indent=0] +---- + let uri = format!("{}:{}", address, port); +include::{page-version}@drivers::partial$tutorials/rust/src/main.rs[tags=driver_new] +---- + +-- + +Python:: ++ +-- +[,python,indent=0] +---- + uri = f"{address}:{port}" +include::{page-version}@drivers::partial$tutorials/python/sample.py[tags=driver_new] +---- +-- +==== + +== Connecting to TypeDB Community Edition + +[tabs] +==== +Console:: ++ +-- +Run Console in CLI: + +//include::../tools/console.adoc[tag=connect_console] +.Connect to TypeDB +[source,console] +---- +typedb console --address= --username= --tls-disabled +---- + +You will be prompted for a password. + +TypeDB CE does not support encryption. Use `--tls-disabled` to connect without using TLS. +-- + +Studio:: ++ +-- +// include::../tools/studio.adoc[tag=connect_ce_studio] +. Launch TypeDB Studio. +. Enter the address of the HTTP endpoint of your cluster. By default, this is at port 8000 and for local instances you can use `http://localhost:8000`. +. Enter your username and password - defaults are `admin` and `password`. +. Click `Connect`. +-- +==== + +== Connecting your application + +For programmatic access, use one of the TypeDB xref:{page-component-version}@drivers::overview.adoc[drivers] via the network API: + +[tabs] +==== +Rust:: ++ +-- +[,rust,indent=0] +---- + let uri = format!("{}:{}", address, port); +include::{page-version}@drivers::partial$tutorials/rust/src/main.rs[tags=driver_new] +---- + +-- + +Python:: ++ +-- +[,python,indent=0] +---- + uri = f"{address}:{port}" +include::{page-version}@drivers::partial$tutorials/python/sample.py[tags=driver_new] +---- +-- +==== diff --git a/new_core_concepts/modules/ROOT/pages/typedb/crud.adoc b/new_core_concepts/modules/ROOT/pages/typedb/crud.adoc index 605c5cb9c..053795759 100644 --- a/new_core_concepts/modules/ROOT/pages/typedb/crud.adoc +++ b/new_core_concepts/modules/ROOT/pages/typedb/crud.adoc @@ -1,4 +1,367 @@ = CRUD -[placeholder] -CRUD operations in TypeDB server. \ No newline at end of file +CRUD operations create, read, update, and delete data in the TypeDB database. + +== Create + +When a database is created, it contains no data. The first step to building a rich, structured knowledge base is to insert data into the +database. This can be done in two primary ways: using an `insert` stage for unconditional creation, or a `put` stage for idempotent +creation. All creation operations must be performed in a write-capable transaction (i.e., `write` or `schema`). + +=== Unconditional creation using `insert` + +The `insert` stage is the fundamental command for creating new data. It adds the specified instances without first checking if they +already exist. If insert is the first stage in a pipeline, it runs just once. For these examples, consider this schema: + +For these examples, consider the following schema: + +[,typeql] +.Sample schema +---- +define + entity person, + owns name @card(1), + plays friendship:friend; + relation friendship, + relates friend; + attribute name, + value string; +---- + +If `insert` is the first stage in a pipeline, it runs just once and outputs a single row containing the newly created instances. + +An example command to insert two people and a friendship between them would be: + +[,typeql] +.Alice 🤝 Bob +---- +insert + $a-name isa name "Alice"; + $b-name isa name "Bob"; + $a isa person, has $a-name; + $b isa person, has $b-name; + $f isa friendship, links (friend: $a, friend: $b); +---- + +The output row will contain the newly created instances: + +[,typeql] +---- + ------------- + $a | isa person, iid 0x1e00000000000000000000 + $a-name | isa name "Alice" + $b | isa person, iid 0x1e00000000000000000001 + $b-name | isa name "Bob" + $f | isa friendship, iid 0x1f00000000000000000000 + ------------- +---- + +When an `insert` stage is preceded by other stages, most commonly `match`, the `insert` stage will run once for each row it receives from +the previous stage, and its output rows will contain the newly created instances as well as the contents of the input rows. + +In this example, Alice and Bob are already in the database, and we want to create a friendship between them. + +[,typeql] +.Alice 🤝 Bob, v2 +---- +match + $a isa person, has name "Alice"; + $b isa person, has name "Bob"; +insert + $f isa friendship, links (friend: $a, friend: $b); +---- + +For more detailed information on `insert` stages, see the xref:{page-version}@new_core_concepts::typeql/pipelines/insert.adoc[insert query +stage] documentation in the TypeQL reference. + +=== Idempotent creation using `put` + +The `put` stage represents an "insert if does not exist" operation and provides a simple way to ensure data exists. It first attempts to +match the entire pattern against existing data. If a complete match is found, no changes are made. If _any part of the pattern_ does not +match, the query executes as if it were an insert stage for _the entire pattern._ + +[,typeql] +---- +put + $a isa person, has name "Alice"; + $b isa person, has name "Bob"; + $f isa friendship, links (friend: $a, friend: $b); +---- + +This query will attempt to match the given patterns against existing data in the database. If the patterns are matched, the query stage will +retrieve the matched instances and make no changes to the database. If the patterns are _not_ matched, however, the query will execute as if +it were an `insert` stage. + +[IMPORTANT] +==== +It's worth underlining: `put` stages are all-or-nothing. For example, in the query above, even if a `person` named `"Alice"` already exists +in the database, if there is no `person` named `"Bob"`, the query will insert a new `person` with the name `"Alice"`, a new `person` with +the name `"Bob"`, and a new friendship between them. +==== + +For more detailed information on `put` stages, see the xref:{page-version}@new_core_concepts::typeql/pipelines/put.adoc[put query stage] +documentation in the TypeQL reference. + +=== Bulk loading + +You may already have a large amount of data that you wish to insert into the newly created database. +This section contains some suggestions on how to do that efficiently. + +==== Query batching + +There is a cost associated with opening and committing transactions. If you have a large number of queries to execute, you should consider +batching more than one query into a single transaction. + +Care should be taken to ensure that the batches of queries are not too large. Long-running transactions can cause slowdowns as large sets of +data are validated against each other during commits. + +As a rule of thumb, we recommend around 100-1000 inserts per transaction, though the exact numbers vary application to application. + +==== Deferred resolution + +Queries are performed asynchronously: when a query request is sent from the driver, the returned value is a _promise_ that needs to be +resolved to obtain the actual result. + +This allows the driver to send multiple queries to the server to be executed concurrently. The suggested way to take advantage of this is to +open a number of concurrent transactions and send a batch of queries to each of them. + +[tabs] +.Example +==== +Python:: ++ +-- +[,python] +---- +# TODO +---- +-- + +Rust:: ++ +-- +The `futures` crate provides the way to concurrently execute tasks in batches of specified size. + +[,rust] +---- +let batch_tasks = batches.into_iter().map(|batch| { + let driver = driver.clone(); + async move { + let tx = driver.transaction(typedb_driver::TransactionType::Write).await?; + let result = tx.query(batch_query(batch)).await?; + tx.commit().await?; + Ok(result) + } +}); +let results: Vec = + stream::iter(batch_tasks).buffered(parallelization).collect().await; +---- +-- +==== + +==== Accidental duplication and ordering + +A major concern when loading large amounts of data is duplication. In most cases, it can be avoided by using the `put` stage: + +[,typeql] +.Insert a new user if there isn't already a user named `"john1"` +---- +put + $x isa user, has username "john_1"; +---- + +An issue may arise during parallel loading, however, where concurrent workers ensure the same user exists, inadvertently creating two +``john_1``s. If `user` has a xref:{page-version}@new_core_concepts::typeql/entities-relations-attributtes.adoc#key[`@key`] attribute, this +is a minor issue: whichever transaction attempts to commit later will fail and need to be retried. + +It is recommended, if possible, to load entities first along with their attributes, followed by relations between entities, then relations +between relations. This order minimizes transaction failures or, with a ``@key``less schema, accidental duplication. + +== Read + +All queries, as usual, must be performed within a transaction. All transaction types, `read`, `write`, and `schema`, are read-capable. + +=== Retrieving data in rows using `match` + +A `match` stage is the fundamental command for retrieving data. They retrieve data by matching *patterns*. Patterns represent constraints +the variables are expected to satisfy. Match stages return _all combinations_ of data for their variables that satisfy the pattern, though +they will not rebind a variable already bound by previous stages. + +Patterns can be combined into larger patterns by conjunction with `;`, disjuction with `or`, and negation with `not`. Patterns can also be +marked as optional by putting them in a `try` block, in which case any failure to match those patterns does not affect the rest of the +stage, and the variables that are newly introduced in the block are considered optionally bound (`$x?`). See the +xref:{page-version}@new_core_concepts::typeql/patterns/index.adoc[pattern reference] for more. + +The stream of rows can then be processed using stream operators such as `sort`, `reduce`, and `limit`, or extended with more `match` +clauses. + +When retrieving data from the database there is a basic distinction to keep in mind: + +* *objects*, i.e. entities and relations, do not have a value that can be returned from the database; instead they are represented + by an internal ID (see xref:{page-version}@new_core_concepts::typeql/data_model.adoc#representation[IID]). +* *attributes* are fully identified by their type and value. + +For the full list of query stages and stream operators, consult the +xref:{page-version}@new_core_concepts::typeql/query-clauses/index.adoc[data pipelines] documentation in the TypeQL reference. + +=== Retrieving data in documents using `fetch` + +A `fetch` stage converts each input row into a JSON-like document. The body of a `fetch` stage describes the structure of the document. +This allows structuring the output of the query to map precisely to the structure of the data required by the application. + +[,typeql] +---- +match + $p isa person; +fetch { + "name": $p.name, + "friends": [ + match ($p, $q) isa friendship; $q has name $friend-name; + return { $friend-name }; + ], +}; +---- + +The `fetch` stage above will return a document for each person in the database, containing the person's name and a list of names of their +friends. + +[,typeql] +---- +{ + "name": "Alice" + "friends": [ + "Bob", + "Carol", + "Dean" + ], +} +{ + "name": "Eve", + "friends": [] +} +... +---- + +For more information on `fetch` stages, see the xref:{page-version}@new_core_concepts::typeql/pipelines/fetch.adoc[fetch query stage] +documentation in the TypeQL reference. + +== Update + +=== `delete; insert` + +[,typeql] +---- +match + $a isa person, has name $name; + $name == "Alice"; +delete + has $name of $a; +insert + $a has name "Alan"; +---- + +=== Atomic updates with `update` + +An attribute ownership or a roleplayer with cardinality `@card(0..1)` or `@card(1)` can be updated using an `update` stage. + +Similar to ``put``, an `update` stage represents a "set if does not exist" operation. If the attribute or roleplayer is not present, the +`update` stage will add it. If one is present, however, the `update` stage will replace it with the new one. + +[,typeql] +.Simple attribute update +---- +match + $a isa person, has name "Alice"; +update + $a has name "Alan"; +---- + +[,typeql] +.Fixing a data entry error by switching roleplayers +---- +match + $parentship isa parentship, links (parent: $p, child: $c); +update + $parentship links (parent: $c, child: $p); +---- + +[,typeql] +.Multiple unrelated statements can be updated at a time +---- +match + $a isa person, has username "white-rabbit"; + $b isa person, has username "mad-hatter"; +update + $a has name "Alice"; + $b has name "Bob"; +---- + +=== Complex updates with ``delete``-``insert`` + +For most updates, the recommended pattern is to use a `delete` stage followed by an `insert` stage. This approach provides explicit, manual +control over the modification process. While more verbose, it is also more flexible. + +The same roleplayer switch from the previous section can be expressed as follows: + +[,typeql] +.Fixing a data entry error by switching roleplayers, v2 +---- +match + $parentship isa parentship, links (parent: $p, child: $c); +delete + (parent: $c, child: $p) of $parentship; +insert + $parentship links (parent: $c, child: $p); +---- + +This pattern is required for any updates involving attributes or roleplayers with a cardinality greater than one, as well any updates that +affect the data in a more complex way. + +== Delete + +Deleting data is handled by a `delete` stage, which operates on variables returned by previous stages. + +=== Deleting instances + +The most straightforward deletion is to remove an entire instance (an entity, relation, or attribute). This is done by matching the instance +and then simply using `delete` with the variable. + +[,typeql] +---- +match + $a isa person, has name "Alice"; +delete + $a; +---- + +When an instance is deleted, the variable is removed from the row for all future stages. + +[NOTE] +.Cascading deletes +==== +Deleting an attribute implicitly deletes all ownerships of that attribute, and deleting an object (i.e. entity or relation) implicitly +deletes all roles that instance plays in any relation. +==== + +=== Deleting ownerships and roleplayers + +Connections between instances, that is ownerships and roleplayers, can be deleted without deleting the instances themselves. `delete has +$attribute of $owner;` removes the ownership link but leaves the attribute in the database, while `delete links (role: $player) of +$relation;` removes a specific roleplayer from a relation. + +[,typeql] +---- +match + $a isa person, has name $name == "Alice"; + $f isa friendship, links (friend: $a); +delete + has $name of $a; + links (friend: $a) of $f; +---- + +[NOTE] +.Cascading deletes +==== +Relations without roleplayers and non-`@independent` attributes with no owners are deleted automatically when the transaction is committed. +==== + diff --git a/new_core_concepts/modules/ROOT/pages/typedb/databases.adoc b/new_core_concepts/modules/ROOT/pages/typedb/databases.adoc index df10471ff..238012771 100644 --- a/new_core_concepts/modules/ROOT/pages/typedb/databases.adoc +++ b/new_core_concepts/modules/ROOT/pages/typedb/databases.adoc @@ -1,4 +1,69 @@ = Databases -[placeholder] -Managing databases in TypeDB server. \ No newline at end of file +This section covers the management of databases and the definition of the schema, which provides the structural foundation for your data. + +== Managing databases + +In TypeDB, databases are high-level containers for your data and its corresponding schema. Database creation and deletion are administrative +operations performed through tools like the TypeDB Console or programmatically via the client drivers, rather than through TypeQL queries. + +To create a new database, you can use the `database create` command in the Console (e.g., `database create my-database`) or call the appropriate +method in a client driver, such as `driver.databases.create("my-database")` in Python. + +Deleting a database, which permanently removes all of its contents, is handled similarly. The Console command is `database delete +my-database`, and the equivalent in the Python driver is `client.databases.delete("my-database")`. This is an irreversible action and should +be used with care. + +You can also perform administrative checks, such as verifying if a database exists or viewing all databases on the server. To see a complete +list, you can use `database list` in the Console or `client.databases.all()` in the Python driver. + +== Defining a schema + +The schema is a high-level specification of your application's data model. The schema must be defined before any data is inserted into the +database. + +The schema is composed of three main kinds of types: + +- Entity types represent the primary objects or concepts in your domain (e.g., `person`, `company`, `movie`). + +- Relation types represent the relationships that can exist between types (e.g., `friendship`, `employment`, `casting`). + +- Attribute types represent the properties or data values that other types can have (e.g., `name`, `mission-statement`, `release-date`). + +You build your schema by defining these types and their interactions using several key statements within a define query: + +- `entity`/`relation`/`attribute` creates a root type of specified kind (e.g., `entity person;`). + +- `sub` creates a type that inherits from a supertype (e.g., `employee sub person;`). + +- `owns` specifies that an entity or relation can have a certain attribute (e.g., `person owns name;`). + +- `plays` specifies that an entity can play a role in a relation (e.g., `person plays employment:employee;`). + +- `relates` defines a role that is part of a relation (e.g., `employment relates employee;`). + +Here is an example of a simple schema definition: + +[,typeql] +---- +define + entity person, + owns name, + owns email, + plays friendship:friend; + + attribute name, value string; + + attribute email, value string; + + entity employee sub person, + owns employee-id; + + attribute employee-id, value string; + + relation friendship, + relates friend; +---- + +For more information on defining a schema, refer to the xref:{page-version}@new_core_concepts::typeql/schema/define.adoc[`define` query] +documentation. diff --git a/new_core_concepts/modules/ROOT/pages/typedb/errors.adoc b/new_core_concepts/modules/ROOT/pages/typedb/errors.adoc index acef028cb..7a763f893 100644 --- a/new_core_concepts/modules/ROOT/pages/typedb/errors.adoc +++ b/new_core_concepts/modules/ROOT/pages/typedb/errors.adoc @@ -1,4 +1,21 @@ = Errors -[placeholder] -Error handling in TypeDB server. \ No newline at end of file +Errors in TypeDB keep track of their cause, and the location of the error in the query. Console and Studio will display the full stck from +the lowest level cause, such as a TypeQL syntax error, to the ultimate outcome such as the transaction being closed as a result of an +invalid write. You can access the entire stacktrace of the error in the drivers by e.g. repeatedly calling the `Error::source()` method in +the Rust driver. + +[,] +---- +test::schema>> define person sub entity; + +Error executing command: 'define person sub entity;' + +[TQL0] [TQL03] TypeQL Error: There is a syntax error +parsing error: expected identifier +Near 1:18: +--> define person sub entity; + ^ +Caused: Error in usage of TypeQL. +Caused: [TSV7] Query parsing failed. +---- diff --git a/new_core_concepts/modules/ROOT/pages/typedb/horizontal_scaling.adoc b/new_core_concepts/modules/ROOT/pages/typedb/horizontal_scaling.adoc index a6bd9b200..40aa4862b 100644 --- a/new_core_concepts/modules/ROOT/pages/typedb/horizontal_scaling.adoc +++ b/new_core_concepts/modules/ROOT/pages/typedb/horizontal_scaling.adoc @@ -1,2 +1,43 @@ = Horizontal Scaling +When a single server can no longer handle the volume of read queries for your application, it becomes necessary to scale out horizontally. +In TypeDB, this is achieved by creating a database cluster that distributes the read load across multiple nodes. This chapter explains how +TypeDB's replication-based architecture enables horizontal scaling for read transactions while also providing high availability and fault +tolerance. + +== Scaling read throughput with replication + +TypeDB's strategy for horizontal scaling is based on data replication using the Raft consensus algorithm. Because every node has access to +all the data, read-only transactions can be executed on any node in the cluster. This allows you to scale your application's read throughput +linearly by simply adding more nodes. As you add nodes, the cluster's capacity to handle concurrent read queries increases proportionally. + +== The leader-follower model + +A TypeDB cluster operates on a leader-follower model. At any given time, the cluster elects a single leader node for each database, while +all other nodes act as followers. Followers receive a stream of committed transactions from the leader and apply them to their local copy of +the database, keeping them in sync. These nodes are only available to process read transactions. + +The leader is exclusively responsible for processing all schema and data writes. Centralizing writes on a single node simplifies consistency +and ensures that all changes are applied in a strict order. Write throughput is therefore determined by the capacity of the single leader +node and is scaled by increasing its resources (see xref:{page-version}@new_core_concepts::typedb/vertical_scaling.adoc[vertical scaling]). + +If a leader node fails, the cluster automatically elects a new leader from among the followers, ensuring that the database remains available +for writes with minimal interruption. + +== Interacting with a cluster + +Interacting with a cluster is very similar to interacting with a single server. The key difference is that the client driver must be +configured with the network addresses of all nodes in the cluster. + +The driver uses this list to intelligently manage connections. It automatically discovers which node is the current leader for a given +database and routes all write transactions to it. For read transactions, the driver can distribute the load across all available nodes (both +leader and followers) by setting the `read_any_replica` option during opening the transaction, effectively using the entire cluster's +capacity. This routing is handled transparently, so your application code for opening sessions and running transactions remains the same +whether you are connecting to a single node or a full cluster. + +== Consistency and durability + +TypeDB's replication model provides strong consistency guarantees, even in a distributed read environment. When a write transaction is sent +to the leader, it is not confirmed until a majority of nodes in the cluster have durably stored the transaction in their logs. This process +guarantees that once a transaction is committed, it is safely replicated and will not be lost. It also ensures that when followers serve +read queries, they are providing access to a consistent and up-to-date state of the database. diff --git a/new_core_concepts/modules/ROOT/pages/typedb/overview.adoc b/new_core_concepts/modules/ROOT/pages/typedb/overview.adoc index 61a27d2a9..a8bbccca5 100644 --- a/new_core_concepts/modules/ROOT/pages/typedb/overview.adoc +++ b/new_core_concepts/modules/ROOT/pages/typedb/overview.adoc @@ -1,4 +1,14 @@ = TypeDB Server Overview -[placeholder] -Overview of the TypeDB server. \ No newline at end of file +This section of the documentation covers the architecture and design of TypeDB. + +TypeDB is a polymorphic database designed to represent and query complex systems. TypeDB's core philosophy is centered on a strong type +system, making it particularly well-suited for knowledge-intensive applications. Key features include full ACID compliance for transactional +integrity with snapshot-level Isolation, a logical schema for modeling complex data, and a robust replication system using the Raft +consensus algorithm for high availability. At its foundation, TypeDB is built on top of RocksDB as its storage engine, providing a robust +and high-performance base for data persistence. + +Clients and applications connect to TypeDB primarily through language-specific drivers that communicate over gRPC for efficient, +high-throughput operations. For broader compatibility, an HTTP endpoint is also available. TypeDB is offered as a fully managed service on +TypeDB Cloud, providing flexible options for projects of any scale and as a free, open-source Community Edition (CE) for self-hosted +deployments. diff --git a/new_core_concepts/modules/ROOT/pages/typedb/transactions.adoc b/new_core_concepts/modules/ROOT/pages/typedb/transactions.adoc index 04b35d5ed..f936f6a12 100644 --- a/new_core_concepts/modules/ROOT/pages/typedb/transactions.adoc +++ b/new_core_concepts/modules/ROOT/pages/typedb/transactions.adoc @@ -1,4 +1,50 @@ = Transactions -[placeholder] -Managing transactions in TypeDB server. \ No newline at end of file +== Transactionality + +TypeDB transactions come in 3 flavors: *read*, *write*, and *schema*. All transactions operate over *snapshots* of the database taken when +the transaction is opened, providing a consistent view regardless of the operations performed in concurrent transactions. + +TypeDB transactions provide *ACID guarantees* up to snapshot isolation. + +All transactions that can do writes in TypeDB are __stateful__: queries that mutate the schema or data have their changes buffered, and +those changes are accessible to later stages in the query, and to later queries in the transaction. After a commit, the changes are written +into the global database state and made accessible to new transactions. + +== Read transactions + +Read transactions can execute only read queries. When provided a data update query or a schema mutation query, a read transaction will +error. + +* They are the most lightweight and should be used whenever possible. +* *Any number of read transactions can be opened concurrently*, and they will never fail to open even when write or schema transactions are open. + +== Write transactions + +Write transactions can execute read queries and data update queries. When provided a schema mutation query, a write transaction will error. + +* Write transactions can be opened concurrently to other write transactions and read transactions. +* An active schema transaction will prevent a new write transaction from being opened. +* Write transactions *may fail on commit*, as required to enforce data consistency and isolation, such as when two write transactions + concurrently update same piece of data and commit. + +.Example of conflicting writes +[caption=""] +==== +1. We open transaction 1 and modify the owned attribute of an entity. + +2. We then open transaction 2 before transaction 1 has been committed, and modify the same ownership. + +3. If we commit first transaction 1, then transaction 2, the commit of transaction 2 will fail. +==== + +== Schema transactions + +Schema transactions can execute read queries, data update queries, and schema mutation queries. + +* Schema transactions are *exclusive* both against other schema transactions and write transactions. An open write transactions will block + schema transactions from opening. Similarly, a schema transaction will block write and other schema transactions from opening. This + prevents the data from being mutated while the schema is being updated. + +* Schema transactions can *mutate both data and schema* at the same time, allowing atomic migrations from one database state to another. + diff --git a/new_core_concepts/modules/ROOT/pages/typedb/users.adoc b/new_core_concepts/modules/ROOT/pages/typedb/users.adoc index 42aacf311..0ec473bc5 100644 --- a/new_core_concepts/modules/ROOT/pages/typedb/users.adoc +++ b/new_core_concepts/modules/ROOT/pages/typedb/users.adoc @@ -1,4 +1,32 @@ = Users -[placeholder] -Managing users in TypeDB server. \ No newline at end of file +This section covers the management of users in TypeDB. + +== Managing users + +Like database management, all user management operations are administrative, meaning they are performed through the TypeDB Console or client +drivers by a user _with administrative privileges_, rather than with TypeQL queries. + +After first boot, the only user is `admin`. Cloud users will be able to set a custom initial password for `admin` during the initial +setup. In TypeDB CE, the default initial password for `admin` is `password`. + +The lifecycle of a user is managed through a few simple commands. An administrator can add a new user at any time using `user create + []` in the Console (you will be prompted for a password if it's not provided), or programmatically with +driver.users.create("", ""). To view all users currently on the server, an administrator can use the `user list` +command. If a user's access needs to be revoked, it can be done permanently with the `user delete ` command. + +A user can change their password using `user update-password []` in the Console (once again, you will be prompted +for a new password if it's not provided), or programmatically with `driver.users.updatePassword("")`. +An administrator can change any user's password with the same command. + +== Permissions + +TypeDB's permission model is comprised of two roles. The administrator role is currently exclusive to the user `admin` and has full +administrative privileges, including the ability to manage users and databases. Any other user is considered a standard user and, by +default, is granted read and write permissions for all databases on the server, but cannot perform administrative actions. This model +simplifies permission management by focusing on user-level access rather than complex, object-level grants. + +For a secure deployment, it is crucial to follow best practices. In a CE deployment, it is recommended to change the default admin password +immediately. Furthermore, instead of using the powerful admin account for your applications, you should create dedicated standard users for +each application or service. This follows the principle of least privilege and ensures that your applications have the necessary database +access without possessing unnecessary administrative rights. diff --git a/new_core_concepts/modules/ROOT/pages/typedb/vertical_scaling.adoc b/new_core_concepts/modules/ROOT/pages/typedb/vertical_scaling.adoc index 0a4434821..fa8a3c3c0 100644 --- a/new_core_concepts/modules/ROOT/pages/typedb/vertical_scaling.adoc +++ b/new_core_concepts/modules/ROOT/pages/typedb/vertical_scaling.adoc @@ -1,2 +1,7 @@ = Vertical Scaling +Vertical scaling, or "scaling up," boils down to adding more resources to a single server to increase its capacity. This is often the +simplest way to handle increased load, as it doesn't require changes to the application's architecture. + +Scaling up can be achieved in several ways. The most direct method is upgrading the server's hardware. In TypeDB Cloud this can be handled +by migrating the cluster to a larger machine size.