Setup

This page is the canonical setup reference for Atscript's DB layer. It covers package installation, plugin registration, adapter configuration, and how to create a DbSpace — the entry point for all database operations.

Installing Packages

Every project needs the core trio plus one adapter package for your database:

# Core packages (always required)
pnpm add @atscript/core @atscript/typescript @atscript/db

Then add the adapter for your database:

SQLite

pnpm add @atscript/db-sqlite better-sqlite3

PostgreSQL

pnpm add @atscript/db-postgres pg

MongoDB

pnpm add @atscript/db-mongo mongodb

MySQL

pnpm add @atscript/db-mysql mysql2

Registering the DB Plugin

The dbPlugin() function registers all @db.* annotations (@db.table, @db.index.*, @db.column.*, @db.default.*, @db.rel.*, @db.view.*, @db.search.*, @db.agg.*, @db.patch.*, etc.) and the db.vector primitive type. Call it in your config before compiling .as files:

import { defineConfig } from "@atscript/core";
import ts from "@atscript/typescript";
import { dbPlugin } from "@atscript/db/plugin";

export default defineConfig({
  plugins: [ts(), dbPlugin()],
  // ...
});

Adapter-Specific Plugins

PostgreSQL and MySQL ship their own plugins for adapter-specific annotations:

• PostgreSQL: PostgresPlugin() from @atscript/db-postgres — registers @db.pg.* annotations
• MySQL: MysqlPlugin() from @atscript/db-mysql — registers @db.mysql.* annotations

Add them alongside dbPlugin() if you use adapter-specific features.

Configuration File

Create atscript.config.mts (or atscript.config.ts) in your project root:

SQLite

import { defineConfig } from "@atscript/core";
import ts from "@atscript/typescript";
import { dbPlugin } from "@atscript/db/plugin";

export default defineConfig({
  rootDir: "src",
  plugins: [ts(), dbPlugin()],
  format: "dts",
  db: {
    adapter: "@atscript/db-sqlite",
    connection: "./myapp.db",
  },
});

PostgreSQL

import { defineConfig } from "@atscript/core";
import ts from "@atscript/typescript";
import { dbPlugin } from "@atscript/db/plugin";
import { PostgresPlugin } from "@atscript/db-postgres";

export default defineConfig({
  rootDir: "src",
  plugins: [ts(), dbPlugin(), PostgresPlugin()],
  format: "dts",
  db: {
    adapter: "@atscript/db-postgres",
    connection: "postgresql://user@localhost:5432/mydb",
  },
});

MongoDB

import { defineConfig } from "@atscript/core";
import ts from "@atscript/typescript";
import { dbPlugin } from "@atscript/db/plugin";

export default defineConfig({
  rootDir: "src",
  plugins: [ts(), dbPlugin()],
  format: "dts",
  db: {
    adapter: "@atscript/db-mongo",
    connection: "mongodb://localhost:27017/mydb",
  },
});

MySQL

import { defineConfig } from "@atscript/core";
import ts from "@atscript/typescript";
import { dbPlugin } from "@atscript/db/plugin";
import { MysqlPlugin } from "@atscript/db-mysql";

export default defineConfig({
  rootDir: "src",
  plugins: [ts(), dbPlugin(), MysqlPlugin()],
  format: "dts",
  db: {
    adapter: "@atscript/db-mysql",
    connection: "mysql://root@localhost:3306/mydb",
  },
});

The db section tells the CLI which adapter to use for schema sync and how to connect. It accepts either a declarative object:

db: {
  adapter: '@atscript/db-sqlite',   // adapter package name
  connection: './myapp.db',          // connection string or factory
  options: { /* adapter-specific */ },
  include: ['src/schema/**/*.as'],   // optional: limit which .as files are synced
  exclude: [],
}

Or a factory function for advanced setups:

db: () => createCustomDbSpace();

Creating a DbSpace

DbSpace is the runtime entry point. It manages adapter lifecycle, table/view instances, and cross-table discovery for relations.

import { DbSpace } from "@atscript/db";

The constructor takes an adapter factory — a function that returns a new BaseDbAdapter instance. Each table and view gets its own adapter instance (1:1), because adapters store per-table state (metadata, column maps, type mappings).

SQLite

import { SqliteAdapter, BetterSqlite3Driver } from "@atscript/db-sqlite";

const driver = new BetterSqlite3Driver("./myapp.db");
const db = new DbSpace(() => new SqliteAdapter(driver));

PostgreSQL

import { PostgresAdapter, PgDriver } from "@atscript/db-postgres";

const driver = new PgDriver("postgresql://user@localhost:5432/mydb");
const db = new DbSpace(() => new PostgresAdapter(driver));

MongoDB

import { MongoAdapter } from "@atscript/db-mongo";
import { MongoClient } from "mongodb";

const client = new MongoClient("mongodb://localhost:27017/mydb");
const db = new DbSpace(() => new MongoAdapter(client.db(), client));

MySQL

import { MysqlAdapter, Mysql2Driver } from "@atscript/db-mysql";

const driver = new Mysql2Driver("mysql://root@localhost:3306/mydb");
const db = new DbSpace(() => new MysqlAdapter(driver));

createAdapter Shorthand

Each adapter package exports a createAdapter() function that creates the driver and DbSpace in one call:

import { createAdapter } from "@atscript/db-sqlite";
const db = createAdapter("./myapp.db");

import { createAdapter } from "@atscript/db-postgres";
const db = createAdapter("postgresql://user@localhost:5432/mydb");

import { createAdapter } from "@atscript/db-mongo";
const db = createAdapter("mongodb://localhost:27017/mydb");

import { createAdapter } from "@atscript/db-mysql";
const db = createAdapter("mysql://root@localhost:3306/mydb");

Registering Types

Get typed table and view instances by passing compiled .as types to the space:

import { User } from "./schema/user.as";
import { ActiveUsers } from "./schema/active-users.as";

const users = db.getTable(User); // AtscriptDbTable<typeof User>
const activeUsers = db.getView(ActiveUsers); // AtscriptDbView<typeof ActiveUsers>

If you don't know whether a type is a table or view, use get() — it auto-detects by checking for @db.view or @db.view.for metadata:

const readable = db.get(SomeType); // table or view, auto-detected

All three methods are lazy — the table/view and its adapter are created on first access and cached (via WeakMap) for subsequent calls.

Next Steps

• Tables & Fields — Field types, nested objects, column mappings
• Storage & Nested Objects — How nested objects are stored
• CRUD Operations — Insert, read, update, delete
• Schema Sync — Automatic schema migrations
• Adapters — Adapter-specific configuration and features