Config (GraphQL & middleware)

Config statements set the per-database singletons — the GraphQL interface's shape, global API-endpoint defaults, and the server's default namespace/database. They have no name: the variant is the header, and there is no /// doc comment (no COMMENT clause exists — use a plain // line instead).

GraphQL: expose tables and functions

The GraphQL interface defaults to exposing nothing. Switch it on explicitly:

applied to SurrealDB 3.3.0

schema.surdl

sdl

namespace acme;
database shop;

config graphql {
  auto;
};

surform build

sql

DEFINE NAMESPACE OVERWRITE acme;
USE NS acme;
DEFINE DATABASE OVERWRITE shop;
USE NS acme DB shop;
DEFINE CONFIG OVERWRITE GRAPHQL AUTO;

auto; sets both families — tables and functions — to auto-expose. Or curate the surface with include/exclude lists:

applied to SurrealDB 3.3.0

schema.surdl

sdl

namespace acme;
database shop;

table user {
  schemafull;
  field email: string;
};
table post {
  schemafull;
  field title: string;
};

config graphql {
  tables { include: user, post; };
  functions { exclude: fn::legacy_report; };
  depth: 4;
  complexity: 100;
  introspection: none;
};

surform build

sql

DEFINE NAMESPACE OVERWRITE acme;
USE NS acme;
DEFINE DATABASE OVERWRITE shop;
USE NS acme DB shop;
DEFINE TABLE OVERWRITE `user` TYPE NORMAL SCHEMAFULL;
DEFINE FIELD OVERWRITE email ON `user` TYPE string;
DEFINE TABLE OVERWRITE `post` TYPE NORMAL SCHEMAFULL;
DEFINE FIELD OVERWRITE title ON `post` TYPE string;
DEFINE CONFIG OVERWRITE GRAPHQL
    TABLES INCLUDE `user`, `post`
    FUNCTIONS EXCLUDE fn::legacy_report
    DEPTH 4
    COMPLEXITY 100
    INTROSPECTION NONE;

tables:/functions: each take auto, none, or a sub-block with exactly one of include:/exclude:.
depth: and complexity: bound query cost.
introspection: defaults to auto — none; hides the schema from clients.

API: global endpoint defaults

Middleware and permissions applied to every API route: middleware runs in list order; its arguments are SurrealQL expressions evaluated once at define time:

applied to SurrealDB 3.3.0

schema.surdl

sdl

namespace acme;
database shop;

config api {
  middleware: api::timeout(5s), api::log();
  permissions: $auth.admin = true;
};

surform build

sql

DEFINE NAMESPACE OVERWRITE acme;
USE NS acme;
DEFINE DATABASE OVERWRITE shop;
USE NS acme DB shop;
DEFINE CONFIG OVERWRITE API
    MIDDLEWARE api::timeout(5s), api::log()
    PERMISSIONS WHERE $auth.admin = true;

Default namespace and database

The server's answer to "connect with no namespace/database selected". At least one side is required; the unset side stays unset. This one executes at root level, above any USE line:

applied to SurrealDB 3.3.0

schema.surdl

sdl

namespace acme;
database shop;

config default {
  namespace: 'acme';
  database: 'shop';
};

surform build

sql

DEFINE NAMESPACE OVERWRITE acme;
DEFINE CONFIG OVERWRITE DEFAULT NAMESPACE 'acme' DATABASE 'shop';
USE NS acme;
DEFINE DATABASE OVERWRITE shop;
USE NS acme DB shop;

A note on round-trips

Configs are singletons — re-defining is what OVERWRITE is for, and the compiler always emits it. The database reports configs as header-less fragments (GRAPHQL TABLES … FUNCTIONS …), not full statements; the reverse reader reassembles them, so normalize folds them back into your file faithfully.

Where next

API routes — the endpoints this config decorates.
Buckets — the other capability-gated statement.