Add migration tool

Fixes #1

Author: zombiezen

README.md

@@ -4,17 +4,28 @@
 
 This package provides a low-level Go interface to SQLite 3. It is a fork of
 [`crawshaw.io/sqlite`][] that uses [`modernc.org/sqlite`][]. It aims to be a
-mostly drop-in replacement for `crawshaw.io/sqlite`.
+mostly drop-in replacement for `crawshaw.io/sqlite`. See the [migration docs][]
+for instructions on how to migrate.
 
 [`crawshaw.io/sqlite`]: https://github.com/crawshaw.io/sqlite
 [`modernc.org/sqlite`]: https://pkg.go.dev/modernc.org/sqlite
+[migration docs]: cmd/zombiezen-sqlite-migrate/README.md
 
 ## Install
 
 ```shell
 go get zombiezen.com/go/sqlite
 ```
 
+## Getting Started
+
+If you're creating a new application, see the [package examples][].
+
+If you're looking to switch existing code that uses `crawshaw.io/sqlite`, take
+a look at the [migration docs][].
+
+[package examples]: https://pkg.go.dev/zombiezen.com/go/sqlite#pkg-examples
+
 ## License
 
 Mostly ISC, with some code borrowed from `modernc.org/sqlite`, which is under a

cmd/zombiezen-sqlite-migrate/README.md

@@ -0,0 +1,79 @@
+# Migrating from `crawshaw.io/sqlite`
+
+`zombiezen.com/go/sqlite` is designed to mostly be a drop-in replacement for
+`crawshaw.io/sqlite`. However, there are some incompatible API changes. To aid
+in migrating, I've prepared a program that rewrites Go source code using
+`crawshaw.io/sqlite` to use `zombiezen.com/go/sqlite`.
+
+## Installation
+
+```shell
+go install zombiezen.com/go/sqlite/cmd/zombiezen-sqlite-migrate@latest
+```
+
+## Usage
+
+Preview changes with:
+
+```shell
+zombiezen-sqlite-migrate ./...
+```
+
+And then apply them with:
+
+```shell
+zombiezen-sqlite-migrate -w ./...
+```
+
+## Automatically fixed changes
+
+The `zombiezen-sqlite-migrate` tool automatically makes a number of mechanical
+changes beyond changing the import paths to preserve semantics.
+
+### `ErrorCode` to `ResultCode`
+
+The `crawshaw.io/sqlite.ErrorCode` type actually represents a SQLite
+[result code][], not just error codes. To better capture this, the new type
+is named `zombiezen.com/go/sqlite.ResultCode`.
+
+[result code]: https://sqlite.org/rescode.html
+
+### Friendlier constant names
+
+The constant names in `crawshaw.io/sqlite` are written in upper snake case with
+`SQLITE_` prefixed (e.g. `sqlite.SQLITE_OK`); the constant names in
+`zombiezen.com/go/sqlite` are written in upper camel case with the type prefixed
+(e.g. `sqlite.ResultOK`).
+
+## Changes that require manual effort
+
+Other usages of the `crawshaw.io/sqlite` may require manual effort to migrate,
+but the `zombiezen-sqlite-migrate` tool will point them out.
+
+### Application-Defined Functions
+
+The `crawshaw.io/sqlite.Conn.CreateFunction` method and supporting APIs like
+`Context` and `Value` have been re-tooled in `zombiezen.com/go/sqlite` with
+better ergonomics. See the [`CreateFunction` reference][] for more details.
+
+[`CreateFunction` reference]: https://pkg.go.dev/zombiezen.com/go/sqlite#Conn.CreateFunction
+
+### Removed `Blob` methods
+
+`zombiezen.com/go/sqlite.Blob` does not implement the [`io.ReaderAt`][] or
+[`io.WriterAt`][] interfaces. Technically, neither did `crawshaw.io/sqlite.Blob`,
+because it was not safe to call in parallel, which these interfaces require.
+To avoid these methods being used incorrectly, I removed them.
+
+I also removed the unused embedded interface fields.
+
+[`io.ReaderAt`]: https://pkg.go.dev/io#ReaderAt
+[`io.WriterAt`]: https://pkg.go.dev/io#WriterAt
+
+### No dedicated `sqlite.Error` type
+
+I don't want to commit to a specific error type in `zombiezen.com/go/sqlite`, so
+there I removed the `Error` type. [`zombiezen.com/go/sqlite.ErrCode`][] still
+extracts the `ResultCode` from an `error`, which covers most needs.
+
+[`zombiezen.com/go/sqlite.ErrCode`]: https://pkg.go.dev/zombiezen.com/go/sqlite#ErrCode

cmd/zombiezen-sqlite-migrate/go.mod

@@ -0,0 +1,8 @@
+module zombiezen.com/go/sqlite/cmd/zombiezen-sqlite-migrate
+
+go 1.16
+
+require (
+	golang.org/x/tools v0.1.0
+	zombiezen.com/go/bass v0.0.0-20210402215001-cb0af0b391a4
+)