Skip to main content

Quickstart

Five minutes from zero to a running app with a database, a model, and an embedded admin panel.

1 — Scaffold a project​

nucleus new myapp
cd myapp
go mod tidy

nucleus new writes a self-contained Go module. There is no replace directive, no local clone of Nucleus required.

2 — Run the server​

nucleus serve

Four endpoints are now live:

URLPurpose
http://localhost:8080/The web app
http://localhost:8080/api/...Auto-mounted REST endpoints
http://localhost:8080/adminEmbedded admin panel
http://localhost:8080/healthzLiveness/readiness checks

The default config (nucleus.yml) uses SQLite at app.db. Override the database with environment variables or by editing nucleus.yml.

3 — A minimal API in code​

If you prefer a single-file app to a scaffolded project, use the fluent entry point:

package main

import (
    "github.com/jcsvwinston/nucleus/pkg/nucleus"
)

type Article struct {
    ID    int64  `json:"id"    db:"id,primary"`
    Title string `json:"title" db:"title" validate:"required"`
}

func main() {
    nucleus.New().
        Port(8080).
        SQLite("app.db").
        Model(&Article{}).
        AutoMigrate().
        Get("/api/articles", func(c *nucleus.Context) error {
            return c.JSON(200, []Article{{ID: 1, Title: "Hello"}})
        }).
        Run()
}

nucleus.New() returns a builder. The terminal call (Run) constructs the application container, opens the database, applies the migration plan and starts the HTTP server. Every step is explicit; nothing happens at import time.

:::warning AutoMigrate is dev-mode only

.AutoMigrate() derives idempotent CREATE TABLE statements from struct tags and runs them against the configured database. Five dialects are supported: SQLite, PostgreSQL, MySQL, MSSQL, and Oracle — each via its own deterministic scaffold builder in pkg/model. On SQLite/Postgres/MySQL the generated SQL uses CREATE TABLE IF NOT EXISTS; on MSSQL it wraps the CREATE in IF OBJECT_ID(..., 'U') IS NULL; on Oracle it wraps it in a PL/SQL block that swallows ORA-00955 ("name is already used by an existing object"). Either way the operation is safe to re-run.

AutoMigrate returns db.ErrAutoMigrate only for unknown drivers — anything outside the five supported dialects above.

Even on supported dialects, AutoMigrate does not alter existing tables — it is CREATE IF NOT EXISTS only. For production schema evolution, prefer explicit SQL migration files (migrations/*.up.sql plus nucleus migrate): they are reversible, reviewable in PR diffs, and the only path the framework offers compatibility guarantees on. nucleus migrate drift will surface any applied migration that has since lost its .up.sql file on disk.

:::

4 — Run a migration​

For non-trivial apps, write SQL migrations under migrations/ and apply them with the CLI:

nucleus migrate         # apply pending migrations
nucleus migrate status  # show plan vs. applied
nucleus migrate down    # roll back the most recent batch

5 — Create an admin user​

nucleus createuser

Prompts for username, email and password. The user goes into the auth table referenced by your nucleus.yml. You can now sign in to the admin panel at /admin.

Next steps​