sqlpkg 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ba14bd48fabc5204acf5de9c6531867fbd3fdd235af9512937e04973705c7b8
-  data.tar.gz: 2a89534503c41d89b5e1dc4bbc4c24253b28ede109dd6e80c63a0339cffad4c3
+  metadata.gz: b0c9c714e0a4480503fadf4f5d9cd654478c4c10ba5bdfde03035e86543eeb7c
+  data.tar.gz: af68d8822b52b10f5aa3f435bf93aafa0e59d8e10544d20187ed4b587f89f14e
 SHA512:
-  metadata.gz: dfa57df77c905f939e5674ddfbb838efe62c2737cc86274517f022b1a75e932c5b864efc77eae0b5b1f38748aba1a64f7f53cdb1867cc1da3424c13d3939e059
-  data.tar.gz: b076a1665433c47fe8462c42e17ab522e951ad904e5e956b57965d7b4079e7aa43a943fad1325446fc52bb7f2076ab9f73402587f60cdb00c6bba6f72c541e39
+  metadata.gz: c432fe870d61eac54cfcfdf8341d04fb6d54af239f8595b8c61771d881f38596e6b1d868dd3f596f50652655f47ce8ab6fd3a62016e5a5da73af2efd51cde5fb
+  data.tar.gz: 3f2bc354e84debdd142eba7a86f0cdc2d6ce00e77a258604cd92138eeb89d09816e45d60c7e96629fd26943dda1eb8cccefc581f42983787500fb40736ca2ad3

data/README.md

@@ -1,24 +1,78 @@
 # sqlpkg-ruby
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/sqlpkg`. To experiment with that code, run `bin/console` for an interactive prompt.
+[sqlpkg](https://sqlpkg.org/) is the (unofficial) SQLite package registry. This gem provides a Ruby interface to [its CLI](https://github.com/nalgeon/sqlpkg-cli).
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+    $ bundle add sqlpkg
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+    $ gem install sqlpkg
+
+After installing the gem, run the installer:
+
+    $ rails generate sqlpkg:install
+
+The installer does three things:
+
+1. creates an empty `.sqlpkg/` directory, which ensures that `sqlpkg` will run in "project scope" and not "global scope" (see [the `sqlpkg-cli` README](https://github.com/nalgeon/sqlpkg-cli#project-vs-global-scope) for more information)
+2. creates an empty `sqlpkg.lock` file, which `sqlpkg` will use to store information about the installed packages (see [the `sqlpkg-cli` README](https://github.com/nalgeon/sqlpkg-cli#lockfile) for more information)
+3. creates an initializer file at `config/initializers/sqlpkg.rb` which will patch the `SQLite3Adapter` to automatically load the extensions installed in the `.sqlpkg/` directory whenever the database is opened
+
+Once properly integrated into your Rails application, you can install any extension listed on [the `sqlpkg` registry](https://sqlpkg.org/all/) by executing:
+
+    $ bundle exec sqlpkg install PACKAGE_IDENTIFIER
+
+When exploring the [the `sqlpkg` registry](https://sqlpkg.org/all/), the `PACKAGE_IDENTIFIER` needed to install an extension is the title found in the cards, always in `owner/name` format.
+
+This gem wraps the standalone executable version of the [sqlpkg-cli](https://github.com/nalgeon/sqlpkg-cli#download-and-install-preferred-method). These executables are platform specific, so there are actually separate underlying gems per platform, but the correct gem will automatically be picked for your platform.
+
+Supported platforms are:
+
+* arm64-darwin (macos-arm64)
+* x86_64-darwin (macos-x64)
+* arm64-linux (linux-arm64)
+* x86_64-linux (linux-x64)
+
+### Using a local installation of `sqlpkg`
+
+If you are not able to use the vendored standalone executables (for example, if you're on an unsupported platform), you can use a local installation of the `sqlpkg` executable by setting an environment variable named `SQLPKG_INSTALL_DIR` to the directory containing the executable.
+
+For example, if you've installed `sqlpkg` so that the executable is found at `/usr/local/bin/sqlpkg`, then you should set your environment variable like so:
+
+``` sh
+SQLPKG_INSTALL_DIR=/usr/local/bin
+```
+
+This also works with relative paths. If you've installed into your app's directory at `./.bin/sqlpkg`:
+
+``` sh
+SQLPKG_INSTALL_DIR=.bin
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+```shell
+$ bundle exec sqlpkg help
+┌────────────────────────────────────────────────┐
+│ sqlpkg is an SQLite package manager.           │
+│ Use it to install or update SQLite extensions. │
+│                                                │
+│ Commands:                                      │
+│ help       Display help                        │
+│ info       Display package information         │
+│ init       Init project scope                  │
+│ install    Install packages                    │
+│ list       List installed packages             │
+│ uninstall  Uninstall package                   │
+│ update     Update installed packages           │
+│ version    Display version                     │
+│ which      Display path to extension file      │
+└────────────────────────────────────────────────┘
+```
 
 ## Development
 

data/exe/sqlpkg

@@ -1,13 +1,13 @@
 #! /usr/bin/env ruby
 # because rubygems shims assume a gem's executables are Ruby
 
-require "litestream/commands"
+require "sqlpkg/commands"
 
 begin
-  command = [Litestream::Commands.executable, *ARGV]
+  command = [Sqlpkg::Commands.executable, *ARGV]
   puts command.inspect
   exec(*command)
-rescue Litestream::Commands::UnsupportedPlatformException, Litestream::Commands::ExecutableNotFoundException => e
+rescue Sqlpkg::Commands::UnsupportedPlatformException, Sqlpkg::Commands::ExecutableNotFoundException => e
   warn("ERROR: " + e.message)
   exit 1
 end

data/lib/sqlpkg/generators/sqlpkg/install_generator.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Sqlpkg
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def ensure_sqlpkg_project_scope_directory
+        empty_directory ".sqlpkg"
+      end
+
+      def create_empty_sqlpkg_lockfile
+        create_file "sqlpkg.lock"
+      end
+
+      def copy_initializer_file
+        template "initializer.rb", "config/initializers/sqlpkg.rb"
+      end
+    end
+  end
+end

data/lib/sqlpkg/generators/sqlpkg/templates/initializer.rb

@@ -0,0 +1,15 @@
+module SqlpkgLoader
+  def configure_connection
+    super
+
+    @raw_connection.enable_load_extension(true)
+    Dir.glob(".sqlpkg/**/*.{dll,so,dylib}") do |extension_path|
+      @raw_connection.load_extension(extension_path)
+    end
+    @raw_connection.enable_load_extension(false)
+  end
+end
+
+ActiveSupport.on_load(:active_record_sqlite3adapter) do
+  prepend SqlpkgLoader
+end

data/lib/sqlpkg/railtie.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Sqlpkg
+  class Railtie < ::Rails::Railtie
+    # Load the `sqlpkg:install` generator into the host Rails app
+    generators do
+      require_relative "generators/sqlpkg/install_generator"
+    end
+  end
+end

data/lib/sqlpkg/version.rb

@@ -1,3 +1,3 @@
 module Sqlpkg
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sqlpkg
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Stephen Margheim
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-12-20 00:00:00.000000000 Z
+date: 2023-12-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubyzip
@@ -24,6 +24,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description:
 email:
 - stephen.margheim@gmail.com
@@ -38,6 +66,9 @@ files:
 - exe/sqlpkg
 - lib/sqlpkg.rb
 - lib/sqlpkg/commands.rb
+- lib/sqlpkg/generators/sqlpkg/install_generator.rb
+- lib/sqlpkg/generators/sqlpkg/templates/initializer.rb
+- lib/sqlpkg/railtie.rb
 - lib/sqlpkg/upstream.rb
 - lib/sqlpkg/version.rb
 homepage: https://github.com/fractaledmind/sqlpkg-ruby