[Seaography] Docs

Author: tyt2y3

Blog/blog/2025-10-08-seaography.md

@@ -52,7 +52,7 @@ This is of course a speed run, but you can follow the [same steps](https://githu
     orderBy: { filmId: ASC }
     pagination: { page: { page: 0, limit: 10 } }
     # ⬆ cursor based pagination is also supported:
-    #    pagination: { cursor: { limit: 10, cursor: "Int[10]:100" } }
+    #    pagination: { cursor: { limit: 10, cursor: "Int[3]:100" } }
   ) {
     nodes {
       filmId

Seaography/docs/01-index.md

@@ -1,3 +1,7 @@
-# Seaography
+# Index
 
-Comprehensive documentation coming soon, please read https://www.sea-ql.org/blog/2025-10-08-seaography/ for a quick introduction.
+## Introduction
+
+## Getting Started
+
+## GraphQL Schema

Seaography/docs/01-introduction/01-seaography.md

@@ -0,0 +1,51 @@
+# Why Seaography
+
+## What is GraphQL
+
+GraphQL, originally open-sourced by Facebook, is both a query language and a runtime for APIs. Instead of exposing multiple endpoints like REST, GraphQL provides a single endpoint where clients can specify the exact fields and relationships they want. This makes responses predictable and shaped exactly like the request.
+
+### Benefits of GraphQL
+
+#### Precise data fetching
+
+Clients avoid over-fetching or under-fetching by requesting only the fields they need.
+
+#### Strongly typed schema
+
+The schema acts as a contract between client and server, improving validation, documentation, and developer experience.
+
+#### Unified data access
+
+GraphQL can aggregate data from multiple sources into one query, reducing round-trips. All API requests go through a single POST endpoint.
+
+## Async-GraphQL
+
+[async-graphql](https://docs.rs/async-graphql/latest/async_graphql/) is a Rust library that implements the GraphQL specification with a asynchronous execution model, strong type safety, and dynamic schema definition. It offers:
+
+#### Concurrent field resolution
+
+If a query requests multiple independent fields, async‑graphql can fetch them in parallel.
+
+#### Complexity & depth limits
+
+Built‑in guards to prevent denial‑of‑service via overly complex queries.
+
+#### Strongly-typed schema
+
+Automatic validation ensures schema and resolvers remain consistent.
+
+## Seaography
+
+Seaography is built on top of async‑graphql, offering a set of derive macros, seamless integration with SeaORM, and advanced query capabilities out of the box.
+
+#### Derive macros & faster builds
+
+Seaography provides a set of derive macros for dynamic schema that mirror those used for static schemas in async‑graphql. This makes defining custom GraphQL endpoints easy but also addresses the problem of slow compilation as schema complexity grows.
+
+#### Seamless SeaORM integration
+
+Seaography integrates directly with SeaORM, adding minimal overhead while offering advanced relational query capabilities.
+
+#### Full‑stack solution
+
+Seaography covers all the needs of building complex applications - from data access, backend API, access control to frontend integration ([SeaORM Pro](https://www.sea-ql.org/sea-orm-pro)).

Seaography/docs/01-introduction/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Introduction",
+  "collapsed": false
+}

Seaography/docs/02-getting-started/01-bootstrap.md

@@ -0,0 +1,147 @@
+# Bootstrap Project
+
+## Install cli tools
+
+First, install our cli tools with `cargo`.
+
+```shell
+cargo install sea-orm-cli@^2.0.0-rc
+cargo install seaography-cli@^2.0.0-rc
+```
+
+## Config database url
+
+Set `DATABASE_URL` in your environment to your database connection.
+
+```sh
+export DATABASE_URL=protocol://username:password@localhost/database
+```
+
+Here are some tips for database specific options:
+
+#### MySQL
+
+```
+mysql://username:password@host/database
+```
+
+#### Postgres
+
+Specify a schema
+
+```
+postgres://username:password@host/database?currentSchema=my_schema
+```
+
+#### SQLite
+
+In memory
+
+```
+sqlite::memory:
+```
+
+Create file if not exists
+
+```
+sqlite://path/to/db.sqlite?mode=rwc
+```
+
+Read only
+
+```
+sqlite://path/to/db.sqlite?mode=ro
+```
+
+## Generate SeaORM Entities
+
+```sh
+sea-orm-cli generate entity -o src/entities --seaography
+```
+
+You will see something like:
+
+```
+Writing src/entities/actor.rs
+Writing src/entities/address.rs
+Writing src/entities/category.rs
+Writing src/entities/city.rs
+Writing src/entities/country.rs
+Writing src/entities/customer.rs
+Writing src/entities/film.rs
+Writing src/entities/film_actor.rs
+Writing src/entities/film_category.rs
+Writing src/entities/inventory.rs
+Writing src/entities/language.rs
+Writing src/entities/payment.rs
+Writing src/entities/rental.rs
+Writing src/entities/staff.rs
+Writing src/entities/store.rs
+Writing src/entities/mod.rs
+Writing src/entities/prelude.rs
+Writing src/entities/sea_orm_active_enums.rs
+... Done.
+```
+
+## Generate Seaography Project
+
+```sh
+seaography-cli -o . -e src/entities --framework axum my-seaography-project
+```
+
+You can choose between `actix`, `poem`, `axum` as the web framework. The generated project will have a crate named `my-seaography-project`.
+
+### CLI options
+
+```sh
+🧭 A dynamic GraphQL framework for SeaORM
+
+Usage: seaography-cli [OPTIONS] --entities <ENTITIES> --database-url <DATABASE_URL> <CRATE_NAME>
+
+Arguments:
+  <CRATE_NAME>  Crate name for generated project
+
+Options:
+  -o, --output-dir <OUTPUT_DIR>
+          Project output directory [default: ./]
+  -e, --entities <ENTITIES>
+          Entities directory
+  -u, --database-url <DATABASE_URL>
+          Database URL [env: DATABASE_URL]
+  -f, --framework <FRAMEWORK>
+          Which web framework to use [default: poem] [possible values: actix, poem, axum]
+      --depth-limit <DEPTH_LIMIT>
+          GraphQL depth limit
+      --complexity-limit <COMPLEXITY_LIMIT>
+          GraphQL complexity limit
+  -h, --help
+          Print help
+  -V, --version
+          Print version
+```
+
+## Launch!
+
+```sh
+cargo build
+```
+
+You should see something like:
+
+```sh
+   Compiling seaography v2.0.0-rc.2
+   Compiling seaography-postgres-example v0.1.0 (/Users/chris/seaography/examples/postgres)
+    Finished `dev` profile [unoptimized + debuginfo] target(s) in 28.24s
+```
+
+If the build succeeds, then you can launch it:
+
+```sh
+cargo run
+```
+
+You should see something like:
+
+```sh
+Visit GraphQL Playground at http://localhost:8000
+```

Seaography/docs/02-getting-started/02-project-structure.md

@@ -0,0 +1,136 @@
+# Project Structure
+
+The generated project looks like:
+
+```sh
+Cargo.toml
+src
+├── entities
+│   ├── actor.rs
+│   ├── address.rs
+│   ├── category.rs
+│   ├── city.rs
+│   ├── country.rs
+│   ├── mod.rs
+│   ├── prelude.rs
+│   ├── sea_orm_active_enums.rs
+│   └── ..
+├── lib.rs
+├── main.rs
+└── query_root.rs
+```
+
+## Entities
+
+This is the folder containing all SeaORM entities. Each file corresponds to a database table.
+
+### `mod.rs`
+
+This is the module file listing all entities. These two macros `register_entity_modules!` and `register_active_enums!` register these entities to Seaography. If you want to ignore certain tables, you can remove them from this list.
+
+```rust
+pub mod prelude;
+
+pub mod actor;
+pub mod address;
+pub mod category;
+pub mod city;
+pub mod country;
+
+seaography::register_entity_modules!([
+    actor,
+    address,
+    category,
+    city,
+    country,
+    ..
+]);
+seaography::register_active_enums!([ .. ]);
+```
+
+## GraphQL schema
+
+### `query_root.rs`
+
+This is the root of the GraphQL schema.
+
+```rust
+lazy_static! {
+    static ref CONTEXT: BuilderContext = BuilderContext::default();
+}
+```
+
+The builder context has many config options, and allow you to customize the type mappings of the GraphQL schema. It also allows you to register field guards and lifecycle hooks.
+
+Here it takes all the entities defined in `entities/mod.rs` and register them to Seaography schema builder.
+If you added custom input, output or query endpoints, this is where you'd register them dynamically into the schema.
+You can also attach custom data to the GraphQL schema.
+
+```rust
+pub fn schema_builder(
+    context: &'static BuilderContext,
+    database: DatabaseConnection,
+    depth: Option<usize>,
+    complexity: Option<usize>,
+) -> SchemaBuilder {
+    let mut builder = Builder::new(context, database.clone());
+    builder = register_entity_modules(builder);
+    builder = register_active_enums(builder);
+    builder
+        .set_depth_limit(depth)
+        .set_complexity_limit(complexity)
+        .schema_builder()
+        .data(database)
+}
+```
+
+## App
+
+### `Cargo.toml`
+
+```toml
+[dependencies]
+sea-orm = { version = "~2.0.0-rc", features = ["sqlx-postgres", "runtime-tokio-native-tls", "seaography"] }
+..
+
+[dependencies.seaography]
+version = "~2.0.0-rc" # seaography version
+features = ["with-decimal", "with-chrono"]
+```
+
+`sea-orm` version must match `seaography`'s version. If you're using other database, replace `sqlx-postgres` with `sqlx-mysql` / `sqlx-sqlite`.
+
+There are some useful feature flags for `seaography`:
+
++ `macros`: derive macros
++ `schema-meta`: additional endpoints for schema metadata
++ `rbac`: RBAC support
++ `field-snake-case`: use snake case instead of camel case for fields
++ `field-pluralize`: pluralize complex fields. i.e. use `posts` instead of `post`
+<br/>
+
++ `with-json`: support JSON as scalar value
++ `with-chrono`: support `chrono` crate
++ `with-time`: support `time` crate
++ `with-uuid`: support `uuid` crate
++ `with-decimal`: support `rust_decimal` crate
++ `with-bigdecimal`: support `bigdecimal` crate
++ `with-postgres-array`: support Postgres' array type
+
+### `main.rs`
+
+This is the entry point to the web app. It setups the routes, i.e. `GET` for GrapQL playground, `POST` for handling GraphQL queries.
+
+You will find a config section:
+
+```rust
+lazy_static! {
+    static ref URL: String = env::var("URL").unwrap_or(..);
+    static ref ENDPOINT: String = env::var("ENDPOINT").unwrap_or(..);
+    static ref DATABASE_URL: String = env::var("DATABASE_URL").expect(..);
+    static ref DEPTH_LIMIT: Option<usize> = ..
+    static ref COMPLEXITY_LIMIT: Option<usize> = ..
+}
+```
+
+These are some config options you can override via environment variables, or by `.env`.

Seaography/docs/02-getting-started/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Getting Started",
+  "collapsed": false
+}

Seaography/docs/03-graphql-schema/01-data-types.md

@@ -0,0 +1,15 @@
+# Data Types
+
+GraphQL only has these built-in scalar types:
+
++ `Int`: A signed 32‐bit integer.
++ `Float`: A signed double-precision floating-point value.
++ `String`: A UTF‐8 character sequence.
++ `Boolean`: `true` or `false`.
+
+The SeaORM type system supports a richer set of types, including:
+
++ `Date`, `Time`, `Datetime`: will be mapped to `String`
++ `Decimal`, `BigDecimal`: will be mapped to `String`
++ `Uuid`: will be mapped to `String`
++ `Json`: will be mapped to a custom scalar type `Json`