Configuration

Schema sync reads its database connection from the db section of your atscript.config.mts. This page covers all configuration options.

Config File Setup

Add a db section to your atscript.config.mts:

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",
  },
});

INFO

dbPlugin() is required to register @db.* annotations. The full base config is covered in Setup. This page focuses on the db section only.

Declarative Config

The declarative format specifies the adapter package and connection:

db: {
  adapter: '@atscript/db-sqlite',
  connection: './myapp.db',
}

Option	Type	Description
adapter	string	Package name of the DB adapter (e.g., '@atscript/db-sqlite')
connection	string | () => string	Connection string, file path, or factory function
options	Record<string, unknown>	Additional options passed to createAdapter()
include	string[]	Glob patterns for .as files to include (overrides root include)
exclude	string[]	Glob patterns for .as files to exclude (overrides root exclude)

The CLI resolves the adapter by importing the package and calling its createAdapter(connection, options) function.

Connection strings by adapter

Adapter	Example Connection
@atscript/db-sqlite	'./data.db' or ':memory:'
@atscript/db-postgres	'postgresql://user:pass@localhost:5432/mydb'
@atscript/db-mysql	{ host: 'localhost', port: 3306, user: 'root', database: 'mydb' }
@atscript/db-mongo	'mongodb://localhost:27017/mydb'

Dynamic connection

The connection option can be a function that returns a connection string. This is useful for reading environment variables or secrets at sync time:

db: {
  adapter: '@atscript/db-postgres',
  connection: () => process.env.DATABASE_URL!,
}

Callback Config

For full control, pass a callback that returns a configured DbSpace:

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

export default defineConfig({
  // ...
  db: async () => {
    const driver = new PgDriver({
      connectionString: process.env.DATABASE_URL,
      max: 5,
    });
    return new DbSpace(() => new PostgresAdapter(driver));
  },
});

This bypasses adapter auto-resolution entirely — you construct the DbSpace yourself with any driver configuration you need.

Scoping Sync to Specific Files

Use include and exclude to control which .as files are compiled for sync. This is useful when your project has .as files that aren't database tables (e.g., validation-only types):

db: {
  adapter: '@atscript/db-sqlite',
  connection: './myapp.db',
  include: ['src/db/**/*.as'],
  exclude: ['src/db/deprecated/**'],
}

When omitted, sync compiles all .as files matching the root config's patterns and extracts types with @db.table or @db.view annotations.

Environment-Based Config

Use standard Node.js environment detection for different sync settings:

const isProd = process.env.NODE_ENV === "production";

export default defineConfig({
  // ...
  db: {
    adapter: "@atscript/db-postgres",
    connection: isProd ? process.env.DATABASE_URL! : "postgresql://localhost:5432/myapp_dev",
  },
});

TIP

For production deployments, consider using the programmatic API instead of the CLI. This gives you full control over sync options, error handling, and integration with your deployment pipeline.

Lock Configuration

Distributed-lock parameters are not exposed in the config file — defaults are sane for most setups (30s TTL, 60s wait, 500ms poll). To tune them, use the programmatic API:

import { syncSchema } from "@atscript/db/sync";

await syncSchema(db, types, {
  podId: process.env.HOSTNAME, // identifiable in logs
  lockTtlMs: 60_000,
  waitTimeoutMs: 120_000,
  pollIntervalMs: 1000,
});

Next Steps

• CLI — command-line usage and flags
• Programmatic API — using sync from code
• CI/CD Integration — deployment strategies