| ID | 20 |Name | 21 |Company | 22 |Phone | 23 |
|---|---|---|---|
| {{ .ID }} | 28 |{{ .Name }} | 29 |{{ .Company }} | 30 |{{ .Phone }} | 31 |
36 | No data yet, try generating a new row. 37 |
38 | {{ end }} 39 | 40 |42 | Region: {{ .Region }} 43 |
44 | 45 | 46 | 47 | -------------------------------------------------------------------------------- /cmd/litefs-example/main.go: -------------------------------------------------------------------------------- 1 | package main 2 | 3 | import ( 4 | "context" 5 | "database/sql" 6 | _ "embed" 7 | "flag" 8 | "fmt" 9 | "html/template" 10 | "log" 11 | "math/rand" 12 | "net/http" 13 | "os" 14 | "time" 15 | 16 | "github.com/brianvoe/gofakeit/v6" 17 | _ "github.com/mattn/go-sqlite3" 18 | ) 19 | 20 | // Command line flags. 21 | var ( 22 | dsn = flag.String("dsn", "", "datasource name") 23 | addr = flag.String("addr", ":8080", "bind address") 24 | ) 25 | 26 | var db *sql.DB 27 | 28 | //go:embed schema.sql 29 | var schemaSQL string 30 | 31 | func main() { 32 | log.SetFlags(0) 33 | rand.Seed(time.Now().UnixNano()) 34 | 35 | if err := run(context.Background()); err != nil { 36 | fmt.Fprintln(os.Stderr, err) 37 | os.Exit(1) 38 | } 39 | } 40 | 41 | func run(ctx context.Context) (err error) { 42 | flag.Parse() 43 | 44 | if *dsn == "" { 45 | return fmt.Errorf("dsn required") 46 | } else if *addr == "" { 47 | return fmt.Errorf("bind address required") 48 | } 49 | 50 | // Connect to SQLite database. 51 | db, err = sql.Open("sqlite3", *dsn) 52 | if err != nil { 53 | return fmt.Errorf("open db: %w", err) 54 | } 55 | defer db.Close() 56 | 57 | log.Printf("database opened at %s", *dsn) 58 | 59 | // Run migration. 60 | if _, err := db.Exec(schemaSQL); err != nil { 61 | return fmt.Errorf("cannot migrate schema: %w", err) 62 | } 63 | 64 | // Start HTTP server. 65 | http.HandleFunc("/", handleIndex) 66 | http.HandleFunc("/generate", handleGenerate) 67 | 68 | log.Printf("http server listening on %s", *addr) 69 | return http.ListenAndServe(*addr, nil) 70 | } 71 | 72 | //go:embed index.tmpl 73 | var indexTmplContent string 74 | var indexTmpl = template.Must(template.New("index").Parse(indexTmplContent)) 75 | 76 | func handleIndex(w http.ResponseWriter, r *http.Request) { 77 | // If a different region is specified, redirect to that region. 78 | if region := r.URL.Query().Get("region"); region != "" && region != os.Getenv("FLY_REGION") { 79 | log.Printf("redirecting from %q to %q", os.Getenv("FLY_REGION"), region) 80 | w.Header().Set("fly-replay", "region="+region) 81 | return 82 | } 83 | 84 | // Query for the most recently added people. 85 | rows, err := db.Query(` 86 | SELECT id, name, phone, company 87 | FROM persons 88 | ORDER BY id DESC 89 | LIMIT 10 90 | `) 91 | if err != nil { 92 | http.Error(w, err.Error(), http.StatusInternalServerError) 93 | return 94 | } 95 | defer rows.Close() 96 | 97 | // Collect rows into a slice. 98 | var persons []*Person 99 | for rows.Next() { 100 | var person Person 101 | if err := rows.Scan(&person.ID, &person.Name, &person.Phone, &person.Company); err != nil { 102 | http.Error(w, err.Error(), http.StatusInternalServerError) 103 | return 104 | } 105 | persons = append(persons, &person) 106 | } 107 | if err := rows.Close(); err != nil { 108 | http.Error(w, err.Error(), http.StatusInternalServerError) 109 | return 110 | } 111 | 112 | // Render the list to either text or HTML. 113 | tmplData := TemplateData{ 114 | Region: os.Getenv("FLY_REGION"), 115 | Persons: persons, 116 | } 117 | 118 | switch r.Header.Get("accept") { 119 | case "text/plain": 120 | fmt.Fprintf(w, "REGION: %s\n\n", tmplData.Region) 121 | for _, person := range tmplData.Persons { 122 | fmt.Fprintf(w, "- %s @ %s (%s)\n", person.Name, person.Company, person.Phone) 123 | } 124 | 125 | default: 126 | if err := indexTmpl.ExecuteTemplate(w, "index", tmplData); err != nil { 127 | http.Error(w, err.Error(), http.StatusInternalServerError) 128 | return 129 | } 130 | } 131 | } 132 | 133 | func handleGenerate(w http.ResponseWriter, r *http.Request) { 134 | // Only allow POST methods. 135 | if r.Method != "POST" { 136 | http.Error(w, "Method not allowed", http.StatusMethodNotAllowed) 137 | return 138 | } 139 | 140 | /* 141 | // If this node is not primary, look up and redirect to the current primary. 142 | primaryFilename := filepath.Join(filepath.Dir(*dsn), ".primary") 143 | primary, err := os.ReadFile(primaryFilename) 144 | if err != nil && !os.IsNotExist(err) { 145 | http.Error(w, err.Error(), http.StatusInternalServerError) 146 | return 147 | } 148 | if string(primary) != "" { 149 | log.Printf("redirecting to primary instance: %q", string(primary)) 150 | w.Header().Set("fly-replay", "instance="+string(primary)) 151 | return 152 | } 153 | */ 154 | 155 | // If this is the primary, attempt to write a record to the database. 156 | person := Person{ 157 | Name: gofakeit.Name(), 158 | Phone: gofakeit.Phone(), 159 | Company: gofakeit.Company(), 160 | } 161 | if _, err := db.ExecContext(r.Context(), `INSERT INTO persons (name, phone, company) VALUES (?, ?, ?)`, person.Name, person.Phone, person.Company); err != nil { 162 | http.Error(w, "Method not alllowed", http.StatusMethodNotAllowed) 163 | return 164 | } 165 | 166 | // Redirect back to the index page to view the new result. 167 | http.Redirect(w, r, r.Referer(), http.StatusFound) 168 | } 169 | 170 | type TemplateData struct { 171 | Region string 172 | Persons []*Person 173 | } 174 | 175 | type Person struct { 176 | ID int 177 | Name string 178 | Phone string 179 | Company string 180 | } 181 | -------------------------------------------------------------------------------- /cmd/litefs-example/schema.sql: -------------------------------------------------------------------------------- 1 | CREATE TABLE IF NOT EXISTS persons ( 2 | id INTEGER PRIMARY KEY AUTOINCREMENT, 3 | name TEXT NOT NULL, 4 | phone TEXT NOT NULL, 5 | company TEXT NOT NULL 6 | ); 7 | 8 | -------------------------------------------------------------------------------- /docker-compose.yml: -------------------------------------------------------------------------------- 1 | version: '3' 2 | services: 3 | nginx: 4 | build: 5 | context: ./docker-config/nginx 6 | ports: 7 | - "8080:80" 8 | primary: 9 | build: 10 | context: . 11 | args: 12 | - "LITEFS_CONFIG=litefs.static-lease.yml" 13 | ports: 14 | - "8081:8081" 15 | privileged: true 16 | environment: 17 | FLY_REGION: primary 18 | IS_PRIMARY: "true" 19 | replica1: 20 | build: 21 | context: . 22 | args: 23 | - "LITEFS_CONFIG=litefs.static-lease.yml" 24 | ports: 25 | - "8082:8081" 26 | privileged: true 27 | environment: 28 | FLY_REGION: replica1 29 | IS_PRIMARY: "false" 30 | -------------------------------------------------------------------------------- /docker-config/README.md: -------------------------------------------------------------------------------- 1 | LiteFS Example Application with Docker 2 | ====================================== 3 | 4 | ## Prerequisites 5 | 6 | You need to [install Docker][] (and docker-compose, which is included in all 7 | recent releases of Docker). 8 | 9 | [install Docker]: https://docs.docker.com/engine/install/ 10 | 11 | ## Usage 12 | 13 | ### Running the app 14 | 15 | You can run the application with this command (from the top-level directory 16 | of the repo): 17 | 18 | ```bash 19 | docker-compose up 20 | ``` 21 | 22 | ### Using the app locally 23 | 24 | The app is configured with the following containers: 25 | 26 | * `primary` - this is the application with LiteFS running as primary 27 | (all writes happen on this node) 28 | * `replica1` - this is the application running with LiteFS as a replica 29 | * `nginx` - nginx configured as a load balancer, and also configured to 30 | route all `POST` requests to the primary node 31 | 32 | Each of these is available to test out locally: 33 | 34 | * http://localhost:8080 - the load balancer 35 | * http://localhost:8081 - the primary 36 | * http://localhost:8082 - the replica 37 | 38 | You can test generating records on each node (it will fail if attempted on 39 | the replica). -------------------------------------------------------------------------------- /docker-config/etc/litefs.static-lease.yml: -------------------------------------------------------------------------------- 1 | # note: there should be one template for this, which you can update as necessary. 2 | # note: had to leave the getting started guide and go to the lease management section bc not using fly 3 | # note: lease.hostname and lease.advertise-url are not clear 4 | # note: we should have an example docker-compose setup with everything working both with consul 5 | # and static leases 6 | # This directory is where your application will access the database. 7 | fuse: 8 | dir: "/litefs" 9 | 10 | # This directory is where LiteFS will store internal data. 11 | # You must place this directory on a persistent volume. 12 | data: 13 | dir: "/var/lib/litefs" 14 | 15 | # The lease section defines how LiteFS creates a cluster and 16 | # implements leader election. For dynamic clusters, use the 17 | # "consul". This allows the primary to change automatically when 18 | # the current primary goes down. For a simpler setup, use 19 | # "static" which assigns a single node to be the primary and does 20 | # not failover. 21 | lease: 22 | # Required. Must be either "consul" or "static". 23 | type: "static" 24 | 25 | # Required. The URL for this node's LiteFS API. 26 | # Should match HTTP port. 27 | advertise-url: "http://primary:20202" 28 | 29 | # Specifies whether the node can become the primary. If using 30 | # "static" leasing, this should be set to true on the primary 31 | # and false on the replicas. 32 | candidate: $IS_PRIMARY 33 | 34 | exec: 35 | - cmd: "litefs-example -addr :8081 -dsn /litefs/db" 36 | -------------------------------------------------------------------------------- /docker-config/nginx/Dockerfile: -------------------------------------------------------------------------------- 1 | FROM nginx:alpine 2 | 3 | COPY ./nginx.conf /etc/nginx/nginx.conf 4 | EXPOSE 80 5 | CMD ["nginx", "-g", "daemon off;"] -------------------------------------------------------------------------------- /docker-config/nginx/nginx.conf: -------------------------------------------------------------------------------- 1 | http { 2 | upstream primary { 3 | server primary:8081; 4 | } 5 | upstream all { 6 | server primary:8081; 7 | server replica1:8081; 8 | } 9 | server { 10 | listen 80; 11 | location / { 12 | if ($request_method ~ "(PUT|POST|PATCH|DELETE)") { 13 | proxy_pass http://primary; 14 | } 15 | proxy_pass http://all; 16 | } 17 | } 18 | } 19 | 20 | events { } -------------------------------------------------------------------------------- /fly-io-config/README.md: -------------------------------------------------------------------------------- 1 | LiteFS Example Application on Fly.io 2 | ==================================== 3 | 4 | ## Prerequisites 5 | 6 | First, you'll need to install [`flyctl`][] and then [sign up for a free account][signup]. 7 | 8 | [`flyctl`]: https://fly.io/docs/hands-on/install-flyctl/ 9 | [signup]: https://fly.io/docs/hands-on/sign-up/ 10 | 11 | 12 | ## Usage 13 | 14 | ### Creating the application 15 | 16 | First, we'll need to create our application on [Fly.io](https://fly.io). This 17 | will prompt you for a name or you can autogenerate one for this example. 18 | Remember this name as we'll need it later. 19 | 20 | ```sh 21 | fly launch --region ord --no-deploy 22 | ``` 23 | 24 | The launch command will create a `fly.toml` file and set the primary region to 25 | Chicago (`ord`) but will not launch the app. 26 | 27 | 28 | ### Creating a volume 29 | 30 | Next, we need to set up a persistent volume in our primary region so that our 31 | data is not lost between restarts. 32 | 33 | ```sh 34 | fly volumes create -r ord --size 1 litefs 35 | ``` 36 | 37 | And add a mount to this volume in your `fly.toml` file: 38 | 39 | ```toml 40 | [mounts] 41 | source = "litefs" 42 | destination = "/var/lib/litefs" 43 | ``` 44 | 45 | ### Setting up Consul 46 | 47 | LiteFS uses [Consul](https://consul.io) for its distributed lease. You can find 48 | instructions for using Fly.io's free multi-tenant Consul in the 49 | [Lease Management][] section of the Getting Started guide. 50 | 51 | [Lease Management]: https://fly.io/docs/litefs/getting-started/#lease-configuration 52 | 53 | 54 | ### Launching your app 55 | 56 | The next step is to launch & deploy your app with the following command: 57 | 58 | ```sh 59 | fly deploy 60 | ``` 61 | 62 | The application should build and deploy and you should see it up in running 63 | after a minute or so. You can go to `https://$APPNAME.fly.dev/` and see your 64 | application running live. 65 | 66 | The application is a simple interface for generating fake records. It's just 67 | for illustrating how LiteFS can easily replicate your data between nodes. 68 | 69 | When you click the _"Generate Record"_ button, it will create that row in a 70 | local SQLite database that is running on a LiteFS file system. Any other node 71 | running LiteFS will automatically get those updates and apply them to their 72 | local copy of the database. That lets every node keep an exact copy of the same 73 | database. 74 | 75 | 76 | ### Launching more regions 77 | 78 | This example application is configured to run as a primary only in the 79 | `PRIMARY_REGION` (which is Chicago). It's best practice to run two or more 80 | instances in the primary region and then you can add instances in additional 81 | regions to reduce latency for your users. 82 | 83 | You can clone the configuration of the machine to other regions by using the 84 | `fly m clone` command. The `--select` flag lets you choose from a list of 85 | existing machines to clone. 86 | 87 | ```sh 88 | # Make a second instance in your primary region. 89 | fly m clone --select --region ord 90 | 91 | # Make additional instances in regions around the world (London, Sydney, etc). 92 | fly m clone --select --region lhr 93 | fly m clone --select --region syd 94 | ``` 95 | -------------------------------------------------------------------------------- /fly-io-config/etc/litefs.yml: -------------------------------------------------------------------------------- 1 | # The fuse section describes settings for the FUSE file system. This file system 2 | # is used as a thin layer between the SQLite client in your application and the 3 | # storage on disk. It intercepts disk writes to determine transaction boundaries 4 | # so that those transactions can be saved and shipped to replicas. 5 | fuse: 6 | dir: "/litefs" 7 | 8 | # The data section describes settings for the internal LiteFS storage. We'll 9 | # mount a volume to the data directory so it can be persisted across restarts. 10 | # However, this data should not be accessed directly by the user application. 11 | data: 12 | dir: "/var/lib/litefs" 13 | 14 | # This flag ensure that LiteFS continues to run if there is an issue on starup. 15 | # It makes it easy to ssh in and debug any issues you might be having rather 16 | # than continually restarting on initialization failure. 17 | exit-on-error: false 18 | 19 | # This section defines settings for the option HTTP proxy. 20 | # This proxy can handle primary forwarding & replica consistency 21 | # for applications that use a single SQLite database. 22 | proxy: 23 | addr: ":8080" 24 | target: "localhost:8081" 25 | db: "db" 26 | passthrough: 27 | - "*.ico" 28 | - "*.png" 29 | 30 | # This section defines a list of commands to run after LiteFS has connected 31 | # and sync'd with the cluster. You can run multiple commands but LiteFS expects 32 | # the last command to be long-running (e.g. an application server). When the 33 | # last command exits, LiteFS is shut down. 34 | exec: 35 | - cmd: "litefs-example -addr :8081 -dsn /litefs/db" 36 | 37 | # The lease section specifies how the cluster will be managed. We're using the 38 | # "consul" lease type so that our application can dynamically change the primary. 39 | # 40 | # These environment variables will be available in your Fly.io application. 41 | lease: 42 | type: "consul" 43 | advertise-url: "http://${HOSTNAME}.vm.${FLY_APP_NAME}.internal:20202" 44 | candidate: ${FLY_REGION == PRIMARY_REGION} 45 | promote: true 46 | 47 | consul: 48 | url: "${FLY_CONSUL_URL}" 49 | key: "litefs/${FLY_APP_NAME}" 50 | 51 | -------------------------------------------------------------------------------- /go.mod: -------------------------------------------------------------------------------- 1 | module github.com/superfly/litefs-example 2 | 3 | go 1.19 4 | 5 | require github.com/brianvoe/gofakeit/v6 v6.18.0 6 | 7 | require github.com/mattn/go-sqlite3 v1.14.15 // indirect 8 | -------------------------------------------------------------------------------- /go.sum: -------------------------------------------------------------------------------- 1 | github.com/brianvoe/gofakeit/v6 v6.18.0 h1:tDQ4zJVFQHaJKvY9xYSqGN4S7noZU/doFn15/aNbhCU= 2 | github.com/brianvoe/gofakeit/v6 v6.18.0/go.mod h1:Ow6qC71xtwm79anlwKRlWZW6zVq9D2XHE4QSSMP/rU8= 3 | github.com/mattn/go-sqlite3 v1.14.15 h1:vfoHhTN1af61xCRSWzFIWzx2YskyMTwHLrExkBOjvxI= 4 | github.com/mattn/go-sqlite3 v1.14.15/go.mod h1:2eHXhiwb8IkHr+BDWZGa96P6+rkvnG63S2DGjv9HUNg= 5 | --------------------------------------------------------------------------------