GITBOOK-7: No subject

gitbook/README.md

@@ -1,9 +1,9 @@
-# Home
+# Overview
 
 Ent Framework is an opinionated TypeScript data access library with the following major features:
 
 1. **Graph-like representation of entities.** Each Ent is represented as a TypeScipt class with immutable properties. An Ent class instance maps to one row of some table in a relational database (like PostgreSQL). In this sense, it looks similar to ORM, but has several differences explained below.
-2. **Row-level security in a graph.** The managed data forms a graph where node is an Ent instance, and edge is a field link (think of foreign keys) to other Ents. To be allowed to read (or update/delete) some Ent, you define a set of explicit rules like "user can read EntA if they can read EntB or EntC". And, consequently, in EntB you define its own set of rules, like "user can read EntB if they can read EntD".
+2. **Row-level security in a graph (privacy layer).** The managed data forms a graph where node is an Ent instance, and edge is a field link (think of foreign keys) to other Ents. To be allowed to read (or update/delete) some Ent, you define a set of explicit rules like "user can read EntA if they can read EntB or EntC". And, consequently, in EntB you define its own set of rules, like "user can read EntB if they can read EntD".
 3. **Query batching and coalescing.** Ent Framework holistically solves the "N+1 selects" problem commonly known in ORM world. You still write you code as if you work with individual Ents and individual IDs, and the framework magically takes care of sending batched requests (both read and write) to the underlying relational database. 
 4. **Microsharding support out of the box.** You can split your database horizontally, and Ent Framework will take care of routing the requests to the proper shards. This includes batching/coalescing of the queries of course.
 5. **Can be plugged to an exising relational database.** If your project already uses some ORM or runs raw SQL queries, Ent Framework can be plugged in.

gitbook/SUMMARY.md

@@ -1,3 +1,8 @@
 # Table of contents
 
-* [Home](README.md)
+* [Overview](README.md)
+
+## Getting Started
+
+* [Preamble](getting-started/preamble.md)
+* [Connect to a Database](getting-started/connect-to-a-database.md)

gitbook/getting-started/connect-to-a-database.md

@@ -0,0 +1,65 @@
+# Connect to a Database
+
+To start simple, create a PostgreSQL database and several tables there. You can also use you existing database.
+
+```sql
+$ export PGUSER=postgres
+$ export PGPASSWORD=postgres
+$ createdb mytest
+
+$ psql mytest
+% CREATE TABLE topic(
+    id bigserial PRIMARY KEY,
+    creator_id bigint NOT NULL,
+    subject text NOT NULL
+  );
+% CREATE TABLE comment(
+    id bigserial PRIMARY KEY,
+    topic_id bigint REFERENCES topic,
+    creator_id bigint NOT NULL,
+    message text NOT NULL
+  );  
+```
+
+To access that database, you need to create an instance of Cluster:
+
+{% code title="core/ent.ts" fullWidth="false" %}
+```typescript
+import { Cluster } from "ent-framework";
+import { PgClientPool } from "ent-framework/pg";
+import type { PoolConfig } from "pg";
+
+export const cluster = new Cluster({
+  islands: () => [{
+    no: 0,
+    nodes: [{
+      host: "localhost",
+      port: 5432,
+      user: "postgres",
+      password: "postgres",
+      database: "mytest",
+      min: 5,
+      max: 20,
+    }]
+  }],
+  createClient: (node: PoolConfig) => new PgClientPool({ config: node }),
+  loggers: {
+    clientQueryLogger: (props) => console.debug(props),
+    swallowedErrorLogger: (props) => console.log(props),
+  },
+});
+
+// Pre-open min number of DB connections.
+setTimeout(() => cluster.prewarm(), 100);
+```
+{% endcode %}
+
+Terminology:
+
+1. **Cluster** consists of **Islands**. Each Island has a number.
+2. Island consists of master + replica **nodes** (in the above example, we only define one master node and no replicas). 
+3. Island also hosts **Microshards** (in the example above, we will have no microshards, aka just 1 microshard).
+
+Notice that we define the map of the cluster using a callback. Ent Framework will call it from time to time to refresh the view of the cluster, so in this callback, you can read the data from some configuration database. This is called "dynamic real-time reconfiguration".
+
+[PgClientPool](../../docs/classes/PgClientPool.md) class accepts several options, one of them is the standard [node-postgtes PoolConfig](https://node-postgres.com/apis/pool) interface. For simplicity, when we define a cluster shape in `islands`, we can return a list of such configs.

gitbook/getting-started/preamble.md

@@ -0,0 +1,5 @@
+# Preamble
+
+Below, we'll show some Ent Framework usage examples.
+
+We will progress from the simplest code snippets to more and more advanced topics, like custom ID schemas, privacy rules, master-replica and failover, microsharding, cross-shard foreign keys etc.