feat: Sentinela v0.2.0 — Brazilian Financial Data API in Go

- 20 Go source files, single 16MB binary - SQLite + FTS5 full-text search (pure Go, no CGO) - BCB integration: Selic, CDI, IPCA, USD/BRL, EUR/BRL - CVM integration: 2,524 companies from registry - Fiber v2 REST API with 42 handlers - Auto-seeds on first run (~5s for BCB + CVM) - Token bucket rate limiter, optional API key auth - Periodic sync scheduler (configurable) - Graceful shutdown, structured logging (slog) - All endpoints tested with real data
2026-02-10 11:15:54 -03:00
commit f7c8b446bf
28 changed files with 1763 additions and 0 deletions
--- a/internal/db/companies.go
+++ b/internal/db/companies.go
@@ -0,0 +1,93 @@
+package db
+
+import (
+	"database/sql"
+	"fmt"
+	"time"
+)
+
+type Company struct {
+	ID        int64  `json:"id"`
+	Ticker    string `json:"ticker,omitempty"`
+	Name      string `json:"name"`
+	CNPJ      string `json:"cnpj"`
+	CVMCode   string `json:"cvm_code,omitempty"`
+	Sector    string `json:"sector,omitempty"`
+	Status    string `json:"status"`
+	CreatedAt string `json:"created_at"`
+	UpdatedAt string `json:"updated_at"`
+}
+
+func (d *DB) UpsertCompany(c *Company) error {
+	_, err := d.Conn.Exec(`
+		INSERT INTO companies (ticker, name, cnpj, cvm_code, sector, status, updated_at)
+		VALUES (?, ?, ?, ?, ?, ?, ?)
+		ON CONFLICT(cnpj) DO UPDATE SET
+			ticker=excluded.ticker, name=excluded.name, cvm_code=excluded.cvm_code,
+			sector=excluded.sector, status=excluded.status, updated_at=excluded.updated_at`,
+		c.Ticker, c.Name, c.CNPJ, c.CVMCode, c.Sector, c.Status, time.Now().UTC().Format(time.RFC3339))
+	return err
+}
+
+func (d *DB) RebuildCompaniesFTS() error {
+	_, err := d.Conn.Exec(`
+		INSERT INTO companies_fts(companies_fts) VALUES('rebuild')`)
+	return err
+}
+
+func (d *DB) ListCompanies(limit, offset int, status, sector string) ([]Company, int, error) {
+	where := "WHERE 1=1"
+	args := []any{}
+	if status != "" {
+		where += " AND status = ?"
+		args = append(args, status)
+	}
+	if sector != "" {
+		where += " AND sector = ?"
+		args = append(args, sector)
+	}
+
+	var total int
+	err := d.Conn.QueryRow("SELECT COUNT(*) FROM companies "+where, args...).Scan(&total)
+	if err != nil {
+		return nil, 0, err
+	}
+
+	query := fmt.Sprintf("SELECT id, COALESCE(ticker,''), name, cnpj, COALESCE(cvm_code,''), COALESCE(sector,''), status, created_at, updated_at FROM companies %s ORDER BY name LIMIT ? OFFSET ?", where)
+	args = append(args, limit, offset)
+	rows, err := d.Conn.Query(query, args...)
+	if err != nil {
+		return nil, 0, err
+	}
+	defer rows.Close()
+
+	var companies []Company
+	for rows.Next() {
+		var c Company
+		if err := rows.Scan(&c.ID, &c.Ticker, &c.Name, &c.CNPJ, &c.CVMCode, &c.Sector, &c.Status, &c.CreatedAt, &c.UpdatedAt); err != nil {
+			return nil, 0, err
+		}
+		companies = append(companies, c)
+	}
+	return companies, total, nil
+}
+
+func (d *DB) GetCompany(id int64) (*Company, error) {
+	c := &Company{}
+	err := d.Conn.QueryRow("SELECT id, COALESCE(ticker,''), name, cnpj, COALESCE(cvm_code,''), COALESCE(sector,''), status, created_at, updated_at FROM companies WHERE id = ?", id).
+		Scan(&c.ID, &c.Ticker, &c.Name, &c.CNPJ, &c.CVMCode, &c.Sector, &c.Status, &c.CreatedAt, &c.UpdatedAt)
+	if err == sql.ErrNoRows {
+		return nil, nil
+	}
+	return c, err
+}
+
+func (d *DB) GetCompanyByCNPJ(cnpj string) (*Company, error) {
+	c := &Company{}
+	err := d.Conn.QueryRow("SELECT id, COALESCE(ticker,''), name, cnpj, COALESCE(cvm_code,''), COALESCE(sector,''), status, created_at, updated_at FROM companies WHERE cnpj = ?", cnpj).
+		Scan(&c.ID, &c.Ticker, &c.Name, &c.CNPJ, &c.CVMCode, &c.Sector, &c.Status, &c.CreatedAt, &c.UpdatedAt)
+	if err == sql.ErrNoRows {
+		return nil, nil
+	}
+	return c, err
+}
--- a/internal/db/filings.go
+++ b/internal/db/filings.go
@@ -0,0 +1,129 @@
+package db
+
+import (
+	"database/sql"
+	"fmt"
+)
+
+type Filing struct {
+	ID            int64  `json:"id"`
+	ExternalID    string `json:"external_id"`
+	CompanyID     *int64 `json:"company_id,omitempty"`
+	CNPJ          string `json:"cnpj"`
+	Category      string `json:"category"`
+	Type          string `json:"type,omitempty"`
+	Species       string `json:"species,omitempty"`
+	Subject       string `json:"subject,omitempty"`
+	ReferenceDate string `json:"reference_date,omitempty"`
+	DeliveryDate  string `json:"delivery_date"`
+	Protocol      string `json:"protocol,omitempty"`
+	Version       string `json:"version,omitempty"`
+	DownloadURL   string `json:"download_url,omitempty"`
+	Importance    int    `json:"importance"`
+	CreatedAt     string `json:"created_at"`
+}
+
+func (d *DB) UpsertFiling(f *Filing) error {
+	_, err := d.Conn.Exec(`
+		INSERT INTO filings (external_id, company_id, cnpj, category, type, species, subject, reference_date, delivery_date, protocol, version, download_url, importance)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		ON CONFLICT(external_id) DO NOTHING`,
+		f.ExternalID, f.CompanyID, f.CNPJ, f.Category, f.Type, f.Species, f.Subject, f.ReferenceDate, f.DeliveryDate, f.Protocol, f.Version, f.DownloadURL, f.Importance)
+	return err
+}
+
+func (d *DB) RebuildFilingsFTS() error {
+	_, err := d.Conn.Exec(`INSERT INTO filings_fts(filings_fts) VALUES('rebuild')`)
+	return err
+}
+
+func (d *DB) ListFilings(limit, offset int, category, from, to string) ([]Filing, int, error) {
+	where := "WHERE 1=1"
+	args := []any{}
+	if category != "" {
+		where += " AND category = ?"
+		args = append(args, category)
+	}
+	if from != "" {
+		where += " AND delivery_date >= ?"
+		args = append(args, from)
+	}
+	if to != "" {
+		where += " AND delivery_date <= ?"
+		args = append(args, to)
+	}
+
+	var total int
+	err := d.Conn.QueryRow("SELECT COUNT(*) FROM filings "+where, args...).Scan(&total)
+	if err != nil {
+		return nil, 0, err
+	}
+
+	query := fmt.Sprintf(`SELECT id, external_id, company_id, cnpj, category, COALESCE(type,''), COALESCE(species,''),
+		COALESCE(subject,''), COALESCE(reference_date,''), delivery_date, COALESCE(protocol,''),
+		COALESCE(version,''), COALESCE(download_url,''), importance, created_at
+		FROM filings %s ORDER BY delivery_date DESC LIMIT ? OFFSET ?`, where)
+	args = append(args, limit, offset)
+	rows, err := d.Conn.Query(query, args...)
+	if err != nil {
+		return nil, 0, err
+	}
+	defer rows.Close()
+	return scanFilings(rows)
+}
+
+func (d *DB) GetFiling(id int64) (*Filing, error) {
+	f := &Filing{}
+	err := d.Conn.QueryRow(`SELECT id, external_id, company_id, cnpj, category, COALESCE(type,''), COALESCE(species,''),
+		COALESCE(subject,''), COALESCE(reference_date,''), delivery_date, COALESCE(protocol,''),
+		COALESCE(version,''), COALESCE(download_url,''), importance, created_at
+		FROM filings WHERE id = ?`, id).
+		Scan(&f.ID, &f.ExternalID, &f.CompanyID, &f.CNPJ, &f.Category, &f.Type, &f.Species, &f.Subject,
+			&f.ReferenceDate, &f.DeliveryDate, &f.Protocol, &f.Version, &f.DownloadURL, &f.Importance, &f.CreatedAt)
+	if err == sql.ErrNoRows {
+		return nil, nil
+	}
+	return f, err
+}
+
+func (d *DB) ListFilingsByCompany(companyID int64, limit, offset int) ([]Filing, int, error) {
+	var total int
+	d.Conn.QueryRow("SELECT COUNT(*) FROM filings WHERE company_id = ?", companyID).Scan(&total)
+
+	rows, err := d.Conn.Query(`SELECT id, external_id, company_id, cnpj, category, COALESCE(type,''), COALESCE(species,''),
+		COALESCE(subject,''), COALESCE(reference_date,''), delivery_date, COALESCE(protocol,''),
+		COALESCE(version,''), COALESCE(download_url,''), importance, created_at
+		FROM filings WHERE company_id = ? ORDER BY delivery_date DESC LIMIT ? OFFSET ?`, companyID, limit, offset)
+	if err != nil {
+		return nil, 0, err
+	}
+	defer rows.Close()
+	filings, _, err := scanFilings(rows)
+	return filings, total, err
+}
+
+func (d *DB) RecentFilings(limit int) ([]Filing, error) {
+	rows, err := d.Conn.Query(`SELECT id, external_id, company_id, cnpj, category, COALESCE(type,''), COALESCE(species,''),
+		COALESCE(subject,''), COALESCE(reference_date,''), delivery_date, COALESCE(protocol,''),
+		COALESCE(version,''), COALESCE(download_url,''), importance, created_at
+		FROM filings ORDER BY delivery_date DESC LIMIT ?`, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	filings, _, err := scanFilings(rows)
+	return filings, err
+}
+
+func scanFilings(rows *sql.Rows) ([]Filing, int, error) {
+	var filings []Filing
+	for rows.Next() {
+		var f Filing
+		if err := rows.Scan(&f.ID, &f.ExternalID, &f.CompanyID, &f.CNPJ, &f.Category, &f.Type, &f.Species,
+			&f.Subject, &f.ReferenceDate, &f.DeliveryDate, &f.Protocol, &f.Version, &f.DownloadURL, &f.Importance, &f.CreatedAt); err != nil {
+			return nil, 0, err
+		}
+		filings = append(filings, f)
+	}
+	return filings, len(filings), nil
+}
--- a/internal/db/market.go
+++ b/internal/db/market.go
@@ -0,0 +1,215 @@
+package db
+
+import (
+	"database/sql"
+	"fmt"
+)
+
+type SelicRecord struct {
+	ID         int64    `json:"id"`
+	Date       string   `json:"date"`
+	DailyRate  float64  `json:"daily_rate"`
+	AnnualRate *float64 `json:"annual_rate,omitempty"`
+	TargetRate *float64 `json:"target_rate,omitempty"`
+}
+
+type CDIRecord struct {
+	ID         int64    `json:"id"`
+	Date       string   `json:"date"`
+	DailyRate  float64  `json:"daily_rate"`
+	AnnualRate *float64 `json:"annual_rate,omitempty"`
+}
+
+type IPCARecord struct {
+	ID              int64    `json:"id"`
+	Date            string   `json:"date"`
+	MonthlyRate     float64  `json:"monthly_rate"`
+	Accumulated12m  *float64 `json:"accumulated_12m,omitempty"`
+}
+
+type FXRecord struct {
+	ID   int64   `json:"id"`
+	Date string  `json:"date"`
+	Pair string  `json:"pair"`
+	Rate float64 `json:"rate"`
+}
+
+// Selic
+func (d *DB) InsertSelic(date string, daily float64, annual, target *float64) error {
+	_, err := d.Conn.Exec(`INSERT OR IGNORE INTO selic_history (date, daily_rate, annual_rate, target_rate) VALUES (?,?,?,?)`,
+		date, daily, annual, target)
+	return err
+}
+
+func (d *DB) ListSelic(limit int, from, to string) ([]SelicRecord, error) {
+	where, args := marketWhere(from, to)
+	query := fmt.Sprintf("SELECT id, date, daily_rate, annual_rate, target_rate FROM selic_history %s ORDER BY date DESC LIMIT ?", where)
+	args = append(args, limit)
+	rows, err := d.Conn.Query(query, args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []SelicRecord
+	for rows.Next() {
+		var r SelicRecord
+		rows.Scan(&r.ID, &r.Date, &r.DailyRate, &r.AnnualRate, &r.TargetRate)
+		out = append(out, r)
+	}
+	return out, nil
+}
+
+func (d *DB) CurrentSelic() (*SelicRecord, error) {
+	r := &SelicRecord{}
+	err := d.Conn.QueryRow("SELECT id, date, daily_rate, annual_rate, target_rate FROM selic_history ORDER BY date DESC LIMIT 1").
+		Scan(&r.ID, &r.Date, &r.DailyRate, &r.AnnualRate, &r.TargetRate)
+	if err == sql.ErrNoRows {
+		return nil, nil
+	}
+	return r, err
+}
+
+// CDI
+func (d *DB) InsertCDI(date string, daily float64, annual *float64) error {
+	_, err := d.Conn.Exec(`INSERT OR IGNORE INTO cdi_history (date, daily_rate, annual_rate) VALUES (?,?,?)`,
+		date, daily, annual)
+	return err
+}
+
+func (d *DB) ListCDI(limit int, from, to string) ([]CDIRecord, error) {
+	where, args := marketWhere(from, to)
+	query := fmt.Sprintf("SELECT id, date, daily_rate, annual_rate FROM cdi_history %s ORDER BY date DESC LIMIT ?", where)
+	args = append(args, limit)
+	rows, err := d.Conn.Query(query, args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []CDIRecord
+	for rows.Next() {
+		var r CDIRecord
+		rows.Scan(&r.ID, &r.Date, &r.DailyRate, &r.AnnualRate)
+		out = append(out, r)
+	}
+	return out, nil
+}
+
+func (d *DB) CurrentCDI() (*CDIRecord, error) {
+	r := &CDIRecord{}
+	err := d.Conn.QueryRow("SELECT id, date, daily_rate, annual_rate FROM cdi_history ORDER BY date DESC LIMIT 1").
+		Scan(&r.ID, &r.Date, &r.DailyRate, &r.AnnualRate)
+	if err == sql.ErrNoRows {
+		return nil, nil
+	}
+	return r, err
+}
+
+// IPCA
+func (d *DB) InsertIPCA(date string, monthly float64, acc12m *float64) error {
+	_, err := d.Conn.Exec(`INSERT OR IGNORE INTO ipca_history (date, monthly_rate, accumulated_12m) VALUES (?,?,?)`,
+		date, monthly, acc12m)
+	return err
+}
+
+func (d *DB) ListIPCA(limit int, from, to string) ([]IPCARecord, error) {
+	where, args := marketWhere(from, to)
+	query := fmt.Sprintf("SELECT id, date, monthly_rate, accumulated_12m FROM ipca_history %s ORDER BY date DESC LIMIT ?", where)
+	args = append(args, limit)
+	rows, err := d.Conn.Query(query, args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []IPCARecord
+	for rows.Next() {
+		var r IPCARecord
+		rows.Scan(&r.ID, &r.Date, &r.MonthlyRate, &r.Accumulated12m)
+		out = append(out, r)
+	}
+	return out, nil
+}
+
+func (d *DB) CurrentIPCA() (*IPCARecord, error) {
+	r := &IPCARecord{}
+	err := d.Conn.QueryRow("SELECT id, date, monthly_rate, accumulated_12m FROM ipca_history ORDER BY date DESC LIMIT 1").
+		Scan(&r.ID, &r.Date, &r.MonthlyRate, &r.Accumulated12m)
+	if err == sql.ErrNoRows {
+		return nil, nil
+	}
+	return r, err
+}
+
+// FX
+func (d *DB) InsertFX(date, pair string, rate float64) error {
+	_, err := d.Conn.Exec(`INSERT OR IGNORE INTO fx_rates (date, pair, rate) VALUES (?,?,?)`, date, pair, rate)
+	return err
+}
+
+func (d *DB) ListFX(limit int, pair, from, to string) ([]FXRecord, error) {
+	where := "WHERE 1=1"
+	args := []any{}
+	if pair != "" {
+		where += " AND pair = ?"
+		args = append(args, pair)
+	}
+	if from != "" {
+		where += " AND date >= ?"
+		args = append(args, from)
+	}
+	if to != "" {
+		where += " AND date <= ?"
+		args = append(args, to)
+	}
+	query := fmt.Sprintf("SELECT id, date, pair, rate FROM fx_rates %s ORDER BY date DESC LIMIT ?", where)
+	args = append(args, limit)
+	rows, err := d.Conn.Query(query, args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []FXRecord
+	for rows.Next() {
+		var r FXRecord
+		rows.Scan(&r.ID, &r.Date, &r.Pair, &r.Rate)
+		out = append(out, r)
+	}
+	return out, nil
+}
+
+func (d *DB) CurrentFX() ([]FXRecord, error) {
+	rows, err := d.Conn.Query(`SELECT DISTINCT pair FROM fx_rates`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var pairs []string
+	for rows.Next() {
+		var p string
+		rows.Scan(&p)
+		pairs = append(pairs, p)
+	}
+	var out []FXRecord
+	for _, p := range pairs {
+		var r FXRecord
+		err := d.Conn.QueryRow("SELECT id, date, pair, rate FROM fx_rates WHERE pair = ? ORDER BY date DESC LIMIT 1", p).
+			Scan(&r.ID, &r.Date, &r.Pair, &r.Rate)
+		if err == nil {
+			out = append(out, r)
+		}
+	}
+	return out, nil
+}
+
+func marketWhere(from, to string) (string, []any) {
+	where := "WHERE 1=1"
+	args := []any{}
+	if from != "" {
+		where += " AND date >= ?"
+		args = append(args, from)
+	}
+	if to != "" {
+		where += " AND date <= ?"
+		args = append(args, to)
+	}
+	return where, args
+}
--- a/internal/db/schema.go
+++ b/internal/db/schema.go
@@ -0,0 +1,73 @@
+package db
+
+const schema = `
+CREATE TABLE IF NOT EXISTS companies (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ticker TEXT,
+    name TEXT NOT NULL,
+    cnpj TEXT UNIQUE NOT NULL,
+    cvm_code TEXT,
+    sector TEXT,
+    status TEXT NOT NULL DEFAULT 'ATIVO',
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS filings (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    external_id TEXT UNIQUE NOT NULL,
+    company_id INTEGER REFERENCES companies(id),
+    cnpj TEXT NOT NULL,
+    category TEXT NOT NULL,
+    type TEXT,
+    species TEXT,
+    subject TEXT,
+    reference_date TEXT,
+    delivery_date DATETIME NOT NULL,
+    protocol TEXT,
+    version TEXT,
+    download_url TEXT,
+    importance INTEGER DEFAULT 1,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS selic_history (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    date TEXT UNIQUE NOT NULL,
+    daily_rate REAL NOT NULL,
+    annual_rate REAL,
+    target_rate REAL
+);
+
+CREATE TABLE IF NOT EXISTS cdi_history (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    date TEXT UNIQUE NOT NULL,
+    daily_rate REAL NOT NULL,
+    annual_rate REAL
+);
+
+CREATE TABLE IF NOT EXISTS ipca_history (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    date TEXT UNIQUE NOT NULL,
+    monthly_rate REAL NOT NULL,
+    accumulated_12m REAL
+);
+
+CREATE TABLE IF NOT EXISTS fx_rates (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    date TEXT NOT NULL,
+    pair TEXT NOT NULL,
+    rate REAL NOT NULL,
+    UNIQUE(date, pair)
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS companies_fts USING fts5(
+    name, ticker, sector, cnpj,
+    content='companies', content_rowid='id'
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS filings_fts USING fts5(
+    subject, category, type,
+    content='filings', content_rowid='id'
+);
+`
--- a/internal/db/search.go
+++ b/internal/db/search.go
@@ -0,0 +1,40 @@
+package db
+
+func (d *DB) SearchCompanies(query string, limit int) ([]Company, error) {
+	rows, err := d.Conn.Query(`
+		SELECT c.id, COALESCE(c.ticker,''), c.name, c.cnpj, COALESCE(c.cvm_code,''), COALESCE(c.sector,''), c.status, c.created_at, c.updated_at
+		FROM companies_fts f JOIN companies c ON f.rowid = c.id
+		WHERE companies_fts MATCH ? LIMIT ?`, query, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []Company
+	for rows.Next() {
+		var c Company
+		rows.Scan(&c.ID, &c.Ticker, &c.Name, &c.CNPJ, &c.CVMCode, &c.Sector, &c.Status, &c.CreatedAt, &c.UpdatedAt)
+		out = append(out, c)
+	}
+	return out, nil
+}
+
+func (d *DB) SearchFilings(query string, limit int) ([]Filing, error) {
+	rows, err := d.Conn.Query(`
+		SELECT fi.id, fi.external_id, fi.company_id, fi.cnpj, fi.category, COALESCE(fi.type,''), COALESCE(fi.species,''),
+			COALESCE(fi.subject,''), COALESCE(fi.reference_date,''), fi.delivery_date, COALESCE(fi.protocol,''),
+			COALESCE(fi.version,''), COALESCE(fi.download_url,''), fi.importance, fi.created_at
+		FROM filings_fts f JOIN filings fi ON f.rowid = fi.id
+		WHERE filings_fts MATCH ? LIMIT ?`, query, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []Filing
+	for rows.Next() {
+		var f Filing
+		rows.Scan(&f.ID, &f.ExternalID, &f.CompanyID, &f.CNPJ, &f.Category, &f.Type, &f.Species,
+			&f.Subject, &f.ReferenceDate, &f.DeliveryDate, &f.Protocol, &f.Version, &f.DownloadURL, &f.Importance, &f.CreatedAt)
+		out = append(out, f)
+	}
+	return out, nil
+}
--- a/internal/db/sqlite.go
+++ b/internal/db/sqlite.go
@@ -0,0 +1,52 @@
+package db
+
+import (
+	"database/sql"
+	"fmt"
+	"log/slog"
+	"os"
+	"path/filepath"
+
+	_ "modernc.org/sqlite"
+)
+
+type DB struct {
+	Conn *sql.DB
+}
+
+func New(dbPath string) (*DB, error) {
+	dir := filepath.Dir(dbPath)
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return nil, fmt.Errorf("create db dir: %w", err)
+	}
+
+	conn, err := sql.Open("sqlite", dbPath+"?_journal_mode=WAL&_busy_timeout=5000")
+	if err != nil {
+		return nil, fmt.Errorf("open db: %w", err)
+	}
+
+	conn.SetMaxOpenConns(1) // SQLite single-writer
+
+	if _, err := conn.Exec(schema); err != nil {
+		return nil, fmt.Errorf("run schema: %w", err)
+	}
+
+	slog.Info("database initialized", "path", dbPath)
+	return &DB{Conn: conn}, nil
+}
+
+func (d *DB) Close() error {
+	return d.Conn.Close()
+}
+
+func (d *DB) IsEmpty() bool {
+	var count int
+	d.Conn.QueryRow("SELECT COUNT(*) FROM companies").Scan(&count)
+	return count == 0
+}
+
+func (d *DB) IsMarketEmpty() bool {
+	var count int
+	d.Conn.QueryRow("SELECT COUNT(*) FROM selic_history").Scan(&count)
+	return count == 0
+}