fips_lookup 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba43694a14b899305f855a2510c338388fa8b28c890357b0cb6060a5d1b3eb25
-  data.tar.gz: 462f6b6a2818fc6a49292edb07f71a9fcb83997862bdae0fa76dbd63f268240f
+  metadata.gz: 919f1f05158a82904ea9d2dbf8713161dd1a606887e7d9cd67a008527445dc6c
+  data.tar.gz: 6729e4bfcacb070fdd1ca18d96e2fe8b28027fd1b8f9bd107ece3baf31146a63
 SHA512:
-  metadata.gz: a77a8a9057ca98f694c843b7e7cbdc9e32d1d189f79b5a6957a0b2089db3724a079d7b4faa16a7182995741554a82ed7bcca8df3e533654b78d3adc20fe44fd7
-  data.tar.gz: 3421f5e848185d4b48c75440193ca0fccc9f2dcba6c73c75fd9fca0d230c77e471e9d8bceae7e4a272f518da94c78a3458c68d58ad91dae0e544f06a8c68cd07
+  metadata.gz: 87a6cc7f761894dde59bc809e31d4b5f1ad32a79af67aee9adc1253bebab32e999753df872e44df91663d4e81d243247cb000b05d4f4b478abca6ac18020b5b2
+  data.tar.gz: a7f74a403e70c4807e7d1472acb40e431f85d6e7aae2cf7faae743bf5dd797cbcc2c5d47624c29d0ffeb5fbba1ec65fac7d08c8f05ad3937dc52b9bdd0483184

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.2
   NewCops: enable
 
 Style/StringLiterals:

data/Gemfile.lock

@@ -1,79 +1,86 @@
 PATH
   remote: .
   specs:
-    fips_lookup (0.2.1)
-      csv (~> 3.0)
+    fips_lookup (1.0.0)
+      sqlite3 (~> 2.0)
+      zeitwerk (~> 2.8)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.2)
+    ast (2.4.3)
+    benchmark (0.5.0)
     csv (3.3.6)
-    diff-lcs (1.5.1)
+    diff-lcs (1.6.2)
     erb (6.0.7)
-    io-console (0.9.3)
+    io-console (0.9.4)
     irb (1.18.0)
       pp (>= 0.6.0)
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.7.1)
-    language_server-protocol (3.17.0.3)
+    json (3.0.2)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
     logger (1.7.0)
     ostruct (0.6.3)
-    parallel (1.24.0)
-    parser (3.3.0.5)
+    parallel (2.3.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
     pp (0.6.4)
       prettyprint
     prettyprint (0.2.0)
     prism (1.9.0)
-    racc (1.7.3)
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.1.0)
+    rake (13.4.2)
     rbs (4.2.0)
       logger
       prism (>= 1.6.0)
       tsort
-    rdoc (8.0.0)
+    rdoc (8.1.0)
       erb
       prism (>= 1.6.0)
       rbs (>= 4.0.0)
       tsort
-    regexp_parser (2.9.0)
+    regexp_parser (2.13.1)
     reline (0.7.0)
       io-console (~> 0.5)
-    rexml (3.2.6)
-    rspec (3.13.0)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.0)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.0)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.0)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.1)
-    rubocop (1.62.1)
-      json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
-      parallel (~> 1.10)
+    rspec-support (3.13.7)
+    rubocop (1.91.0)
+      json (>= 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.31.2)
-      parser (>= 3.3.0.4)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
     ruby-progressbar (1.13.0)
+    sqlite3 (2.9.6-arm64-darwin)
     tsort (0.2.0)
-    unicode-display_width (2.5.0)
+    unicode-display_width (3.3.0)
+      unicode-emoji (~> 4.3)
+    unicode-emoji (4.3.0)
+    zeitwerk (2.8.3)
 
 PLATFORMS
   arm64-darwin-21
@@ -81,6 +88,8 @@ PLATFORMS
   arm64-darwin-25
 
 DEPENDENCIES
+  benchmark (~> 0.2)
+  csv (~> 3.0)
   fips_lookup!
   irb
   ostruct

data/README.md

@@ -1,198 +1,142 @@
-# FipsLookup
+# FIPS Lookup
 
-## Overview
-
-Fips_lookup is a gem that functions as a lookup used to identify county and state FIPS codes.
-
-What are FIPS codes? The United States Federal Communications Commission (FCC) [says:](https://transition.fcc.gov/oet/info/maps/census/fips/fips.txt)
-
-> Federal Information Processing System (FIPS) Codes for States and Counties
->
-> FIPS codes are numbers which uniquely identify geographic areas.  The number of 
-digits in FIPS codes vary depending on the level of geography.  State-level FIPS
-codes have two digits, county-level FIPS codes have five digits of which the 
-first two are the FIPS code of the state to which the county belongs.
-
-_Note:_ FIPS codes are updated by the US census department they can be seen and accessed [here](https://www.census.gov/library/reference/code-lists/ansi.html).
-
-<br>
-
-**Interesting challenge:** <br>
-Multiple states can have the same county name — 16 states have a "Wayne County". This means a state & county pair is required to lookup and return the proper FIPS code.
-This gem utilizes memoization to increase lookup efficiency to csv files without adding complexity to your app.
+`fips_lookup` provides lookups for U.S. states, counties, and county subdivisions using Census FIPS identifiers and names. Results are hashes containing the fields for the requested geography. Lookup data is stored in a bundled SQLite database and queried read-only at runtime.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add the gem to your application's Gemfile:
 
 ```ruby
-gem 'fips_lookup'
+gem "fips_lookup"
 ```
 
-And then execute:
+Then run `bundle install`.
 
-    $ bundle install
+## Usage
 
-Or install it yourself as:
+Require the gem if your application does not use Bundler's automatic loading:
 
-    $ gem install fips_lookup
+```ruby
+require "fips"
+```
 
-## Usage
-<br>
+### General lookup
 
-### County info from lookup:  [.county(state_param: "state", county_param: "county name", _return_nil: false_)](/fips_lookup/lib/fips_lookup.rb?#L24)
+`FIPS.lookup` dispatches to the state, county, or subdivision lookup based on the supplied identifiers:
 
-Find County specific details using memoized hash state and county input. [ Returns state code, county fips, county name, and county class codes ]
+```ruby
+FIPS.lookup(fips: "02")
+# => { fips: "02", abbr: "AK", name: "Alaska", ansi: "01785533" }
 
-Input the state name and county name and return the corresponding 5 digit FIPS code:
-```
-FipsLookup.county(state_param: "AL", county_param: "Autauga County") # => {:state_code=>"AL", :fips=>"01001", :name=>"Autauga County", :class_code=>"H1"}
-```
+FIPS.lookup(fips: "02060")
+# => county record for Bristol Bay Borough
 
-* `state_param` - (String) flexible - able to find the state using its' 2 letter abbreviation ("AL"), 2 digit FIPS number ("01"), state name ("Alabama"), or the state ANSI code ("01779775").
-* `county_param` - (String) must match spelling set by US Census Bureau, [resource library](https://www.census.gov/library/reference/code-lists/ansi.html)
-— "Autauga County" can be found, "Autauga" can not be found.
-* `return_nil` - (Boolean) is an optional parameter that when used overrides any Errors from input and returns an empty hash `{}`.
-    * Ex:  `FipsLookup.county(state_param: "AL", county_param: "Autauga", return_nil: true) # => {}`
+FIPS.lookup(fips: "0206009050")
+# => subdivision record for Bristol Bay census subarea
 
-    * Ex: Access the [:fips] symbol after a lookup `FipsLookup.county(state_param: "AL", county_param: "Autauga", return_nil: true)[:fips] # => nil`
+FIPS.lookup(state: "Alaska", county: "Bristol Bay Borough")
+# => county record for Bristol Bay Borough
 
-<br>
+FIPS.lookup(state: "Alaska", county: "Bristol Bay Borough",
+            subdivision: "Bristol Bay census subarea")
+# => subdivision record for Bristol Bay census subarea
+```
 
-**How does it work?:**
+FIPS codes must be strings so leading zeroes are preserved. The general dispatcher supports state FIPS (2 digits), county FIPS (5 digits), and full subdivision FIPS (10 digits). Contextual forms are also available through the specific lookup methods below.
 
-Class attribute hash: [`@county_fips = { ["state_code", "county name"] => {:state_code, :fips, :name, :class_code} }`](/fips_lookup/lib/fips_lookup.rb?#L21)
+### State lookup
 
-The `county_fips` hash is built of key value pairs that grows as the `.county` method is used. Calls to `county` first searches `@county_fips` attribute with `[state_code, county_param]` before opening `.csv` files.  Therefore any duplicate calls made to `county` will return the value stored in `@county_fips`.  Instance variable lasts the lifespan of the FipsLookup class.
-```
-FipsLookup.county_fips # => { ["AL", "Autauga County"] => {:state_code=>"AL", :fips=>"01001", :name=>"Autauga County", :class_code=>"H1"} }
+```ruby
+FIPS::State.lookup(fips: "02")
+FIPS::State.lookup(state: "AK")
+FIPS::State.lookup(state: "Alaska")
+FIPS::State.lookup(state: "01785533") # ANSI code
 ```
-<br>
-<hr>
 
-### State / County lookup using FIPS code [.fips_county(fips: "fips", return_nil: _return_nil=false_)](/fips_lookup/lib/fips_lookup.rb?#L38)
+The returned state hash has `:fips`, `:abbr`, `:name`, and `:ansi` keys. `FIPS::State.all` returns all state records in the same format:
 
-Input the 5 digit FIPS code for a county and return the county name and state name in an Array:
-```
-FipsLookup.fips_county(fips: "01001") # => ["Autauga County", "AL"]
+```ruby
+FIPS::State.all.map { |state| [state[:name], state[:abbr]] }
 ```
 
-* `fips` - (String) must be a 5 character string of numbers ex: "01001".
-* `return_nil` - (Boolean) is an optional parameter that when used overrides any Errors from input and returns `nil`.
-    * Ex: `FipsLookup.fips_county(fips: "03000", return_nil: true) # => nil`
+### County lookup
 
-<br>
-<hr>
+```ruby
+FIPS::County.lookup(fips: "02060")
+FIPS::County.lookup(fips: "060", state: "AK")
+FIPS::County.lookup(fips: "02", county: "Bristol Bay Borough")
+FIPS::County.lookup(state: "Alaska", county: "Bristol Bay Borough")
+```
 
-### State info from lookup [.state(state_param: "state", _return_nil: false_)](/fips_lookup/lib/fips_lookup.rb?#L33)
+The returned county hash has `:state_abbr`, `:fips`, `:gnis`, `:name`, `:class_code`, and `:status` keys. State identifiers may be an abbreviation, name, FIPS code, or ANSI code.
 
-Using state information input return a dictionary of values for keys fips, state code, state name, state ansi code.
+To list counties in a state, use `FIPS::County.all`:
 
-```
-FipsLookup.state(state_param: "01") # => {:fips=>"01", :code=>"AL", :name=>"Alabama", :ansi=>"01779775"}
+```ruby
+counties = FIPS::County.all(state: "AK")
+county_names = counties.map { |county| county[:name] }
 ```
 
-* `state_param` - (String) flexible - able to find the state using its' 2 letter abbreviation ("AL"), 2 digit FIPS number ("01"), state name ("Alabama"), or the state ANSI code ("01779775").
-* `return_nil` - (Boolean) is an optional parameter that when used overrides any Errors from input and returns an empty hash `{}`.
+### Subdivision lookup
 
-* `.state` functions similarly to the `.county` method in how it uses a memoized hash `@state_fips` to store state parameter lookups and return values before searching `state.csv` for more.
-
-**State code lookup hash** [`STATE_CODES["state code"] # => "fips code"`](/fips_lookup/lib/fips_lookup.rb?#L8)
-Can also be used for quick lookup translation between state 2-character abbreviations and state 2-digit FIPS code.
-```
-FipsLookup::STATE_CODES["AL"] #=> "01"
-FipsLookup::STATE_CODES.key("01") # => "AL"
+```ruby
+FIPS::Subdivision.lookup(fips: "0206009050")
+FIPS::Subdivision.lookup(fips: "09050", state: "AK")
+FIPS::Subdivision.lookup(fips: "02060", subdivision: "Bristol Bay census subarea")
+FIPS::Subdivision.lookup(fips: "060", state: "AK",
+                         subdivision: "Bristol Bay census subarea")
+FIPS::Subdivision.lookup(state: "Alaska", county: "Bristol Bay Borough",
+                         subdivision: "Bristol Bay census subarea")
 ```
-<br>
-<hr>
 
-### Finding state abbreviation with flexible input [.find_state_code(state_param: "state", _return_nil: false_)](/fips_lookup/lib/fips_lookup.rb?#L52)
+The returned subdivision hash has `:state_abbr`, `:fips`, `:county_name`, `:gnis`, `:name`, `:class_code`, and `:status` keys. To retrieve subdivision records for a state, optionally filtered by county:
 
-* `state_param` - (String) flexible - able to find the state using its' 2 letter abbreviation ("AL"), 2 digit FIPS number ("01"), state name ("Alabama"), or the state ANSI code ("01779775").
-* `return_nil` - (Boolean) is an optional parameter that when used overrides any Errors from input and returns nil.
-
-```
-FipsLookup.find_state_code(state_param: "MicHiGan") # => "MI"
+```ruby
+FIPS::Subdivision.all(state: "AK")
+FIPS::Subdivision.all(state: "AK", county: "Bristol Bay Borough")
 ```
 
-<br>
-<hr>
+County and subdivision name matching is case-insensitive. State identifiers accept abbreviations, names, FIPS codes, and ANSI codes.
 
-## Accessing county and state `.csv` files in your Rails app
+### Source data
 
-Data `csv` files are made accessible incase extra configuration is needed. Here is an example in a Rails application that displays the list of state and county names within a form. This is done by accessing the CSV files included in this gem, examples below are from Rails 7 app called [Build With](https://github.com/3barroso/build_with)
+The raw and intermediate CSV datasets are retained under `source_data/` for rebuilding and auditing. They are development inputs, are not used at runtime, and are not included in the published gem. Runtime lookups and collection methods use the bundled SQLite database.
 
-### Path to state.csv file [.state_file](/fips_lookup/lib/fips_lookup.rb?#L64)
+### Database build
 
-Display state codes in a select option dropdown by using CSV on the FipsLookup method accessing the state.csv file ( `FipsLookup.state_file #=> "path/to/data/state.csv"` )
-
-```
-# in controller.rb
-@state_options = []
-CSV.foreach(FipsLookup.state_file) do |state_row|
-    @state_options << [state_row[2], state_row[1]]
-end
-```
+The checked-in schema is in `db/schema.sql`. The bundled database is built from the 2020 Census county and county-subdivision source files. To rebuild it from the source text files and state data, run:
 
+```sh
+bundle exec ruby bin/db/build
 ```
-# in html.erb (within `form_with do |form|` block)
-<%= form.label :state, style: "display: block" %>
-<%= form.select :state, @state_options %>
-```
-
-### Path to state specific county csv files [.county_file(state_code: "state param")](/fips_lookup/lib/fips_lookup.rb?#L59)
 
-Display County name options in a select option dropdown by using CSV on the FipsLookup method accessing the county specific .csv file ( `FipsLookup.county_file(state_code: "MI") #=> "path/to/data/county/MI.csv"` )
+### Errors
 
-* `state_param` – strict parameter, must be string abbreviation of State code (suggested usage is to call `.find_state_code` above first)
+Malformed or insufficient inputs raise `ArgumentError`. Validly formatted identifiers that do not match a record raise `FIPS::NotFoundError`, a subclass of `StandardError`:
 
-```
-# in controller.rb
-state_code = address_params[:state] # or use find_state_code from user input
-@county_options = []
-CSV.foreach(FipsLookup.county_file(state_code:)) do |county_row|
-    @county_options << county_row[3]
+```ruby
+begin
+  FIPS::County.lookup(fips: "02999")
+rescue FIPS::NotFoundError => error
+  warn error.message
 end
 ```
 
-```
-# in html.erb (within `form_with do |form|` block)
-<%= form.label :county, style: "display: block" %>
-<%= form.select :county, @county_options %>
-```
-
 ## Development
 
-Download the repository locally, and from the directory run `bin/setup` to install gem dependencies.
-
-Check installation and any changes by running `rspec` to run the tests. 
-
-Use `bin/console` to open IRB console with FIPS gem included and ready to use.
-
-To install this gem onto your local machine, run `bundle exec rake install`. 
-
-To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Install dependencies with `bin/setup`. Run tests and lint with:
 
-### New to Ruby?
-On Mac, follow steps 1 and 2 of [this guide](https://www.digitalocean.com/community/tutorials/how-to-install-ruby-on-rails-with-rbenv-on-macos) to install ruby with rbenv using brew.
-
-For PC, consult official ruby language [installation guides](https://www.ruby-lang.org/en/documentation/installation/).
-
-#### New to this gem?
-
-* The main working file is `lib/fips_lookup.rb` with usage examples in the test file: `spec/fips_lookup_spec.rb`
-* [The first pull request](https://github.com/3barroso/fips_lookup/pull/1) contains more details to decisions and considerations when first launching gem.
+```sh
+bundle exec rspec
+bundle exec rubocop
+```
 
+Open an IRB console with `bin/console`. Install locally with `bundle exec rake install`.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at the [FIPS repo](https://github.com/3barroso/fips_lookup).
-This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/3barroso/fips_lookup/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome in the [FIPS repository](https://github.com/3barroso/fips_lookup). Contributors are expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the FIPS project's codebase, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/3barroso/fips_lookup/blob/main/CODE_OF_CONDUCT.md).
+This gem is available under the terms of the MIT License. See [LICENSE.txt](LICENSE.txt).

data/db/schema.sql

@@ -0,0 +1,45 @@
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE states (
+  state_fips TEXT PRIMARY KEY,
+  state_abbr TEXT NOT NULL UNIQUE,
+  name TEXT NOT NULL,
+  name_key TEXT NOT NULL,
+  ansi TEXT NOT NULL UNIQUE
+);
+
+CREATE INDEX states_name_key_idx ON states(name_key);
+
+CREATE TABLE counties (
+  state_fips TEXT NOT NULL,
+  county_fips TEXT NOT NULL,
+  full_fips TEXT NOT NULL UNIQUE,
+  name TEXT NOT NULL,
+  name_key TEXT NOT NULL,
+  gnis TEXT NOT NULL,
+  class_code TEXT NOT NULL,
+  status TEXT NOT NULL,
+  PRIMARY KEY (state_fips, county_fips),
+  FOREIGN KEY (state_fips) REFERENCES states(state_fips)
+);
+
+CREATE INDEX counties_state_name_idx ON counties(state_fips, name_key);
+
+CREATE TABLE subdivisions (
+  full_fips TEXT PRIMARY KEY,
+  state_fips TEXT NOT NULL,
+  county_fips TEXT NOT NULL,
+  subdivision_fips TEXT NOT NULL,
+  name TEXT NOT NULL,
+  name_key TEXT NOT NULL,
+  gnis TEXT NOT NULL,
+  class_code TEXT NOT NULL,
+  status TEXT NOT NULL,
+  UNIQUE (state_fips, county_fips, subdivision_fips),
+  FOREIGN KEY (state_fips, county_fips) REFERENCES counties(state_fips, county_fips)
+);
+
+CREATE INDEX subdivisions_state_subdivision_fips_idx
+  ON subdivisions(state_fips, subdivision_fips);
+CREATE INDEX subdivisions_county_name_idx
+  ON subdivisions(state_fips, county_fips, name_key);

data/lib/fips/county.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# FIPS::County
+module FIPS
+  class County
+    extend FIPS::Database::Access
+
+    class << self
+      def lookup(**params)
+        fips = params.fetch(:fips, nil)
+        state = params.fetch(:state, nil)
+        county = params.fetch(:county, nil)
+
+        unless fips.nil? || (fips.is_a?(String) && fips.match?(/\A(?:\d{2}|\d{3}|\d{5})\z/))
+          raise ArgumentError, "FIPS input must be a 2, 3, or 5 digit string"
+        end
+        raise ArgumentError, "State input must be a non-empty string" unless state.nil? || (state.is_a?(String) && !state.strip.empty?)
+        raise ArgumentError, "County input must be a non-empty string" unless county.nil? || (county.is_a?(String) && !county.strip.empty?)
+
+        location = identify_with_fips(fips, state, county)
+        return location unless location.nil?
+
+        if !county.nil? && !state.nil?
+          state_fips = FIPS::State.lookup(state: state)[:fips]
+          return by_name(state_fips, county)
+        end
+
+        raise ArgumentError, "Could not identify county with parameters provided: #{params.inspect}"
+      end
+
+      def all(state:)
+        raise ArgumentError, "State input must be a non-empty string" unless state.is_a?(String) && !state.strip.empty?
+
+        state_fips = FIPS::State.lookup(state: state)[:fips]
+        rows = db_all(
+          "SELECT states.state_abbr AS state_abbr, counties.full_fips AS fips, counties.gnis, counties.name, counties.class_code, counties.status " \
+          "FROM counties JOIN states USING (state_fips) WHERE counties.state_fips = ? ORDER BY counties.county_fips",
+          [state_fips]
+        )
+        rows.map { |county_row| formatted_county(county_row) }
+      end
+
+      private
+
+      def identify_with_fips(fips, state, county)
+        return nil if fips.nil? || !fips.is_a?(String)
+
+        case fips.length
+        when 2
+          return nil if county.nil?
+
+          return by_name(fips, county)
+        when 3
+          return nil if state.nil?
+
+          state_fips = FIPS::State.lookup(state: state)[:fips]
+          return by_fips(state_fips + fips)
+        when 5
+          return by_fips(fips)
+        end
+        nil
+      end
+
+      def by_fips(fips)
+        county_row = db_first(
+          "SELECT states.state_abbr AS state_abbr, counties.full_fips AS fips, counties.gnis, counties.name, counties.class_code, counties.status " \
+          "FROM counties JOIN states USING (state_fips) WHERE counties.full_fips = ?",
+          [fips]
+        )
+        return formatted_county(county_row) unless county_row.nil?
+
+        raise FIPS::NotFoundError, "Could not identify county with fips: #{fips}"
+      end
+
+      def by_name(state_fips, county)
+        county_row = db_first(
+          "SELECT states.state_abbr AS state_abbr, counties.full_fips AS fips, counties.gnis, counties.name, counties.class_code, counties.status " \
+          "FROM counties JOIN states USING (state_fips) WHERE counties.state_fips = ? AND counties.name_key = ?",
+          [state_fips, county.upcase]
+        )
+        return formatted_county(county_row) unless county_row.nil?
+
+        raise FIPS::NotFoundError, "Could not identify county with name: #{county}, in: #{state_fips}"
+      end
+
+      def formatted_county(row)
+        {
+          state_abbr: row["state_abbr"],
+          fips: row["fips"],
+          gnis: row["gnis"],
+          name: row["name"],
+          class_code: row["class_code"],
+          status: row["status"]
+        }
+      end
+    end
+  end
+end

data/lib/fips/database.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "sqlite3"
+
+module FIPS
+  module Database
+    DB_PATH = File.expand_path("../data/fips.sqlite3", __dir__).freeze
+
+    module Access
+      private
+
+      def db_all(sql, bind_params = [])
+        Client.all(sql, bind_params)
+      end
+
+      def db_first(sql, bind_params = [])
+        Client.first(sql, bind_params)
+      end
+    end
+
+    class Client
+      class << self
+        def all(sql, bind_params = [])
+          synchronize { connection.execute(sql, bind_params) }
+        end
+
+        def first(sql, bind_params = [])
+          synchronize { connection.get_first_row(sql, bind_params) }
+        end
+
+        private
+
+        def synchronize(&)
+          mutex.synchronize(&)
+        end
+
+        def mutex
+          @mutex ||= Mutex.new
+        end
+
+        def connection
+          @connection ||= begin
+            raise LoadError, "FIPS SQLite database is missing at #{DB_PATH}; run bin/db/build" unless File.file?(DB_PATH)
+
+            database = SQLite3::Database.new(DB_PATH, readonly: true)
+            database.results_as_hash = true
+            database
+          end
+        end
+      end
+    end
+
+    private_constant :Client
+  end
+end