Skip to content

Latest commit

 

History

History
132 lines (84 loc) · 4.22 KB

v2.md

File metadata and controls

132 lines (84 loc) · 4.22 KB

Changes in SQLitePCLRaw 2.0

Overview:

  • .NET Standard 2.0
  • Span-ification
  • Dynamic loading of native library
  • Fewer NuGet packages
  • New build system

SQLitePCLRaw 2.0 ("v2") contains minor breaking changes. As of 5 August 2019, the following caveats apply:

  • EF Core 3.0 (currently in preview) requires v2
  • EF Core 2.x is not compatible with v2
  • sqlite-net is (probably) not yet compatible with v2
  • Akavache is (probably) not yet compatible with v2
  • v2 is not yet tested with official SQLCipher builds from Zetetic, but I'm hopeful that it Just Works.

Source-level breaking changes

  • Functions that previously returned a byte[] now return ReadOnlySpan<byte>. Call .ToArray() on the result to get a byte array again. For example:

      byte[] ba = raw.sqlite3_column_blob(stmt, 0).ToArray()
    
  • Functions that previously returned a string now return utf8z, which is a ref struct that wraps a ReadOnlySpan<byte>, which refers to the UTF-8 string provided by the native SQLite library. An extension method utf8_to_string() is provided.

      string s = raw.sqlite3_column_text(stmt, 0).utf8_to_string()
    
  • Delegate types which involve string parameters now also deal in terms of utf8z. The original form is still available with str as a prefix. For example, if you previously used delegate_collation, you now want to use strdelegate_collation.

  • On UWP, sqlite3_win32_set_directory() is no longer called as part of initialization. You have to call it yourself. This can be done either by an enclosing library or the app.

  • The sqlite3_next_stmt() function is now disabled by default. To enable it, call sqlite3.enable_sqlite3_next_stmt(true) immediately after opening the sqlite3 connection.

Platform support breaking changes

  • .NET Standard 2.0 is now required.

  • Support for PCL profiles has been removed.

  • Windows Phone 8 is no longer supported.

  • The minimum supported version of .NET Framework is 4.6.1.

  • The minimum supported version of UWP is Fall Creators Update, 10.0.16299.

  • Due to various tooling and platform problems, Xamarin.Mac support is currently not working.

Packaging changes

  • The naming of the SQLitePCLRaw.lib.* packages has been cleaned up. In general, all builds are in SQLitePCLRaw.lib.e_sqlite3 and SQLitePCLRaw.lib.e_sqlcipher. Builds for iOS and Android are currently in separate packages due to an apparent bug in mono's msbuild (see mono/mono#15569).

  • The SQLitePCLRaw.provider.* packages have been simplified, with fewer packages.

  • Using the SQLitePCLRaw.bundle_* packages should work the same as before.

  • raw.GetNativeLibraryName() returns the name used by the provider when retrieving the native library.

Under the hood changes

  • Typed pointers from SQLite (such as sqlite* and sqlite3_stmt*) are now implemented with SafeHandle.

  • The SQLitePCLRaw.core assembly is no longer bait-and-switch.

  • Functions which takes string parameters now take utf8z. Whenever feasible, an overload is provided for convenience.

  • Functions which takes byte[] parameters now take ReadOnlySpan<byte>. Whenever feasible, an overload is provided for convenience.

  • Wherever possible, loading of native code is now done dynamically instead of with DllImport. The new dynamic provider does the loading of function pointers as delegates, and the job of locating the native code library is done in SQLitePCL.nativelibary (which, on .NET Core 3.0, is a thin wrapper around System.Runtime.InteropServices.NativeLibrary). On platforms where this is problematic, a regular DllImport provider is still used.

  • The unofficial SQLCipher builds are now named e_sqlcipher to more clearly distinguish them from official builds from Zetetic.

  • The e_sqlite3 and e_sqlcipher libraries for Windows are built with Control Flow Guard turned on.

Build system changes

  • SDK style projects

  • csproj files are no longer generated

  • multi-targeting

  • Code generation is now done with t4

  • no sln file

  • Do dotnet run in the build directory to build the whole project and run the tests.

Testing changes

  • Many more test cases

  • Better test integration with the build script

  • Code coverage (AltCover)

Bundled native code

  • SQLite 3.28.0

  • SQLCipher Community 4.2, based on SQLite 3.28.0