Full-text search is one of those features that looks simple until you have to ship it. Typos fail silently. Category filters conflict with relevance ranking. The database LIKE query that worked at 10,000 rows grinds to a halt at 100,000. This tutorial walks through building a real search API in Go using Fiber and Meilisearch, complete with filter support, typo tolerance configuration, and a MySQL LIKE fallback for resilience.
This is roughly the architecture running search across 1,600+ cybersecurity articles at AYI NEDJIMI Consultants.
Setup #
go mod init search-api
go get github.com/gofiber/fiber/v2
go get github.com/meilisearch/meilisearch-go
go get github.com/go-sql-driver/mysql
Run Meilisearch:
docker run -d -p 7700:7700 \
-e MEILI_MASTER_KEY=your_master_key \
getmeili/meilisearch:latest
Project structure #
search-api/
├── main.go
├── config/
│ └── config.go
├── search/
│ ├── meili.go
│ └── fallback.go
└── handlers/
└── search.go
Data model #
// search/meili.go
package search
// Article is the document type stored in Meilisearch and MySQL.
type Article struct {
ID string `json:"id"`
Title string `json:"title"`
Slug string `json:"slug"`
Content string `json:"content"` // plain text, stripped of HTML
Category string `json:"category"` // news, guide, analyse, blog, checklist
Difficulty string `json:"difficulty"` // beginner, intermediate, advanced
DocType string `json:"doc_type"` // article, checklist, glossary
Tags []string `json:"tags"`
PublishedAt int64 `json:"published_at"` // Unix timestamp for sort
}
// SearchResult wraps hits with metadata.
type SearchResult struct {
Hits []Article `json:"hits"`
TotalHits int64 `json:"total_hits"`
ProcessingTimeMs int64 `json:"processing_time_ms"`
Query string `json:"query"`
Source string `json:"source"` // "meilisearch" or "mysql_fallback"
}
Meilisearch client initialization #
// search/meili.go (continued)
package search
import (
"fmt"
"log"
"github.com/meilisearch/meilisearch-go"
)
const IndexName = "articles"
type MeiliSearcher struct {
client meilisearch.ServiceManager
index meilisearch.IndexManager
}
func NewMeiliSearcher(host, apiKey string) (*MeiliSearcher, error) {
client := meilisearch.New(host, meilisearch.WithAPIKey(apiKey))
// Verify connectivity
if _, err := client.Health(); err != nil {
return nil, fmt.Errorf("meilisearch unreachable at %s: %w", host, err)
}
s := &MeiliSearcher{client: client}
if err := s.ensureIndex(); err != nil {
return nil, err
}
return s, nil
}
func (s *MeiliSearcher) ensureIndex() error {
// Get or create index
idx, err := s.client.GetIndex(IndexName)
if err != nil {
task, err := s.client.CreateIndex(&meilisearch.IndexConfig{
Uid: IndexName,
PrimaryKey: "id",
})
if err != nil {
return fmt.Errorf("create index: %w", err)
}
s.client.WaitForTask(task.TaskUID, nil)
idx, err = s.client.GetIndex(IndexName)
if err != nil {
return fmt.Errorf("get index after create: %w", err)
}
}
s.index = idx
return s.configureIndex()
}
func (s *MeiliSearcher) configureIndex() error {
task, err := s.index.UpdateSettings(&meilisearch.Settings{
SearchableAttributes: []string{
"title", // highest weight
"tags",
"content", // lowest weight
},
FilterableAttributes: []string{
"category",
"difficulty",
"doc_type",
},
SortableAttributes: []string{
"published_at",
},
RankingRules: []string{
"words",
"typo",
"proximity",
"attribute", // respects SearchableAttributes order
"sort",
"exactness",
},
TypoTolerance: &meilisearch.TypoTolerance{
Enabled: func() *bool { b := true; return &b }(),
MinWordSizeForTypos: meilisearch.MinWordSizeForTypos{
OneTypo: 4,
TwoTypos: 8,
},
},
Pagination: &meilisearch.Pagination{
MaxTotalHits: 10000,
},
})
if err != nil {
return fmt.Errorf("update settings: %w", err)
}
s.client.WaitForTask(task.TaskUID, nil)
log.Println("Meilisearch index configured.")
return nil
}
Index sync function #
Call this on startup and hook it to your CRUD operations.
// search/meili.go (continued)
func (s *MeiliSearcher) IndexDocuments(articles []Article) error {
if len(articles) == 0 {
return nil
}
task, err := s.index.AddDocuments(articles, "id")
if err != nil {
return fmt.Errorf("add documents: %w", err)
}
s.client.WaitForTask(task.TaskUID, nil)
log.Printf("Indexed %d documents.", len(articles))
return nil
}
func (s *MeiliSearcher) DeleteDocument(id string) error {
task, err := s.index.DeleteDocument(id)
if err != nil {
return fmt.Errorf("delete document %s: %w", id, err)
}
s.client.WaitForTask(task.TaskUID, nil)
return nil
}
Search with filters #
// search/meili.go (continued)
type SearchParams struct {
Query string
Category string
Difficulty string
DocType string
Limit int64
Offset int64
}
func (s *MeiliSearcher) Search(params SearchParams) (*SearchResult, error) {
if params.Limit <= 0 {
params.Limit = 10
}
if params.Limit > 100 {
params.Limit = 100
}
// Build filter expression
var filters []string
if params.Category != "" {
filters = append(filters, fmt.Sprintf("category = %q", params.Category))
}
if params.Difficulty != "" {
filters = append(filters, fmt.Sprintf("difficulty = %q", params.Difficulty))
}
if params.DocType != "" {
filters = append(filters, fmt.Sprintf("doc_type = %q", params.DocType))
}
filterStr := ""
for i, f := range filters {
if i == 0 {
filterStr = f
} else {
filterStr += " AND " + f
}
}
req := &meilisearch.SearchRequest{
Limit: params.Limit,
Offset: params.Offset,
AttributesToRetrieve: []string{
"id", "title", "slug", "category",
"difficulty", "doc_type", "tags", "published_at",
},
// Don't return full content in search results
}
if filterStr != "" {
req.Filter = filterStr
}
resp, err := s.index.Search(params.Query, req)
if err != nil {
return nil, err
}
hits := make([]Article, 0, len(resp.Hits))
for _, h := range resp.Hits {
// Meilisearch returns hits as map[string]interface{}
b, _ := json.Marshal(h)
var a Article
if err := json.Unmarshal(b, &a); err == nil {
hits = append(hits, a)
}
}
return &SearchResult{
Hits: hits,
TotalHits: resp.TotalHits,
ProcessingTimeMs: resp.ProcessingTimeMs,
Query: params.Query,
Source: "meilisearch",
}, nil
}
MySQL fallback #
When Meilisearch is down (restart, OOM, maintenance), fall back to MySQL LIKE. It's slower and has no typo tolerance, but it keeps the API responding.
// search/fallback.go
package search
import (
"database/sql"
"fmt"
"strings"
"time"
_ "github.com/go-sql-driver/mysql"
)
type MySQLFallback struct {
db *sql.DB
}
func NewMySQLFallback(dsn string) (*MySQLFallback, error) {
db, err := sql.Open("mysql", dsn)
if err != nil {
return nil, err
}
db.SetMaxOpenConns(10)
db.SetConnMaxLifetime(5 * time.Minute)
return &MySQLFallback{db: db}, nil
}
func (m *MySQLFallback) Search(params SearchParams) (*SearchResult, error) {
query := "%" + strings.ReplaceAll(params.Query, "%", "\\%") + "%"
args := []interface{}{query, query}
where := "WHERE (title LIKE ? OR content LIKE ?)"
if params.Category != "" {
where += " AND category = ?"
args = append(args, params.Category)
}
if params.Difficulty != "" {
where += " AND difficulty = ?"
args = append(args, params.Difficulty)
}
if params.DocType != "" {
where += " AND doc_type = ?"
args = append(args, params.DocType)
}
// Count total
var total int64
countSQL := fmt.Sprintf("SELECT COUNT(*) FROM articles %s", where)
_ = m.db.QueryRow(countSQL, args...).Scan(&total)
// Fetch page
args = append(args, params.Limit, params.Offset)
rows, err := m.db.Query(
fmt.Sprintf(`SELECT id, title, slug, category, difficulty, doc_type, published_at
FROM articles %s ORDER BY published_at DESC LIMIT ? OFFSET ?`, where),
args...,
)
if err != nil {
return nil, err
}
defer rows.Close()
var hits []Article
for rows.Next() {
var a Article
if err := rows.Scan(&a.ID, &a.Title, &a.Slug,
&a.Category, &a.Difficulty, &a.DocType, &a.PublishedAt); err != nil {
continue
}
hits = append(hits, a)
}
return &SearchResult{
Hits: hits,
TotalHits: total,
Query: params.Query,
Source: "mysql_fallback",
}, nil
}
HTTP handler #
// handlers/search.go
package handlers
import (
"encoding/json"
"log"
"github.com/gofiber/fiber/v2"
"search-api/search"
)
type SearchHandler struct {
meili *search.MeiliSearcher
fallback *search.MySQLFallback
}
func NewSearchHandler(meili *search.MeiliSearcher, fallback *search.MySQLFallback) *SearchHandler {
return &SearchHandler{meili: meili, fallback: fallback}
}
func (h *SearchHandler) Handle(c *fiber.Ctx) error {
params := search.SearchParams{
Query: c.Query("q", ""),
Category: c.Query("cat", ""),
Difficulty: c.Query("diff", ""),
DocType: c.Query("type", ""),
Limit: int64(c.QueryInt("limit", 10)),
Offset: int64(c.QueryInt("offset", 0)),
}
if len([]rune(params.Query)) > 200 {
return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{
"error": "query too long",
})
}
result, err := h.meili.Search(params)
if err != nil {
log.Printf("Meilisearch error: %v — falling back to MySQL", err)
result, err = h.fallback.Search(params)
if err != nil {
return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{
"error": "search unavailable",
})
}
}
return c.JSON(result)
}
Wiring it up in main.go #
// main.go
package main
import (
"log"
"os"
"github.com/gofiber/fiber/v2"
"search-api/handlers"
"search-api/search"
)
func main() {
meiliHost := os.Getenv("MEILI_HOST") // e.g. "http://127.0.0.1:7700"
meiliKey := os.Getenv("MEILI_MASTER_KEY")
mysqlDSN := os.Getenv("MYSQL_DSN") // e.g. "user:pass@tcp(127.0.0.1:3306)/dbname"
meili, err := search.NewMeiliSearcher(meiliHost, meiliKey)
if err != nil {
log.Fatalf("Failed to connect to Meilisearch: %v", err)
}
fallback, err := search.NewMySQLFallback(mysqlDSN)
if err != nil {
log.Fatalf("Failed to connect to MySQL: %v", err)
}
app := fiber.New(fiber.Config{
ErrorHandler: func(c *fiber.Ctx, err error) error {
return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{
"error": err.Error(),
})
},
})
searchHandler := handlers.NewSearchHandler(meili, fallback)
app.Get("/api/search", searchHandler.Handle)
// Reindex endpoint (protect with auth middleware in production)
app.Post("/admin/search/reindex", func(c *fiber.Ctx) error {
var articles []search.Article
if err := c.BodyParser(&articles); err != nil {
return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": err.Error()})
}
if err := meili.IndexDocuments(articles); err != nil {
return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{"error": err.Error()})
}
return c.JSON(fiber.Map{"indexed": len(articles)})
})
log.Fatal(app.Listen(":4001"))
}
Test it #
curl "http://localhost:4001/api/search?q=pentest"
curl "http://localhost:4001/api/search?q=NIS+2&cat=guide&diff=intermediate&limit=5"
curl "http://localhost:4001/api/search?q=penetartion+tesitng"
Key tuning decisions #
** SearchableAttributes order matters.** Meilisearch's
attribute
ranking rule rewards matches in earlier attributes. Putting title
first means a title match outranks a content match, which is almost always what you want.Pagination cap. The MaxTotalHits: 10000
setting prevents Meilisearch from doing expensive full-index scans for pagination deep into results. If users never go past page 20 at 10 results/page, set this to 200.
Fallback opacity. The source
field in SearchResult
tells the frontend (and your monitoring) when it's getting degraded results. Log every fallback occurrence — if Meilisearch is down and you're not paged, you won't know until users complain.
On-startup sync. Pull all published articles from MySQL on startup and call IndexDocuments
. For 10,000+ documents this takes 2–5 seconds; for 100,000+ batch in chunks of 5,000. This ensures your index is always consistent even after a Meilisearch restart.
This pattern — Meilisearch primary, MySQL LIKE fallback — gives you production-grade search with no single point of failure and a codebase any Go developer can reason about.
source & further reading
dev.to — original article
The Most Dangerous Kind of Good
The AI Coding Tool You Use Is Now a Hiring Signal
Guard Scripts Don't Stop an AI Agent From Publishing Your Draft. It Has a Shell